@epilot/cli 0.1.24 → 0.1.25

package/README.md

@@ -29,7 +29,7 @@ npm install -g @epilot/cli
 
 <!-- usage-help -->
 ```
-epilot v0.1.24 — CLI for epilot APIs
+epilot v0.1.25 — CLI for epilot APIs
 
 USAGE
   epilot <api> <operationId> [params...] [flags]
@@ -70,6 +70,7 @@ APIs
   automation           Automation API
   billing              Billing API
   blueprint-manifest   Blueprint Manifest API
+  calendar             Calendar API
   configuration-hub    Configuration Hub API
   consent              Consent API
   customer-portal      Portal API
@@ -325,6 +326,7 @@ Full documentation with sample calls and responses for all APIs:
 | Automation API | `epilot automation` | [docs](./docs/automation.md) |
 | Billing API | `epilot billing` | [docs](./docs/billing.md) |
 | Blueprint Manifest API | `epilot blueprint-manifest` | [docs](./docs/blueprint-manifest.md) |
+| Calendar API | `epilot calendar` | [docs](./docs/calendar.md) |
 | Configuration Hub API | `epilot configuration-hub` | [docs](./docs/configuration-hub.md) |
 | Consent API | `epilot consent` | [docs](./docs/consent.md) |
 | Portal API | `epilot customer-portal` | [docs](./docs/customer-portal.md) |

package/definitions/app.json

@@ -17,6 +17,10 @@
     {
       "name": "App Analytics",
       "description": "Analytics for installed apps"
+    },
+    {
+      "name": "App Proxy",
+      "description": "Forward requests to external APIs via registered proxy targets"
     }
   ],
   "servers": [
@@ -1468,6 +1472,100 @@
           }
         }
       }
+    },
+    "/v1/public/app/{appId}/proxy/{proxyName}/{path}": {
+      "parameters": [
+        {
+          "name": "appId",
+          "in": "path",
+          "required": true,
+          "schema": {
+            "type": "string"
+          },
+          "description": "ID of the installed app"
+        },
+        {
+          "name": "proxyName",
+          "in": "path",
+          "required": true,
+          "schema": {
+            "type": "string"
+          },
+          "description": "Name of the proxy target as defined in the app manifest"
+        },
+        {
+          "name": "path",
+          "in": "path",
+          "required": true,
+          "schema": {
+            "type": "string"
+          },
+          "description": "Path to forward to the proxy target"
+        }
+      ],
+      "get": {
+        "summary": "publicProxyGet",
+        "operationId": "publicProxyGet",
+        "description": "Forward a GET request to a registered proxy target from a public-facing component (e.g. journey blocks)",
+        "tags": [
+          "App Proxy"
+        ],
+        "security": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Proxied response from the target API"
+          },
+          "403": {
+            "description": "Forbidden - app not installed or no public component uses this proxy"
+          },
+          "404": {
+            "description": "Proxy target not found"
+          },
+          "502": {
+            "description": "Bad gateway - proxy target unreachable or error"
+          }
+        }
+      },
+      "post": {
+        "summary": "publicProxyPost",
+        "operationId": "publicProxyPost",
+        "description": "Forward a POST request to a registered proxy target from a public-facing component (e.g. journey blocks)",
+        "tags": [
+          "App Proxy"
+        ],
+        "security": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Proxied response from the target API"
+          },
+          "403": {
+            "description": "Forbidden - app not installed or no public component uses this proxy"
+          },
+          "404": {
+            "description": "Proxy target not found"
+          },
+          "502": {
+            "description": "Bad gateway - proxy target unreachable or error"
+          }
+        }
+      }
     }
   },
   "components": {
@@ -1832,7 +1930,8 @@
           "ERP_INFORM_TOOLKIT",
           "CUSTOM_CAPABILITY",
           "EXTERNAL_PRODUCT_CATALOG",
-          "CUSTOM_PAGE"
+          "CUSTOM_PAGE",
+          "API_PROXY"
         ],
         "description": "Type of app component"
       },
@@ -1944,7 +2043,8 @@
                 "ERP_INFORM_TOOLKIT": "#/components/schemas/ErpInformToolkitComponent",
                 "CUSTOM_CAPABILITY": "#/components/schemas/CustomCapabilityComponent",
                 "EXTERNAL_PRODUCT_CATALOG": "#/components/schemas/ExternalProductCatalogComponent",
-                "CUSTOM_PAGE": "#/components/schemas/CustomPageComponent"
+                "CUSTOM_PAGE": "#/components/schemas/CustomPageComponent",
+                "API_PROXY": "#/components/schemas/ApiProxyComponent"
               }
             },
             "oneOf": [
@@ -1971,11 +2071,32 @@
               },
               {
                 "$ref": "#/components/schemas/CustomPageComponent"
+              },
+              {
+                "$ref": "#/components/schemas/ApiProxyComponent"
               }
             ]
           }
         ]
       },
+      "ApiProxyComponent": {
+        "type": "object",
+        "required": [
+          "component_type",
+          "configuration"
+        ],
+        "properties": {
+          "component_type": {
+            "type": "string",
+            "enum": [
+              "API_PROXY"
+            ]
+          },
+          "configuration": {
+            "$ref": "#/components/schemas/ApiProxyConfig"
+          }
+        }
+      },
       "CustomCapabilityComponent": {
         "type": "object",
         "required": [
@@ -2488,8 +2609,10 @@
                   "contractIdentification": "#/components/schemas/PortalExtensionHookContractIdentification",
                   "priceDataRetrieval": "#/components/schemas/PortalExtensionHookPriceDataRetrieval",
                   "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": [
@@ -2505,11 +2628,17 @@
                 {
                   "$ref": "#/components/schemas/PortalExtensionHookConsumptionDataRetrieval"
                 },
+                {
+                  "$ref": "#/components/schemas/PortalExtensionHookDataExport"
+                },
                 {
                   "$ref": "#/components/schemas/PortalExtensionHookCostDataRetrieval"
                 },
                 {
                   "$ref": "#/components/schemas/PortalExtensionHookMeterReadingPlausibilityCheck"
+                },
+                {
+                  "$ref": "#/components/schemas/PortalExtensionHookVisualizationMetadata"
                 }
               ]
             }
@@ -2594,7 +2723,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": {
@@ -2707,7 +2837,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": {
@@ -2818,7 +2949,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": {
@@ -2853,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": [
@@ -2918,7 +3051,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": {
@@ -2952,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": [
@@ -3017,7 +3152,179 @@
           },
           "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/PortalExtensionSecureProxy"
+          }
+        },
+        "required": [
+          "id",
+          "type",
+          "call"
+        ],
+        "additionalProperties": false
+      },
+      "PortalExtensionHookDataExport": {
+        "description": "Generic data export hook. When configured on blocks that support it, 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": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-zA-Z0-9_-]+$",
+            "description": "Identifier of the hook. Should not change between updates."
+          },
+          "name": {
+            "$ref": "#/components/schemas/TranslatedString"
+          },
+          "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/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"
+            ],
+            "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",
+          "type",
+          "call"
+        ],
+        "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\": [{ \"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",
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-zA-Z0-9_-]+$",
+            "description": "Identifier of the hook. Should not change between updates."
+          },
+          "name": {
+            "$ref": "#/components/schemas/TranslatedString"
+          },
+          "type": {
+            "type": "string",
+            "enum": [
+              "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"
+            ],
+            "additionalProperties": false
+          },
+          "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": {
@@ -3051,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": [
@@ -3116,7 +3424,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": {
@@ -3430,7 +3739,8 @@
                 "enum": [
                   "text",
                   "boolean",
-                  "enum"
+                  "enum",
+                  "block_reference"
                 ]
               },
               "required": {
@@ -3467,7 +3777,8 @@
               "mapping": {
                 "text": "#/components/schemas/TextArg",
                 "boolean": "#/components/schemas/BooleanArg",
-                "enum": "#/components/schemas/EnumArg"
+                "enum": "#/components/schemas/EnumArg",
+                "block_reference": "#/components/schemas/BlockReferenceArg"
               }
             },
             "oneOf": [
@@ -3479,6 +3790,9 @@
               },
               {
                 "$ref": "#/components/schemas/EnumArg"
+              },
+              {
+                "$ref": "#/components/schemas/BlockReferenceArg"
               }
             ]
           }
@@ -3506,6 +3820,25 @@
           }
         }
       },
+      "BlockReferenceArg": {
+        "type": "object",
+        "description": "References another journey block by its ID. The configuring user picks\na block from the journey via a dropdown in the journey-builder; the\nchosen block's ID is stored as the arg value (a string). The bundle can\nthen call `subscribe(blockId, cb)` / `getValue(blockId)` against that ID.\n",
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": [
+              "block_reference"
+            ]
+          },
+          "allowed_types": {
+            "type": "array",
+            "description": "Restrict the picker to blocks of these journey block types\n(e.g. [\"availability-check\", \"address\"]). Omit to allow any type.\n",
+            "items": {
+              "type": "string"
+            }
+          }
+        }
+      },
       "EnumArg": {
         "type": "object",
         "required": [
@@ -3876,6 +4209,49 @@
           }
         }
       },
+      "ApiProxyConfig": {
+        "type": "object",
+        "description": "Configuration for an API proxy component",
+        "required": [
+          "name",
+          "target",
+          "auth_type"
+        ],
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Human-friendly proxy name used in SDK calls",
+            "pattern": "^[a-zA-Z0-9_-]+$",
+            "maxLength": 64
+          },
+          "target": {
+            "type": "string",
+            "format": "uri",
+            "description": "Base URL of the target API. Must be HTTPS.",
+            "pattern": "^https://"
+          },
+          "auth_type": {
+            "type": "string",
+            "enum": [
+              "header",
+              "bearer",
+              "oauth2",
+              "none"
+            ],
+            "description": "Authentication strategy"
+          },
+          "auth_header": {
+            "type": "string",
+            "description": "Header name for 'header' auth type"
+          },
+          "token_url": {
+            "type": "string",
+            "format": "uri",
+            "description": "OAuth2 token endpoint URL",
+            "pattern": "^https://"
+          }
+        }
+      },
       "Grants": {
         "type": "array",
         "description": "Required grants for the app in order to call APIs for the installing tenant",