@epilot/cli 0.1.143 → 0.1.144

package/README.md

@@ -29,7 +29,7 @@ npm install -g @epilot/cli
 
 <!-- usage-help -->
 ```
-epilot v0.1.143 — CLI for epilot APIs
+epilot v0.1.144 — CLI for epilot APIs
 
 USAGE
   epilot <api> <operationId> [params...] [flags]

package/definitions/app.json

@@ -1150,6 +1150,9 @@
             "description": "Target version to create"
           }
         ],
+        "requestBody": {
+          "$ref": "#/components/requestBodies/CloneVersionRequest"
+        },
         "responses": {
           "201": {
             "description": "New version created successfully",
@@ -1902,6 +1905,28 @@
                     "$ref": "#/components/schemas/Options"
                   },
                   "description": "Replaces the full set of app-level option declarations for this version.\nOption keys must be unique app-wide; `secret`-touching options are always\nsensitive and must not declare `sensitive: false`.\n"
+                },
+                "changelog": {
+                  "type": "string",
+                  "maxLength": 250,
+                  "description": "Short description of what changed in this version"
+                }
+              }
+            }
+          }
+        }
+      },
+      "CloneVersionRequest": {
+        "required": false,
+        "content": {
+          "application/json": {
+            "schema": {
+              "type": "object",
+              "properties": {
+                "changelog": {
+                  "type": "string",
+                  "maxLength": 250,
+                  "description": "Short description of what the new version will change"
                 }
               }
             }
@@ -2009,7 +2034,7 @@
       },
       "Options": {
         "type": "object",
-        "description": "Options for the component configuration",
+        "description": "An option declaration — a setting the installing org fills in. Declared at app level.",
         "required": [
           "key",
           "type"
@@ -2058,7 +2083,7 @@
           },
           "sensitive": {
             "type": "boolean",
-            "description": "Write-only, server-side only value — like a sensitive environment variable\n(app-level options only). Sensitive values are never serialized in any response;\nthey are resolvable only via server-side channels (API proxy injection, function\n`secrets` allowlist, the internal options/resolve endpoint). Non-sensitive values\nare readable wherever the app runs, including the end-customer browser (journey and\nportal runtime). Forced to true for `secret`-touching options. Default: false.\n"
+            "description": "Write-only, server-side only value — like a sensitive environment variable\n(app-level options only). Sensitive values are never serialized in any response;\nthey are resolvable only via server-side channels (API proxy injection, function\nruns, the internal options/resolve endpoint). Non-sensitive values\nare readable wherever the app runs, including the end-customer browser (journey and\nportal runtime). Forced to true for `secret`-touching options. Default: false.\n"
           },
           "configured": {
             "type": "boolean",
@@ -2179,6 +2204,7 @@
           "EXTERNAL_PRODUCT_CATALOG",
           "CUSTOM_PAGE",
           "API_PROXY",
+          "EXTERNAL_VALUES",
           "APP_FUNCTION"
         ],
         "description": "Type of app component"
@@ -2375,7 +2401,8 @@
                 "CUSTOM_CAPABILITY": "#/components/schemas/CustomCapabilityComponent",
                 "EXTERNAL_PRODUCT_CATALOG": "#/components/schemas/ExternalProductCatalogComponent",
                 "CUSTOM_PAGE": "#/components/schemas/CustomPageComponent",
-                "API_PROXY": "#/components/schemas/ApiProxyComponent"
+                "API_PROXY": "#/components/schemas/ApiProxyComponent",
+                "EXTERNAL_VALUES": "#/components/schemas/ExternalValuesComponent"
               }
             },
             "oneOf": [
@@ -2405,6 +2432,9 @@
               },
               {
                 "$ref": "#/components/schemas/ApiProxyComponent"
+              },
+              {
+                "$ref": "#/components/schemas/ExternalValuesComponent"
               }
             ]
           }
@@ -2428,6 +2458,25 @@
           }
         }
       },
+      "ExternalValuesComponent": {
+        "type": "object",
+        "description": "Exposes typed values resolved from an external system at runtime (e.g. a meter reading prediction). Consumers such as validation rules reference a hook and one of its results by id. Resolution is performed by the external-values-api on behalf of authenticated epilot 360 users and portal end customers.\n",
+        "required": [
+          "component_type",
+          "configuration"
+        ],
+        "properties": {
+          "component_type": {
+            "type": "string",
+            "enum": [
+              "EXTERNAL_VALUES"
+            ]
+          },
+          "configuration": {
+            "$ref": "#/components/schemas/ExternalValuesConfig"
+          }
+        }
+      },
       "CustomCapabilityComponent": {
         "type": "object",
         "required": [
@@ -3667,7 +3716,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\": \"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",
+        "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\", \"P1Y\"],\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": {
@@ -5082,6 +5131,204 @@
           }
         }
       },
+      "ExternalValuesConfig": {
+        "type": "object",
+        "description": "Configuration for an EXTERNAL_VALUES component",
+        "required": [
+          "hooks"
+        ],
+        "properties": {
+          "hooks": {
+            "type": "array",
+            "description": "Hooks exposed by this component. Hook ids must be unique within the component.",
+            "items": {
+              "$ref": "#/components/schemas/ExternalValuesHook"
+            }
+          }
+        }
+      },
+      "ExternalValuesHook": {
+        "type": "object",
+        "description": "One external call that returns one or more typed results. Interpolated templates (Liquid) have access to `Input`, `Context`, `Consumer`, `Options`, `Env` and — for `result` templates — `Response` and `AuthResponse`.\n",
+        "required": [
+          "id",
+          "name",
+          "call",
+          "result"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-zA-Z0-9_-]{1,100}$",
+            "description": "Stable identifier; consumers (e.g. validation rules) reference it. Renaming breaks references."
+          },
+          "name": {
+            "$ref": "#/components/schemas/TranslatedString"
+          },
+          "description": {
+            "$ref": "#/components/schemas/TranslatedString"
+          },
+          "auth_type": {
+            "type": "string",
+            "enum": [
+              "none",
+              "header",
+              "bearer",
+              "hmac"
+            ],
+            "default": "none",
+            "description": "Static request authentication applied to the call.\n- `none`: no static authentication.\n- `header`: sends `auth_secret` in header `auth_header` (default `X-API-Key`).\n- `bearer`: sends `Authorization: Bearer <auth_secret>`.\n- `hmac`: signs the request per Standard Webhooks (headers `webhook-id`,\n  `webhook-timestamp`, `webhook-signature` = `v1,<base64 HMAC-SHA256>` over\n  `<id>.<timestamp>.<body>`) using `auth_secret` as a `whsec_`-prefixed\n  base64 secret, exactly as epilot webhooks do.\n\n`auth_secret` is required when `auth_type` is `header`, `bearer` or `hmac`.\nCombine with `auth` (a pre-call that fetches a token) when the target needs both.\n"
+          },
+          "auth_header": {
+            "type": "string",
+            "description": "Header name used when `auth_type` is `header`. Defaults to `X-API-Key`."
+          },
+          "auth_secret": {
+            "type": "string",
+            "description": "Liquid template resolving to the secret, e.g. \"{{Options.api_key}}\". Must reference an option declared with `type: secret`; literals are rejected. Required when `auth_type` is `header`, `bearer` or `hmac`.",
+            "example": "{{Options.api_key}}"
+          },
+          "auth": {
+            "$ref": "#/components/schemas/PortalExtensionAuthBlock"
+          },
+          "call": {
+            "type": "object",
+            "required": [
+              "url"
+            ],
+            "properties": {
+              "method": {
+                "type": "string",
+                "enum": [
+                  "GET",
+                  "POST",
+                  "PUT",
+                  "PATCH"
+                ],
+                "default": "POST",
+                "description": "HTTP method to use for the call"
+              },
+              "url": {
+                "type": "string",
+                "description": "URL to call. Supports variable interpolation."
+              },
+              "headers": {
+                "type": "object",
+                "description": "Headers to send with the call. Supports variable interpolation.",
+                "additionalProperties": {
+                  "type": "string"
+                }
+              },
+              "params": {
+                "type": "object",
+                "description": "Query parameters to append to the URL. Supports variable interpolation.",
+                "additionalProperties": {
+                  "type": "string"
+                }
+              },
+              "body": {
+                "type": "object",
+                "description": "JSON body to send. Values support variable interpolation. When omitted, `{ Input, Context, Consumer }` is sent as-is.",
+                "additionalProperties": true
+              }
+            }
+          },
+          "result": {
+            "type": "array",
+            "minItems": 1,
+            "description": "Typed results extracted from the response. Result ids must be unique within the hook.",
+            "items": {
+              "$ref": "#/components/schemas/ExternalValuesResult"
+            }
+          },
+          "timeout_ms": {
+            "type": "integer",
+            "minimum": 500,
+            "maximum": 5000,
+            "default": 3000,
+            "description": "Timeout for the external call in milliseconds."
+          },
+          "on_unavailable": {
+            "type": "string",
+            "enum": [
+              "skip",
+              "block"
+            ],
+            "default": "skip",
+            "description": "Behaviour when the external system is unavailable (timeout, network or upstream error). `skip`: consumers ignore conditions depending on this hook. `block`: consumers treat the dependent action as not allowed."
+          },
+          "cache": {
+            "type": "object",
+            "description": "Response caching. Off when omitted.",
+            "required": [
+              "ttl_seconds"
+            ],
+            "properties": {
+              "ttl_seconds": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 3600,
+                "description": "Time to live in seconds. 0 disables caching."
+              },
+              "key": {
+                "type": "string",
+                "description": "Liquid template for the cache key. Defaults to a hash of org, app, hook, `Input` and `Context`."
+              }
+            }
+          },
+          "use_static_ips": {
+            "type": "boolean",
+            "description": "If set, requests are sent from epilot's static egress IPs. Mutually exclusive with secure_proxy."
+          },
+          "secure_proxy": {
+            "$ref": "#/components/schemas/PortalExtensionSecureProxy"
+          }
+        }
+      },
+      "ExternalValuesResult": {
+        "type": "object",
+        "description": "A single typed value extracted from the hook response. Exactly one of `template`, `path` or `jsonata` must be set.\n",
+        "required": [
+          "id",
+          "type",
+          "name"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-zA-Z0-9_-]{1,100}$",
+            "description": "Stable identifier of the result within the hook. Renaming breaks references."
+          },
+          "type": {
+            "type": "string",
+            "enum": [
+              "number",
+              "text",
+              "date",
+              "boolean"
+            ],
+            "description": "Type the extracted value is coerced to."
+          },
+          "name": {
+            "$ref": "#/components/schemas/TranslatedString"
+          },
+          "template": {
+            "type": "string",
+            "description": "Liquid template over `Response` etc.; output coerced to `type`.",
+            "example": "{{Response.value}}"
+          },
+          "path": {
+            "type": "string",
+            "description": "Dot path into the response body, e.g. \"data.limit\".",
+            "example": "data.limit"
+          },
+          "jsonata": {
+            "type": "string",
+            "description": "JSONata expression over `{ Response, Input, Context, Options, Env }`.",
+            "example": "$sum(Response.items.amount)"
+          }
+        }
+      },
       "Grants": {
         "type": "array",
         "description": "Required grants for the app in order to call APIs for the installing tenant",

package/definitions/validation-rules.json

@@ -208,7 +208,7 @@
             }
           },
           "400": {
-            "description": "Bad Request - Invalid request body",
+            "description": "Bad Request - Invalid request body. Invalid external comparison values additionally carry a\n`code` (`external_value_not_found` when the app is not installed or the hook / result does not\nexist, `external_value_incompatible` when the result type does not match the compared kind).\n",
             "content": {
               "application/json": {
                 "schema": {
@@ -217,6 +217,13 @@
                     "message": {
                       "type": "string",
                       "example": "Invalid request body"
+                    },
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "external_value_not_found",
+                        "external_value_incompatible"
+                      ]
                     }
                   }
                 }
@@ -484,7 +491,7 @@
             }
           },
           "400": {
-            "description": "Bad Request - Invalid request body",
+            "description": "Bad Request - Invalid request body. Invalid external comparison values additionally carry a\n`code` (`external_value_not_found` when the app is not installed or the hook / result does not\nexist, `external_value_incompatible` when the result type does not match the compared kind).\n",
             "content": {
               "application/json": {
                 "schema": {
@@ -493,6 +500,13 @@
                     "message": {
                       "type": "string",
                       "example": "Invalid request body"
+                    },
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "external_value_not_found",
+                        "external_value_incompatible"
+                      ]
                     }
                   }
                 }
@@ -1984,7 +1998,7 @@
       },
       "ComparisonRuleType": {
         "type": "object",
-        "description": "Declarative validation rule (schema version v2). Supports predefined comparison operators\nover number, date and text inputs, with static, dynamic (context path) and relative-date\ncomparison values.\n",
+        "description": "Declarative validation rule (schema version v2). Supports predefined comparison operators\nover number, date and text inputs, with static, dynamic (context path), relative-date and\nexternal (app-provided) comparison values.\n",
         "required": [
           "input_type",
           "conditions"
@@ -2088,6 +2102,12 @@
           {
             "$ref": "#/components/schemas/RelativeDateValue"
           },
+          {
+            "$ref": "#/components/schemas/EnvironmentValue"
+          },
+          {
+            "$ref": "#/components/schemas/ExternalValue"
+          },
           {
             "$ref": "#/components/schemas/RangeValue"
           },
@@ -2097,7 +2117,7 @@
         ]
       },
       "ScalarValue": {
-        "description": "A single comparison value - static, resolved from context, or a relative date.",
+        "description": "A single comparison value - static, resolved from context, a relative date, an organisation environment variable, or an external value.",
         "oneOf": [
           {
             "$ref": "#/components/schemas/StaticValue"
@@ -2107,9 +2127,82 @@
           },
           {
             "$ref": "#/components/schemas/RelativeDateValue"
+          },
+          {
+            "$ref": "#/components/schemas/EnvironmentValue"
+          },
+          {
+            "$ref": "#/components/schemas/ExternalValue"
           }
         ]
       },
+      "EnvironmentValue": {
+        "type": "object",
+        "description": "A comparison value resolved at evaluation time from an organisation environment variable\n(environments-api). The rule stores the key, never the value, so one change to the variable\nreaches every rule that references it and a blueprint install never overwrites the\norganisation's own value.\n\nOnly browser-safe variable types are allowed: `Number` for numeric comparisons, `Text` for\ntext comparisons and for dates (ISO 8601 string), `Boolean` for `applies_when` values.\n`String` and `SecretString` variables are rejected at write time. Write-time validation also\nchecks that the variable exists in the organisation; a variable that exists without a value\n(for example seeded by a blueprint install) is accepted and resolves as unavailable until set.\n",
+        "required": [
+          "source",
+          "key"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "source": {
+            "type": "string",
+            "enum": [
+              "environment"
+            ]
+          },
+          "key": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9_.\\-]{0,127}$",
+            "description": "Environment variable key, e.g. `abschlag.max`."
+          },
+          "adjust": {
+            "$ref": "#/components/schemas/ValueAdjustment"
+          }
+        }
+      },
+      "ExternalValue": {
+        "type": "object",
+        "description": "A comparison value produced at evaluation time by an External Values hook of an installed\napp (component type `EXTERNAL_VALUES`). The rule stores the reference only; the value is\nresolved server-side by the external-values-api, which executes the hook's HTTP call with\nthe app's credentials and returns the typed result identified by `result_id`.\n\nWrite-time validation checks that the app is installed in the organisation, that the hook\nand result exist, and that the result's type is compatible with the compared kind\n(`number` results for numeric comparisons, `text` for text, `date` for date). External values\nare resolved only for authenticated consumers (epilot 360 users and portal end customers);\nin public journeys the dependent conditions are skipped.\n",
+        "required": [
+          "source",
+          "app_id",
+          "hook_id",
+          "result_id"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "source": {
+            "type": "string",
+            "enum": [
+              "external"
+            ]
+          },
+          "app_id": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 100,
+            "description": "ID of the installed app that provides the External Values component."
+          },
+          "hook_id": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 100,
+            "pattern": "^[a-zA-Z0-9_-]+$",
+            "description": "ID of the hook within the app's External Values component."
+          },
+          "result_id": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 100,
+            "pattern": "^[a-zA-Z0-9_-]+$",
+            "description": "ID of the result entry within the hook whose value is compared."
+          },
+          "adjust": {
+            "$ref": "#/components/schemas/ValueAdjustment"
+          }
+        }
+      },
       "StaticValue": {
         "type": "object",
         "description": "A fixed comparison value.",
@@ -2194,6 +2287,9 @@
               },
               {
                 "$ref": "#/components/schemas/ContextValue"
+              },
+              {
+                "$ref": "#/components/schemas/EnvironmentValue"
               }
             ]
           },
@@ -2324,7 +2420,7 @@
             "description": "Comparison applied to the resolved context value. `isEmpty` / `isNotEmpty`\ntake no `value`; all other operators require one.\n"
           },
           "value": {
-            "description": "Static comparison value for binary operators.",
+            "description": "Comparison value for binary operators: a static number, string or boolean, or an\norganisation environment variable (`Number`, `Text` or `Boolean`) so a precondition\ncan act as a per-organisation switch or threshold.\n",
             "oneOf": [
               {
                 "type": "number"
@@ -2334,6 +2430,9 @@
               },
               {
                 "type": "boolean"
+              },
+              {
+                "$ref": "#/components/schemas/EnvironmentValue"
               }
             ]
           }

package/dist/bin/epilot.js

@@ -11,7 +11,7 @@ import { defineCommand } from "citty";
 var main = defineCommand({
   meta: {
     name: "epilot",
-    version: "0.1.143",
+    version: "0.1.144",
     description: "CLI for epilot APIs"
   },
   args: {
@@ -31,7 +31,7 @@ var main = defineCommand({
     profile: () => import("../profile-OZJL5ZPT.js").then((m) => m.default),
     config: () => import("../config-DGZIMLZK.js").then((m) => m.default),
     completion: () => import("../completion-HPDI7RNO.js").then((m) => m.default),
-    upgrade: () => import("../upgrade-7VYPWNEV.js").then((m) => m.default),
+    upgrade: () => import("../upgrade-4LGBIDMY.js").then((m) => m.default),
     "access-token": () => import("../access-token-WWE6BDJH.js").then((m) => m.default),
     address: () => import("../address-EH3C4CVB.js").then((m) => m.default),
     "address-suggestions": () => import("../address-suggestions-RRSLOBFW.js").then((m) => m.default),
@@ -134,7 +134,7 @@ process.stderr.on("error", (err) => {
   if (err.code === "EPIPE") process.exit(0);
   throw err;
 });
-var VERSION = true ? "0.1.143" : (await null).default.version;
+var VERSION = true ? "0.1.144" : (await null).default.version;
 var reorderedArgv = hoistFlagsAfterSubcommand(process.argv.slice(2));
 process.argv = [process.argv[0], process.argv[1], ...reorderedArgv];
 var args = process.argv.slice(2);

package/dist/{upgrade-7VYPWNEV.js → upgrade-4LGBIDMY.js}

@@ -72,7 +72,7 @@ ${GREEN}${BOLD}Upgraded to @epilot/cli@${latest}${RESET}
   }
 });
 var getCurrentVersion = () => {
-  if (true) return "0.1.143";
+  if (true) return "0.1.144";
   try {
     const output = execSync("npm ls -g @epilot/cli --depth=0 --json 2>/dev/null", {
       encoding: "utf-8",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@epilot/cli",
-  "version": "0.1.143",
+  "version": "0.1.144",
   "description": "CLI for epilot APIs",
   "type": "module",
   "bin": {