@epilot/app-client 0.13.8 → 0.15.0

package/dist/openapi.json

@@ -1150,6 +1150,9 @@
             "description": "Target version to create"
           }
         ],
+        "requestBody": {
+          "$ref": "#/components/requestBodies/CloneVersionRequest"
+        },
         "responses": {
           "201": {
             "description": "New version created successfully",
@@ -1438,6 +1441,70 @@
         }
       }
     },
+    "/v1/app/{appId}/options/resolve": {
+      "post": {
+        "summary": "resolveOptions",
+        "description": "Resolve the effective app-level options of an installation, including decrypted sensitive values (secrets). This endpoint accepts epilot internal-auth tokens exclusively (internal service calls, e.g. automation-workers or the customer portal API) — no user token, API key, or app token can call it, regardless of roles. Every call is audit-logged with the caller identity.",
+        "operationId": "resolveOptions",
+        "tags": [
+          "App Installation"
+        ],
+        "parameters": [
+          {
+            "name": "appId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "keys": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    },
+                    "description": "Narrow the response to these option keys"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Effective options with resolved values",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "options": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/Options"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Caller is not authenticated with an internal-auth token"
+          },
+          "404": {
+            "description": "App installation not found"
+          }
+        }
+      }
+    },
     "/v1/app-events": {
       "post": {
         "summary": "ingestEvent",
@@ -1501,6 +1568,18 @@
             "type": "string"
           },
           "description": "Path to forward to the proxy target"
+        },
+        {
+          "name": "query",
+          "in": "query",
+          "required": false,
+          "style": "form",
+          "explode": true,
+          "schema": {
+            "type": "object",
+            "additionalProperties": true
+          },
+          "description": "Free-form query parameters, forwarded unchanged to the proxy target"
         }
       ],
       "get": {
@@ -1812,6 +1891,42 @@
                 },
                 "grants": {
                   "$ref": "#/components/schemas/Grants"
+                },
+                "functions": {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/components/schemas/FunctionDefinition"
+                  },
+                  "description": "Replaces the full set of server-side functions for this version"
+                },
+                "options": {
+                  "type": "array",
+                  "items": {
+                    "$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"
                 }
               }
             }
@@ -1919,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"
@@ -1965,6 +2080,25 @@
               "object"
             ],
             "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"
+          },
+          "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\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",
+            "readOnly": true,
+            "description": "Serialized instead of `value` for sensitive options (secrets): true when a\nvalue is stored.\n"
+          },
+          "lifted": {
+            "type": "boolean",
+            "readOnly": true,
+            "description": "Compatibility marker: this option is declared at app level and folded back\ninto the component's options so existing consumers (journey runtime, portal\nblocks, older services) keep working unchanged. New consumers should read\napp-level options from the installation's `options` array instead.\n"
+          },
+          "value_updated_at": {
+            "type": "string",
+            "readOnly": true,
+            "description": "Timestamp of the last value change. Only returned for sensitive options\n(alongside `configured`) so installers can see when a secret was last rotated.\n"
           }
         }
       },
@@ -2029,7 +2163,7 @@
         "properties": {
           "component_id": {
             "type": "string",
-            "description": "ID of the component these values are for"
+            "description": "ID of the component these values are for. Use the sentinel `$app` for\napp-level option values (options declared at the manifest top level).\n"
           },
           "options": {
             "type": "array",
@@ -2069,10 +2203,87 @@
           "CUSTOM_CAPABILITY",
           "EXTERNAL_PRODUCT_CATALOG",
           "CUSTOM_PAGE",
-          "API_PROXY"
+          "API_PROXY",
+          "APP_FUNCTION"
         ],
         "description": "Type of app component"
       },
+      "FunctionDefinition": {
+        "type": "object",
+        "description": "A named server-side function belonging to the app. Runs in the epilot code-execution sandbox with an installation-scoped app token. Functions with a schedule are executed automatically once per installation.\n",
+        "required": [
+          "name",
+          "type",
+          "code"
+        ],
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Unique function name within the app",
+            "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
+          },
+          "type": {
+            "type": "string",
+            "enum": [
+              "workflow",
+              "scheduled"
+            ],
+            "description": "Where the function can be used. `workflow` functions are referenced by CUSTOM_FLOW_ACTION components (type `function`) and run with entity context. `scheduled` functions run automatically per installation on their cron schedule.\n"
+          },
+          "label": {
+            "allOf": [
+              {
+                "description": "Human-readable display name of the function, shown to installing organizations (e.g. in the scheduled-functions summary)\n"
+              },
+              {
+                "$ref": "#/components/schemas/TranslatedString"
+              }
+            ]
+          },
+          "description": {
+            "allOf": [
+              {
+                "description": "Description of the function"
+              },
+              {
+                "$ref": "#/components/schemas/TranslatedString"
+              }
+            ]
+          },
+          "code": {
+            "type": "string",
+            "maxLength": 307200,
+            "description": "JavaScript code to execute. Must declare a top-level `async function handler(input, context)`. Maximum size: 300KB (hard limit). Security restrictions: eval() and Function() constructor are not allowed.\n"
+          },
+          "schedule": {
+            "type": "string",
+            "maxLength": 100,
+            "description": "Cron trigger for the function, executed once per installation. Standard 5-field cron expression (e.g. \"0 3 * * *\") or rate expression (e.g. \"rate(30 minutes)\"). Minimum interval: 15 minutes. Scheduled runs are limited to 60 seconds.\n",
+            "example": "rate(30 minutes)"
+          },
+          "schedule_timezone": {
+            "type": "string",
+            "description": "IANA timezone the cron expression is evaluated in",
+            "default": "Europe/Berlin"
+          },
+          "schedule_overlap": {
+            "type": "string",
+            "enum": [
+              "skip"
+            ],
+            "default": "skip",
+            "description": "Behavior when the previous scheduled run is still active"
+          },
+          "secrets": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "deprecated": true,
+            "description": "DEPRECATED and ignored — functions receive the app's full effective option keyspace (sensitive values included) via input.app_options. Kept for manifest compatibility.\n"
+          }
+        }
+      },
       "Author": {
         "type": "object",
         "required": [
@@ -2159,6 +2370,13 @@
             },
             "description": "List of options for the app component"
           },
+          "uses_options": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Keys of app-level options this component uses. Narrows which options are\nfolded back into `options` for legacy consumers (e.g. which values a journey\nblock receives in its public args) — a scoping hint, never a security\nboundary. Stamped automatically by the component-options migration; may also\nbe declared by the app developer.\n"
+          },
           "surfaces": {
             "type": "object"
           }
@@ -2486,7 +2704,7 @@
           }
         ]
       },
-      "SandboxCustomActionConfig": {
+      "FunctionRefCustomActionConfig": {
         "allOf": [
           {
             "$ref": "#/components/schemas/BaseCustomActionConfig"
@@ -2497,41 +2715,37 @@
               "type": {
                 "type": "string",
                 "enum": [
-                  "sandbox"
+                  "function"
                 ]
               },
-              "sandbox_settings": {
-                "type": "object",
-                "properties": {
-                  "code": {
-                    "type": "string",
-                    "description": "JavaScript code to execute for the sandbox action. Maximum size: 300KB (hard limit). Code is stored as raw JavaScript and will be syntax-validated on save. Security restrictions: eval() and Function() constructor are not allowed.\n",
-                    "maxLength": 307200
-                  }
-                }
+              "function_name": {
+                "type": "string",
+                "description": "Name of a `workflow`-type function of the same app version. The component provides the org-facing contract (name, options, config surface); the referenced function provides the code.\n"
               }
             },
             "required": [
-              "type"
+              "type",
+              "function_name"
             ]
           }
         ]
       },
       "CustomFlowConfig": {
         "type": "object",
+        "description": "Configuration of a flow action component. `external_integration` calls an external HTTP endpoint; `function` runs a workflow-type app function in the epilot sandbox.\n",
         "oneOf": [
           {
             "$ref": "#/components/schemas/ExternalIntegrationCustomActionConfig"
           },
           {
-            "$ref": "#/components/schemas/SandboxCustomActionConfig"
+            "$ref": "#/components/schemas/FunctionRefCustomActionConfig"
           }
         ],
         "discriminator": {
           "propertyName": "type",
           "mapping": {
             "external_integration": "#/components/schemas/ExternalIntegrationCustomActionConfig",
-            "sandbox": "#/components/schemas/SandboxCustomActionConfig"
+            "function": "#/components/schemas/FunctionRefCustomActionConfig"
           }
         }
       },
@@ -3186,7 +3400,8 @@
                 "PT15M",
                 "PT1H",
                 "P1D",
-                "P1M"
+                "P1M",
+                "P1Y"
               ]
             }
           },
@@ -3297,7 +3512,8 @@
                 "PT15M",
                 "PT1H",
                 "P1D",
-                "P1M"
+                "P1M",
+                "P1Y"
               ]
             }
           },
@@ -3476,7 +3692,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": {
@@ -3600,7 +3816,8 @@
                 "PT15M",
                 "PT1H",
                 "P1D",
-                "P1M"
+                "P1M",
+                "P1Y"
               ]
             }
           },
@@ -4563,6 +4780,39 @@
           }
         }
       },
+      "InternalReview": {
+        "description": "Review entry including app ownership info, used by internal admin endpoints",
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/Review"
+          },
+          {
+            "type": "object",
+            "properties": {
+              "app_id": {
+                "type": "string",
+                "description": "ID of the app configuration",
+                "readOnly": true
+              },
+              "org_id": {
+                "type": "string",
+                "description": "Organization ID of the app owner",
+                "readOnly": true
+              },
+              "reviewed_by": {
+                "type": "string",
+                "description": "Identity of the internal reviewer who approved the review",
+                "readOnly": true
+              },
+              "reviewed_at": {
+                "type": "string",
+                "description": "Timestamp of the approval",
+                "readOnly": true
+              }
+            }
+          }
+        ]
+      },
       "ConfigurationMetadata": {
         "description": "Basic metadata about your app configuration which does not get versioned",
         "type": "object",
@@ -4708,6 +4958,22 @@
             },
             "minItems": 0
           },
+          "functions": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/FunctionDefinition"
+            },
+            "minItems": 0,
+            "description": "Server-side functions of the app, including scheduled functions"
+          },
+          "options": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/Options"
+            },
+            "minItems": 0,
+            "description": "App-level option declarations (with sensitivity) of this version"
+          },
           "visibility": {
             "type": "string",
             "enum": [
@@ -4816,10 +5082,11 @@
             "enum": [
               "header",
               "bearer",
+              "basic",
               "oauth2",
               "none"
             ],
-            "description": "Authentication strategy"
+            "description": "Authentication strategy. 'basic' sends an HTTP Basic Authorization header built server-side from the 'username' and 'password' component options."
           },
           "auth_header": {
             "type": "string",
@@ -4936,6 +5203,22 @@
             "minLength": 0,
             "readOnly": true
           },
+          "functions": {
+            "description": "Server-side functions of the installed version, including scheduled functions",
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/FunctionDefinition"
+            },
+            "readOnly": true
+          },
+          "options": {
+            "description": "Effective app-level options of the installation: declared top-level options plus\ncomponent-level options lifted to the app keyspace, each with its configured\n`value`. Values of sensitive options (secrets) are never included — they carry\n`configured` and `value_updated_at` instead.\n",
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/Options"
+            },
+            "readOnly": true
+          },
           "installed_version": {
             "type": "string",
             "description": "Version of the app that is installed",
@@ -5043,6 +5326,22 @@
             },
             "minItems": 0
           },
+          "functions": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/FunctionDefinition"
+            },
+            "minItems": 0,
+            "description": "Server-side functions of the app, including scheduled functions"
+          },
+          "options": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/Options"
+            },
+            "minItems": 0,
+            "description": "App-level option declarations (with sensitivity) of this version"
+          },
           "is_beta": {
             "type": "boolean",
             "description": "Flag to indicate if the app is in beta.",
@@ -5293,6 +5592,11 @@
               "correlation_id": {
                 "type": "string",
                 "description": "Filter by correlation ID for tracing"
+              },
+              "search": {
+                "type": "string",
+                "maxLength": 200,
+                "description": "Case-insensitive substring match over event details and component id"
               }
             }
           },
@@ -5343,6 +5647,11 @@
                 "minimum": 1,
                 "maximum": 1000,
                 "default": 100
+              },
+              "before": {
+                "type": "string",
+                "format": "date-time",
+                "description": "Cursor: only return events strictly older than this timestamp. Use the timestamp of the last received event to fetch the next page; more efficient than increasing page/page_size.\n"
               }
             }
           },

package/package.json

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