@epilot/app-client 0.12.8 → 0.13.1

package/dist/openapi.d.ts

@@ -1338,15 +1338,44 @@ declare namespace Components {
             events?: NotificationEvent[];
         }
         export type NotificationEvent = "app.installed" | "app.uninstalled";
+        /**
+         * One declared field inside a `type: object` option. Fields are primitives — object nesting
+         * is not supported.
+         *
+         */
+        export interface ObjectField {
+            /**
+             * Unique identifier for this field within the parent object.
+             */
+            key: string;
+            /**
+             * Human-readable label for the field.
+             */
+            label?: string;
+            /**
+             * Detailed description of what this field is for.
+             */
+            description?: string;
+            /**
+             * Flag to indicate if this field must be filled.
+             */
+            required?: boolean;
+            /**
+             * Primitive type of this field.
+             */
+            type: "text" | "number" | "boolean" | "secret";
+        }
         export interface Option {
             /**
              * Key matching a config_option from the component
              */
             key: string;
             /**
-             * The configured value for this option
+             * The configured value for this option. Shape depends on the matching component option's
+             * `type` and `repeatable` (see `Options.value`).
+             *
              */
-            value: string | boolean | number;
+            value: any;
         }
         /**
          * Options for the component configuration
@@ -1369,10 +1398,41 @@ declare namespace Components {
              */
             description?: string;
             /**
-             * The configured value for this option. Is only present when the component is installed.
+             * When true, the configured value is an array of entries, each tagged with a stable
+             * server-assigned `id`. Combine with any `type` to express "many of this thing."
+             * Defaults to false.
+             *
              */
-            value?: string | boolean | number;
-            type: "text" | "number" | "boolean" | "secret";
+            repeatable?: boolean;
+            /**
+             * Field declarations — required when `type: object`. Each entry describes one primitive
+             * sub-field of the object value. Object types may not nest (no `type: object` inside `fields`).
+             *
+             */
+            fields?: /**
+             * One declared field inside a `type: object` option. Fields are primitives — object nesting
+             * is not supported.
+             *
+             */
+            ObjectField[];
+            /**
+             * The configured value for this option. Shape depends on `type` and `repeatable`:
+             * - primitive `type` (text/number/boolean/secret), `repeatable` false → primitive
+             * - primitive `type`, `repeatable` true → array of `{id, value}` entries
+             * - `type: object`, `repeatable` false → object with declared fields
+             * - `type: object`, `repeatable` true → array of `{id, ...declared fields}` entries
+             *
+             * `id` is server-assigned and stable across edits so consumers can reference entries
+             * by id rather than by index.
+             *
+             */
+            value?: any;
+            /**
+             * The type of this option. `object` declares a structured value whose fields are listed
+             * under `fields`. Combine with `repeatable: true` to express a list of these objects.
+             *
+             */
+            type: "text" | "number" | "boolean" | "secret" | "object";
         }
         export interface OptionsRef {
             /**
@@ -1520,15 +1580,14 @@ declare namespace Components {
              *   - 200 with a JSON body of shape:
              *     {
              *       "type_options": [
-             *         { "id": "feed-out", "label": { "en": "Grid import" }, "aggregation_group": "grid", "statistical_method": "sum", "direction": "out", "unit": "kWh" },
-             *         { "id": "feed-in",  "label": { "en": "Feed-in"     }, "aggregation_group": "grid", "statistical_method": "sum", "direction": "in",  "unit": "kWh" },
+             *         { "id": "ht", "label": { "en": "High tariff" }, "aggregation_group": "consumption", "statistical_method": "sum", "unit": "kWh", "color": "primary", "precision": 2 },
              *         ...
              *       ],
              *       "intervals": ["PT15M", "PT1H", "P1D", "P1M"],
              *       "data_range": { "from": "2024-01-01T00:00:00Z", "to": "2026-05-01T00:00:00Z" }
              *     }
              *   Each type option carries its own `statistical_method`, which describes the method already applied to that type's data and dictates the chart shape: `sum` is rendered as a bar chart; `min`, `average`, and `max` are rendered as a line chart. A single visualization can therefore mix bar-shaped types with line-shaped types. Defaults to `sum` when omitted.
-             *   `direction` declares whether a type adds to or subtracts from the period total: `out` is grid-to-consumer (consumption, additive); `in` is consumer-to-grid (export, subtractive). With both present in a prosumer setup the chart computes a *net* consumption per period and can flip its label to "Total production" when the result is negative. Defaults to `out` when omitted.
+             *   Each type option may also customize its rendering: `color` picks a Spark palette color (`primary`, `slate`, `mauve`, `orange`, `red`, `tomato`, `amber`, `green`, `blue`) used to draw the type's series; `precision` sets the number of decimal places to show for that type's values (axis labels, tooltips, summaries). Both are optional — the consumer falls back to its own defaults when they are omitted.
              *   `aggregation_group` controls how types within a group are visually combined (depends on the per-type `statistical_method`):
              *     - bar chart (`sum`): same-group types are stacked into a single bar (e.g. ht/nt summed into total consumption); different-group types render side-by-side.
              *     - line chart (`min` / `average` / `max`): same-group types are rendered as an area chart; different-group types render as separate lines.
@@ -1618,6 +1677,14 @@ declare namespace Components {
                  * Optional path to the data (array) in the response. If omitted, the data is assumed to be on the top level.
                  */
                 dataPath?: string;
+                /**
+                 * Optional path to a human-readable error message in the third-party response body, used when the call fails (non-2xx status).
+                 * If specified and the path resolves to a string, that message is forwarded to the end user instead of a generic error.
+                 *
+                 * example:
+                 * error.message
+                 */
+                errorMessagePath?: string;
             };
             /**
              * Deprecated. Prefer `secure_proxy` instead.
@@ -1763,6 +1830,14 @@ declare namespace Components {
                  * Optional path to the data (array) in the response. If omitted, the data is assumed to be on the top level.
                  */
                 dataPath?: string;
+                /**
+                 * Optional path to a human-readable error message in the third-party response body, used when the call fails (non-2xx status).
+                 * If specified and the path resolves to a string, that message is forwarded to the end user instead of a generic error.
+                 *
+                 * example:
+                 * error.message
+                 */
+                errorMessagePath?: string;
             };
             /**
              * Deprecated. Prefer `secure_proxy` instead.
@@ -1821,6 +1896,16 @@ declare namespace Components {
                     [name: string]: any;
                 };
             };
+            resolved?: {
+                /**
+                 * Optional path to a human-readable error message in the third-party response body, used when the call fails (non-2xx status).
+                 * If specified and the path resolves to a string, that message is forwarded to the end user instead of a generic error.
+                 *
+                 * example:
+                 * error.message
+                 */
+                errorMessagePath?: 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.
@@ -1916,6 +2001,14 @@ declare namespace Components {
                  * {{CallResponse.data.lower_limit}}
                  */
                 lower_limit?: string;
+                /**
+                 * Optional path to a human-readable error message in the third-party response body, used when the call fails (non-2xx status).
+                 * If specified and the path resolves to a string, that message is forwarded to the end user instead of a generic error.
+                 *
+                 * example:
+                 * error.message
+                 */
+                errorMessagePath?: string;
             };
             /**
              * Deprecated. Prefer `secure_proxy` instead.
@@ -1977,6 +2070,14 @@ declare namespace Components {
                  * Optional path to the data (array) in the response. If omitted, the data is assumed to be on the top level.
                  */
                 dataPath?: string;
+                /**
+                 * Optional path to a human-readable error message in the third-party response body, used when the call fails (non-2xx status).
+                 * If specified and the path resolves to a string, that message is forwarded to the end user instead of a generic error.
+                 *
+                 * example:
+                 * error.message
+                 */
+                errorMessagePath?: string;
             };
             /**
              * Deprecated. Prefer `secure_proxy` instead.
@@ -2045,15 +2146,14 @@ declare namespace Components {
          *   - 200 with a JSON body of shape:
          *     {
          *       "type_options": [
-         *         { "id": "feed-out", "label": { "en": "Grid import" }, "aggregation_group": "grid", "statistical_method": "sum", "direction": "out", "unit": "kWh" },
-         *         { "id": "feed-in",  "label": { "en": "Feed-in"     }, "aggregation_group": "grid", "statistical_method": "sum", "direction": "in",  "unit": "kWh" },
+         *         { "id": "ht", "label": { "en": "High tariff" }, "aggregation_group": "consumption", "statistical_method": "sum", "unit": "kWh", "color": "primary", "precision": 2 },
          *         ...
          *       ],
          *       "intervals": ["PT15M", "PT1H", "P1D", "P1M"],
          *       "data_range": { "from": "2024-01-01T00:00:00Z", "to": "2026-05-01T00:00:00Z" }
          *     }
          *   Each type option carries its own `statistical_method`, which describes the method already applied to that type's data and dictates the chart shape: `sum` is rendered as a bar chart; `min`, `average`, and `max` are rendered as a line chart. A single visualization can therefore mix bar-shaped types with line-shaped types. Defaults to `sum` when omitted.
-         *   `direction` declares whether a type adds to or subtracts from the period total: `out` is grid-to-consumer (consumption, additive); `in` is consumer-to-grid (export, subtractive). With both present in a prosumer setup the chart computes a *net* consumption per period and can flip its label to "Total production" when the result is negative. Defaults to `out` when omitted.
+         *   Each type option may also customize its rendering: `color` picks a Spark palette color (`primary`, `slate`, `mauve`, `orange`, `red`, `tomato`, `amber`, `green`, `blue`) used to draw the type's series; `precision` sets the number of decimal places to show for that type's values (axis labels, tooltips, summaries). Both are optional — the consumer falls back to its own defaults when they are omitted.
          *   `aggregation_group` controls how types within a group are visually combined (depends on the per-type `statistical_method`):
          *     - bar chart (`sum`): same-group types are stacked into a single bar (e.g. ht/nt summed into total consumption); different-group types render side-by-side.
          *     - line chart (`min` / `average` / `max`): same-group types are rendered as an area chart; different-group types render as separate lines.
@@ -2102,6 +2202,14 @@ declare namespace Components {
                  * Optional path to the metadata object in the response. If omitted, the metadata is assumed to be on the top level.
                  */
                 dataPath?: string;
+                /**
+                 * Optional path to a human-readable error message in the third-party response body, used when the call fails (non-2xx status).
+                 * If specified and the path resolves to a string, that message is forwarded to the end user instead of a generic error.
+                 *
+                 * example:
+                 * error.message
+                 */
+                errorMessagePath?: string;
             };
             /**
              * Deprecated. Prefer `secure_proxy` instead.
@@ -3670,6 +3778,7 @@ export type JourneyBlockComponentArgs = Components.Schemas.JourneyBlockComponent
 export type JourneyBlockConfig = Components.Schemas.JourneyBlockConfig;
 export type NotificationConfig = Components.Schemas.NotificationConfig;
 export type NotificationEvent = Components.Schemas.NotificationEvent;
+export type ObjectField = Components.Schemas.ObjectField;
 export type Option = Components.Schemas.Option;
 export type Options = Components.Schemas.Options;
 export type OptionsRef = Components.Schemas.OptionsRef;

package/dist/openapi.json

@@ -1842,13 +1842,56 @@
             "type": "string",
             "description": "Detailed description of what this configuration option does"
           },
+          "repeatable": {
+            "type": "boolean",
+            "description": "When true, the configured value is an array of entries, each tagged with a stable\nserver-assigned `id`. Combine with any `type` to express \"many of this thing.\"\nDefaults to false.\n"
+          },
+          "fields": {
+            "type": "array",
+            "description": "Field declarations — required when `type: object`. Each entry describes one primitive\nsub-field of the object value. Object types may not nest (no `type: object` inside `fields`).\n",
+            "items": {
+              "$ref": "#/components/schemas/ObjectField"
+            }
+          },
           "value": {
-            "type": [
-              "string",
+            "description": "The configured value for this option. Shape depends on `type` and `repeatable`:\n- primitive `type` (text/number/boolean/secret), `repeatable` false → primitive\n- primitive `type`, `repeatable` true → array of `{id, value}` entries\n- `type: object`, `repeatable` false → object with declared fields\n- `type: object`, `repeatable` true → array of `{id, ...declared fields}` entries\n\n`id` is server-assigned and stable across edits so consumers can reference entries\nby id rather than by index.\n"
+          },
+          "type": {
+            "type": "string",
+            "enum": [
+              "text",
+              "number",
               "boolean",
-              "number"
+              "secret",
+              "object"
             ],
-            "description": "The configured value for this option. Is only present when the component is installed."
+            "description": "The type of this option. `object` declares a structured value whose fields are listed\nunder `fields`. Combine with `repeatable: true` to express a list of these objects.\n"
+          }
+        }
+      },
+      "ObjectField": {
+        "type": "object",
+        "description": "One declared field inside a `type: object` option. Fields are primitives — object nesting\nis not supported.\n",
+        "required": [
+          "key",
+          "type"
+        ],
+        "properties": {
+          "key": {
+            "type": "string",
+            "description": "Unique identifier for this field within the parent object."
+          },
+          "label": {
+            "type": "string",
+            "description": "Human-readable label for the field."
+          },
+          "description": {
+            "type": "string",
+            "description": "Detailed description of what this field is for."
+          },
+          "required": {
+            "type": "boolean",
+            "description": "Flag to indicate if this field must be filled."
           },
           "type": {
             "type": "string",
@@ -1857,7 +1900,8 @@
               "number",
               "boolean",
               "secret"
-            ]
+            ],
+            "description": "Primitive type of this field."
           }
         }
       },
@@ -1873,12 +1917,7 @@
             "description": "Key matching a config_option from the component"
           },
           "value": {
-            "type": [
-              "string",
-              "boolean",
-              "number"
-            ],
-            "description": "The configured value for this option"
+            "description": "The configured value for this option. Shape depends on the matching component option's\n`type` and `repeatable` (see `Options.value`).\n"
           }
         }
       },
@@ -2943,6 +2982,11 @@
                 "type": "string",
                 "description": "Lower allowed limit of the meter reading",
                 "example": "{{CallResponse.data.lower_limit}}"
+              },
+              "errorMessagePath": {
+                "type": "string",
+                "description": "Optional path to a human-readable error message in the third-party response body, used when the call fails (non-2xx status).\nIf specified and the path resolves to a string, that message is forwarded to the end user instead of a generic error.\n",
+                "example": "error.message"
               }
             },
             "additionalProperties": false
@@ -3045,6 +3089,11 @@
               "dataPath": {
                 "type": "string",
                 "description": "Optional path to the data (array) in the response. If omitted, the data is assumed to be on the top level."
+              },
+              "errorMessagePath": {
+                "type": "string",
+                "description": "Optional path to a human-readable error message in the third-party response body, used when the call fails (non-2xx status).\nIf specified and the path resolves to a string, that message is forwarded to the end user instead of a generic error.\n",
+                "example": "error.message"
               }
             },
             "additionalProperties": false
@@ -3146,6 +3195,11 @@
               "dataPath": {
                 "type": "string",
                 "description": "Optional path to the data (array) in the response. If omitted, the data is assumed to be on the top level."
+              },
+              "errorMessagePath": {
+                "type": "string",
+                "description": "Optional path to a human-readable error message in the third-party response body, used when the call fails (non-2xx status).\nIf specified and the path resolves to a string, that message is forwarded to the end user instead of a generic error.\n",
+                "example": "error.message"
               }
             },
             "additionalProperties": false
@@ -3234,6 +3288,17 @@
             ],
             "additionalProperties": false
           },
+          "resolved": {
+            "type": "object",
+            "properties": {
+              "errorMessagePath": {
+                "type": "string",
+                "description": "Optional path to a human-readable error message in the third-party response body, used when the call fails (non-2xx status).\nIf specified and the path resolves to a string, that message is forwarded to the end user instead of a generic error.\n",
+                "example": "error.message"
+              }
+            },
+            "additionalProperties": false
+          },
           "use_static_ips": {
             "type": "boolean",
             "deprecated": true,
@@ -3252,7 +3317,7 @@
         "additionalProperties": false
       },
       "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\": [\n        { \"id\": \"feed-out\", \"label\": { \"en\": \"Grid import\" }, \"aggregation_group\": \"grid\", \"statistical_method\": \"sum\", \"direction\": \"out\", \"unit\": \"kWh\" },\n        { \"id\": \"feed-in\",  \"label\": { \"en\": \"Feed-in\"     }, \"aggregation_group\": \"grid\", \"statistical_method\": \"sum\", \"direction\": \"in\",  \"unit\": \"kWh\" },\n        ...\n      ],\n      \"intervals\": [\"PT15M\", \"PT1H\", \"P1D\", \"P1M\"],\n      \"data_range\": { \"from\": \"2024-01-01T00:00:00Z\", \"to\": \"2026-05-01T00:00:00Z\" }\n    }\n  Each type option carries its own `statistical_method`, which describes the method already applied to that type's data and dictates the chart shape: `sum` is rendered as a bar chart; `min`, `average`, and `max` are rendered as a line chart. A single visualization can therefore mix bar-shaped types with line-shaped types. Defaults to `sum` when omitted.\n  `direction` declares whether a type adds to or subtracts from the period total: `out` is grid-to-consumer (consumption, additive); `in` is consumer-to-grid (export, subtractive). With both present in a prosumer setup the chart computes a *net* consumption per period and can flip its label to \"Total production\" when the result is negative. Defaults to `out` when omitted.\n  `aggregation_group` controls how types within a group are visually combined (depends on the per-type `statistical_method`):\n    - bar chart (`sum`): same-group types are stacked into a single bar (e.g. ht/nt summed into total consumption); different-group types render side-by-side.\n    - line chart (`min` / `average` / `max`): same-group types are rendered as an area chart; different-group types render as separate lines.\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",
+        "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\": [\n        { \"id\": \"ht\", \"label\": { \"en\": \"High tariff\" }, \"aggregation_group\": \"consumption\", \"statistical_method\": \"sum\", \"unit\": \"kWh\", \"color\": \"primary\", \"precision\": 2 },\n        ...\n      ],\n      \"intervals\": [\"PT15M\", \"PT1H\", \"P1D\", \"P1M\"],\n      \"data_range\": { \"from\": \"2024-01-01T00:00:00Z\", \"to\": \"2026-05-01T00:00:00Z\" }\n    }\n  Each type option carries its own `statistical_method`, which describes the method already applied to that type's data and dictates the chart shape: `sum` is rendered as a bar chart; `min`, `average`, and `max` are rendered as a line chart. A single visualization can therefore mix bar-shaped types with line-shaped types. Defaults to `sum` when omitted.\n  Each type option may also customize its rendering: `color` picks a Spark palette color (`primary`, `slate`, `mauve`, `orange`, `red`, `tomato`, `amber`, `green`, `blue`) used to draw the type's series; `precision` sets the number of decimal places to show for that type's values (axis labels, tooltips, summaries). Both are optional — the consumer falls back to its own defaults when they are omitted.\n  `aggregation_group` controls how types within a group are visually combined (depends on the per-type `statistical_method`):\n    - bar chart (`sum`): same-group types are stacked into a single bar (e.g. ht/nt summed into total consumption); different-group types render side-by-side.\n    - line chart (`min` / `average` / `max`): same-group types are rendered as an area chart; different-group types render as separate lines.\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",
         "properties": {
           "id": {
@@ -3317,6 +3382,11 @@
               "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."
+              },
+              "errorMessagePath": {
+                "type": "string",
+                "description": "Optional path to a human-readable error message in the third-party response body, used when the call fails (non-2xx status).\nIf specified and the path resolves to a string, that message is forwarded to the end user instead of a generic error.\n",
+                "example": "error.message"
               }
             },
             "additionalProperties": false
@@ -3418,6 +3488,11 @@
               "dataPath": {
                 "type": "string",
                 "description": "Optional path to the data (array) in the response. If omitted, the data is assumed to be on the top level."
+              },
+              "errorMessagePath": {
+                "type": "string",
+                "description": "Optional path to a human-readable error message in the third-party response body, used when the call fails (non-2xx status).\nIf specified and the path resolves to a string, that message is forwarded to the end user instead of a generic error.\n",
+                "example": "error.message"
               }
             },
             "additionalProperties": false

package/package.json

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