@epilot/app-client 0.12.5 → 0.12.6

package/dist/openapi.d.ts

@@ -1515,7 +1515,19 @@ declare namespace Components {
              *       - valid: false
              *
              */
-            PortalExtensionHookMeterReadingPlausibilityCheck)[];
+            PortalExtensionHookMeterReadingPlausibilityCheck | /**
+             * Hook that returns runtime metadata describing how a visualization (consumption / price / cost chart) should be rendered for a given portal context (meter, contract, etc). It is invoked by the portal before fetching data, with the same context the data hook would receive, so that the discovery shape can vary per meter/contract. The expected response to the call is:
+             *   - 200 with a JSON body of shape:
+             *     {
+             *       "type_options": [{ "id": "ht", "label": { "en": "High tariff" }, "aggregation_group": "consumption", "unit": "kWh" }, ...],
+             *       "intervals": ["PT15M", "PT1H", "P1D", "P1M"],
+             *       "data_range": { "from": "2024-01-01T00:00:00Z", "to": "2026-05-01T00:00:00Z" }
+             *     }
+             *   All fields are optional; the consumer falls back to its defaults for whatever the hook does not return.
+             * The portal looks up this hook implicitly per extension (one `visualizationMetadata` hook per extension) — there is no need for a data-retrieval hook to reference it explicitly.
+             *
+             */
+            PortalExtensionHookVisualizationMetadata)[];
             links?: {
                 /**
                  * Identifier of the link. Should not change between updates.
@@ -1545,16 +1557,6 @@ declare namespace Components {
                 };
             }[];
         }
-        /**
-         * An aggregation method advertised by a consumption data retrieval hook.
-         */
-        export interface PortalExtensionHookConsumptionAggregationMethodOption {
-            /**
-             * Identifier of the option. Matches the `aggregation_method` value returned by the hook.
-             */
-            id: "sum" | "average" | "min" | "max";
-            label: TranslatedString;
-        }
         /**
          * Hook that will allow using the specified source as data for consumption visualizations. This hook is triggered to fetch the data. Format of the request and response has to follow the following specification: TBD. The expected response to the call is:
          *   - 200 with the time series data
@@ -1568,19 +1570,11 @@ declare namespace Components {
             name?: TranslatedString;
             type: "consumptionDataRetrieval";
             /**
+             * Deprecated. Prefer declaring a sibling `visualizationMetadata` hook on the same extension and returning `intervals` from its response — that way the supported intervals can vary per meter/contract.
              * Intervals supported by the API. If omitted, it is assumed that all intervals are supported.
-             */
-            intervals?: ("PT15M" | "PT1H" | "P1D" | "P1M")[];
-            /**
-             * Consumption types advertised by the hook (e.g. `ht`/`nt`, `feed-in`/`feed-out`). The `id` has to match the `type` field returned in the consumption response.
              *
              */
-            type_options?: /* A consumption type advertised by a consumption data retrieval hook. */ PortalExtensionHookConsumptionOption[];
-            /**
-             * Aggregation methods advertised by the hook (e.g. `sum`, `average`, `min`, `max`). The `id` has to match the `aggregation_method` field returned in the consumption response.
-             *
-             */
-            aggregation_method_options?: /* An aggregation method advertised by a consumption data retrieval hook. */ PortalExtensionHookConsumptionAggregationMethodOption[];
+            intervals?: ("PT15M" | "PT1H" | "P1D" | "P1M")[];
             auth?: PortalExtensionAuthBlock;
             call: {
                 /**
@@ -1624,23 +1618,6 @@ declare namespace Components {
             use_static_ips?: boolean;
             secure_proxy?: /* If set, requests are routed through the ERP Integration secure proxy. Mutually exclusive with use_static_ips. */ PortalExtensionSecureProxy;
         }
-        /**
-         * A consumption type advertised by a consumption data retrieval hook.
-         */
-        export interface PortalExtensionHookConsumptionOption {
-            /**
-             * Identifier of the option. Matches the `type` value returned by the hook (e.g. `ht`, `nt`, `feed-in`).
-             */
-            id: string;
-            label: TranslatedString;
-            /**
-             * Optional grouping key. Types sharing the same aggregation_group are interpreted as values that can be aggregated (e.g. ht/nt shown as a stacked bar chart - summed into total consumption per interval). Types in different groups — or types without a group — are not (e.g. feed-in vs feed-out shown as separate bars).
-             *
-             * example:
-             * consumption
-             */
-            aggregation_group?: string;
-        }
         /**
          * Hook that replaces the built-in Contract identification for self-assignment. This hook involves an HTTP request whenever a user is trying to self-assign Contract(s).
          * The expected response http status code to the call is:
@@ -1738,7 +1715,9 @@ declare namespace Components {
             name?: TranslatedString;
             type: "costDataRetrieval";
             /**
+             * Deprecated. Prefer declaring a sibling `visualizationMetadata` hook on the same extension and returning `intervals` from its response — that way the supported intervals can vary per meter/contract.
              * Intervals supported by the API. If omitted, it is assumed that all intervals are supported.
+             *
              */
             intervals?: ("PT15M" | "PT1H" | "P1D" | "P1M")[];
             auth?: PortalExtensionAuthBlock;
@@ -1796,6 +1775,14 @@ declare namespace Components {
             id: string; // ^[a-zA-Z0-9_-]+$
             name?: TranslatedString;
             type: "dataExport";
+            /**
+             * Optional list of portal block types this hook supports. If omitted,
+             * the hook is usable on any export-capable block. Allowed values match
+             * the block type identifiers used by the portal builder
+             * (e.g. `consumption_visualization`, `dynamic_tariff`).
+             *
+             */
+            block_types?: string[];
             auth?: PortalExtensionAuthBlock;
             call: {
                 /**
@@ -1942,7 +1929,9 @@ declare namespace Components {
             name?: TranslatedString;
             type: "priceDataRetrieval";
             /**
+             * Deprecated. Prefer declaring a sibling `visualizationMetadata` hook on the same extension and returning `intervals` from its response — that way the supported intervals can vary per meter/contract.
              * Intervals supported by the API. If omitted, it is assumed that all intervals are supported.
+             *
              */
             intervals?: ("PT15M" | "PT1H" | "P1D" | "P1M")[];
             auth?: PortalExtensionAuthBlock;
@@ -2042,6 +2031,68 @@ declare namespace Components {
             use_static_ips?: boolean;
             secure_proxy?: /* If set, requests are routed through the ERP Integration secure proxy. Mutually exclusive with use_static_ips. */ PortalExtensionSecureProxy;
         }
+        /**
+         * Hook that returns runtime metadata describing how a visualization (consumption / price / cost chart) should be rendered for a given portal context (meter, contract, etc). It is invoked by the portal before fetching data, with the same context the data hook would receive, so that the discovery shape can vary per meter/contract. The expected response to the call is:
+         *   - 200 with a JSON body of shape:
+         *     {
+         *       "type_options": [{ "id": "ht", "label": { "en": "High tariff" }, "aggregation_group": "consumption", "unit": "kWh" }, ...],
+         *       "intervals": ["PT15M", "PT1H", "P1D", "P1M"],
+         *       "data_range": { "from": "2024-01-01T00:00:00Z", "to": "2026-05-01T00:00:00Z" }
+         *     }
+         *   All fields are optional; the consumer falls back to its defaults for whatever the hook does not return.
+         * The portal looks up this hook implicitly per extension (one `visualizationMetadata` hook per extension) — there is no need for a data-retrieval hook to reference it explicitly.
+         *
+         */
+        export interface PortalExtensionHookVisualizationMetadata {
+            /**
+             * Identifier of the hook. Should not change between updates.
+             */
+            id: string; // ^[a-zA-Z0-9_-]+$
+            name?: TranslatedString;
+            type: "visualizationMetadata";
+            auth?: PortalExtensionAuthBlock;
+            call: {
+                /**
+                 * HTTP method to use for the call
+                 */
+                method?: string;
+                /**
+                 * URL to call. Supports variable interpolation.
+                 */
+                url: string;
+                /**
+                 * Parameters to append to the URL. Supports variable interpolation.
+                 */
+                params?: {
+                    [name: string]: string;
+                };
+                /**
+                 * Headers to use. Supports variable interpolation.
+                 */
+                headers?: {
+                    [name: string]: string;
+                };
+                /**
+                 * Request body to send. Supports variable interpolation. Content format is determined by Content-Type header.
+                 */
+                body?: {
+                    [name: string]: any;
+                };
+            };
+            resolved?: {
+                /**
+                 * Optional path to the metadata object in the response. If omitted, the metadata is assumed to be on the top level.
+                 */
+                dataPath?: string;
+            };
+            /**
+             * Deprecated. Prefer `secure_proxy` instead.
+             * 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.
+             *
+             */
+            use_static_ips?: boolean;
+            secure_proxy?: /* If set, requests are routed through the ERP Integration secure proxy. Mutually exclusive with use_static_ips. */ PortalExtensionSecureProxy;
+        }
         export interface PortalExtensionSeamlessLink {
             /**
              * Identifier of the link. Should not change between updates.
@@ -3611,15 +3662,14 @@ export type PortalBlockSurfaceConfig = Components.Schemas.PortalBlockSurfaceConf
 export type PortalExtensionAuthBlock = Components.Schemas.PortalExtensionAuthBlock;
 export type PortalExtensionComponent = Components.Schemas.PortalExtensionComponent;
 export type PortalExtensionConfig = Components.Schemas.PortalExtensionConfig;
-export type PortalExtensionHookConsumptionAggregationMethodOption = Components.Schemas.PortalExtensionHookConsumptionAggregationMethodOption;
 export type PortalExtensionHookConsumptionDataRetrieval = Components.Schemas.PortalExtensionHookConsumptionDataRetrieval;
-export type PortalExtensionHookConsumptionOption = Components.Schemas.PortalExtensionHookConsumptionOption;
 export type PortalExtensionHookContractIdentification = Components.Schemas.PortalExtensionHookContractIdentification;
 export type PortalExtensionHookCostDataRetrieval = Components.Schemas.PortalExtensionHookCostDataRetrieval;
 export type PortalExtensionHookDataExport = Components.Schemas.PortalExtensionHookDataExport;
 export type PortalExtensionHookMeterReadingPlausibilityCheck = Components.Schemas.PortalExtensionHookMeterReadingPlausibilityCheck;
 export type PortalExtensionHookPriceDataRetrieval = Components.Schemas.PortalExtensionHookPriceDataRetrieval;
 export type PortalExtensionHookRegistrationIdentifiersCheck = Components.Schemas.PortalExtensionHookRegistrationIdentifiersCheck;
+export type PortalExtensionHookVisualizationMetadata = Components.Schemas.PortalExtensionHookVisualizationMetadata;
 export type PortalExtensionSeamlessLink = Components.Schemas.PortalExtensionSeamlessLink;
 export type PortalExtensionSecureProxy = Components.Schemas.PortalExtensionSecureProxy;
 export type Pricing = Components.Schemas.Pricing;

package/dist/openapi.json

@@ -2611,7 +2611,8 @@
                   "consumptionDataRetrieval": "#/components/schemas/PortalExtensionHookConsumptionDataRetrieval",
                   "dataExport": "#/components/schemas/PortalExtensionHookDataExport",
                   "costDataRetrieval": "#/components/schemas/PortalExtensionHookCostDataRetrieval",
-                  "meterReadingPlausibilityCheck": "#/components/schemas/PortalExtensionHookMeterReadingPlausibilityCheck"
+                  "meterReadingPlausibilityCheck": "#/components/schemas/PortalExtensionHookMeterReadingPlausibilityCheck",
+                  "visualizationMetadata": "#/components/schemas/PortalExtensionHookVisualizationMetadata"
                 }
               },
               "oneOf": [
@@ -2635,6 +2636,9 @@
                 },
                 {
                   "$ref": "#/components/schemas/PortalExtensionHookMeterReadingPlausibilityCheck"
+                },
+                {
+                  "$ref": "#/components/schemas/PortalExtensionHookVisualizationMetadata"
                 }
               ]
             }
@@ -2981,7 +2985,8 @@
           },
           "intervals": {
             "type": "array",
-            "description": "Intervals supported by the API. If omitted, it is assumed that all intervals are supported.",
+            "deprecated": true,
+            "description": "Deprecated. Prefer declaring a sibling `visualizationMetadata` hook on the same extension and returning `intervals` from its response — that way the supported intervals can vary per meter/contract.\nIntervals supported by the API. If omitted, it is assumed that all intervals are supported.\n",
             "items": {
               "type": "string",
               "enum": [
@@ -3081,7 +3086,8 @@
           },
           "intervals": {
             "type": "array",
-            "description": "Intervals supported by the API. If omitted, it is assumed that all intervals are supported.",
+            "deprecated": true,
+            "description": "Deprecated. Prefer declaring a sibling `visualizationMetadata` hook on the same extension and returning `intervals` from its response — that way the supported intervals can vary per meter/contract.\nIntervals supported by the API. If omitted, it is assumed that all intervals are supported.\n",
             "items": {
               "type": "string",
               "enum": [
@@ -3092,20 +3098,6 @@
               ]
             }
           },
-          "type_options": {
-            "type": "array",
-            "description": "Consumption types advertised by the hook (e.g. `ht`/`nt`, `feed-in`/`feed-out`). The `id` has to match the `type` field returned in the consumption response.\n",
-            "items": {
-              "$ref": "#/components/schemas/PortalExtensionHookConsumptionOption"
-            }
-          },
-          "aggregation_method_options": {
-            "type": "array",
-            "description": "Aggregation methods advertised by the hook (e.g. `sum`, `average`, `min`, `max`). The `id` has to match the `aggregation_method` field returned in the consumption response.\n",
-            "items": {
-              "$ref": "#/components/schemas/PortalExtensionHookConsumptionAggregationMethodOption"
-            }
-          },
           "auth": {
             "$ref": "#/components/schemas/PortalExtensionAuthBlock"
           },
@@ -3193,6 +3185,13 @@
               "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/PortalExtensionAuthBlock"
           },
@@ -3252,50 +3251,90 @@
         ],
         "additionalProperties": false
       },
-      "PortalExtensionHookConsumptionOption": {
+      "PortalExtensionHookVisualizationMetadata": {
+        "description": "Hook that returns runtime metadata describing how a visualization (consumption / price / cost chart) should be rendered for a given portal context (meter, contract, etc). It is invoked by the portal before fetching data, with the same context the data hook would receive, so that the discovery shape can vary per meter/contract. The expected response to the call is:\n  - 200 with a JSON body of shape:\n    {\n      \"type_options\": [{ \"id\": \"ht\", \"label\": { \"en\": \"High tariff\" }, \"aggregation_group\": \"consumption\", \"unit\": \"kWh\" }, ...],\n      \"intervals\": [\"PT15M\", \"PT1H\", \"P1D\", \"P1M\"],\n      \"data_range\": { \"from\": \"2024-01-01T00:00:00Z\", \"to\": \"2026-05-01T00:00:00Z\" }\n    }\n  All fields are optional; the consumer falls back to its defaults for whatever the hook does not return.\nThe portal looks up this hook implicitly per extension (one `visualizationMetadata` hook per extension) — there is no need for a data-retrieval hook to reference it explicitly.\n",
         "type": "object",
-        "description": "A consumption type advertised by a consumption data retrieval hook.",
         "properties": {
           "id": {
             "type": "string",
-            "description": "Identifier of the option. Matches the `type` value returned by the hook (e.g. `ht`, `nt`, `feed-in`)."
+            "pattern": "^[a-zA-Z0-9_-]+$",
+            "description": "Identifier of the hook. Should not change between updates."
           },
-          "label": {
+          "name": {
             "$ref": "#/components/schemas/TranslatedString"
           },
-          "aggregation_group": {
-            "type": "string",
-            "description": "Optional grouping key. Types sharing the same aggregation_group are interpreted as values that can be aggregated (e.g. ht/nt shown as a stacked bar chart - summed into total consumption per interval). Types in different groups — or types without a group — are not (e.g. feed-in vs feed-out shown as separate bars).\n",
-            "example": "consumption"
-          }
-        },
-        "required": [
-          "id",
-          "label"
-        ],
-        "additionalProperties": false
-      },
-      "PortalExtensionHookConsumptionAggregationMethodOption": {
-        "type": "object",
-        "description": "An aggregation method advertised by a consumption data retrieval hook.",
-        "properties": {
-          "id": {
+          "type": {
             "type": "string",
             "enum": [
-              "sum",
-              "average",
-              "min",
-              "max"
+              "visualizationMetadata"
+            ]
+          },
+          "auth": {
+            "$ref": "#/components/schemas/PortalExtensionAuthBlock"
+          },
+          "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": true
+              }
+            },
+            "required": [
+              "url"
             ],
-            "description": "Identifier of the option. Matches the `aggregation_method` value returned by the hook."
+            "additionalProperties": false
           },
-          "label": {
-            "$ref": "#/components/schemas/TranslatedString"
+          "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."
+              }
+            },
+            "additionalProperties": false
+          },
+          "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/PortalExtensionSecureProxy"
           }
         },
         "required": [
           "id",
-          "label"
+          "type",
+          "call"
         ],
         "additionalProperties": false
       },
@@ -3319,7 +3358,8 @@
           },
           "intervals": {
             "type": "array",
-            "description": "Intervals supported by the API. If omitted, it is assumed that all intervals are supported.",
+            "deprecated": true,
+            "description": "Deprecated. Prefer declaring a sibling `visualizationMetadata` hook on the same extension and returning `intervals` from its response — that way the supported intervals can vary per meter/contract.\nIntervals supported by the API. If omitted, it is assumed that all intervals are supported.\n",
             "items": {
               "type": "string",
               "enum": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@epilot/app-client",
-  "version": "0.12.5",
+  "version": "0.12.6",
   "description": "JavaScript client library for the epilot App API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",