@epilot/cli 0.1.107 → 0.1.109

package/README.md

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

package/definitions/app.json

@@ -1501,6 +1501,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 +1824,13 @@
                 },
                 "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"
                 }
               }
             }
@@ -2069,10 +2088,99 @@
           "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 selectable as actions in the flow builder and run with entity context. `scheduled` functions run automatically per installation on their cron schedule.\n"
+          },
+          "label": {
+            "allOf": [
+              {
+                "description": "Human-readable display name, e.g. shown in the flow builder action picker"
+              },
+              {
+                "$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"
+            },
+            "description": "Keys of installation options of type secret made available to the function via input.app_options\n"
+          },
+          "wait_for_callback": {
+            "type": "boolean",
+            "description": "Workflow functions only — wait for the callback_url to be called before completing the flow action\n"
+          },
+          "surfaces": {
+            "type": "object",
+            "description": "Workflow functions only — optional custom config UI shown in the flow builder",
+            "properties": {
+              "flow_action_config": {
+                "$ref": "#/components/schemas/AppBridgeSurfaceConfig"
+              }
+            }
+          }
+        }
+      },
       "Author": {
         "type": "object",
         "required": [
@@ -2486,52 +2594,18 @@
           }
         ]
       },
-      "SandboxCustomActionConfig": {
-        "allOf": [
-          {
-            "$ref": "#/components/schemas/BaseCustomActionConfig"
-          },
-          {
-            "type": "object",
-            "properties": {
-              "type": {
-                "type": "string",
-                "enum": [
-                  "sandbox"
-                ]
-              },
-              "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
-                  }
-                }
-              }
-            },
-            "required": [
-              "type"
-            ]
-          }
-        ]
-      },
       "CustomFlowConfig": {
         "type": "object",
+        "description": "Configuration of an external-integration flow action. Sandboxed code belongs in the app's `functions` (type `workflow`) instead — workflow functions are selectable directly in the flow builder without a component.\n",
         "oneOf": [
           {
             "$ref": "#/components/schemas/ExternalIntegrationCustomActionConfig"
-          },
-          {
-            "$ref": "#/components/schemas/SandboxCustomActionConfig"
           }
         ],
         "discriminator": {
           "propertyName": "type",
           "mapping": {
-            "external_integration": "#/components/schemas/ExternalIntegrationCustomActionConfig",
-            "sandbox": "#/components/schemas/SandboxCustomActionConfig"
+            "external_integration": "#/components/schemas/ExternalIntegrationCustomActionConfig"
           }
         }
       },
@@ -4563,6 +4637,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 +4815,14 @@
             },
             "minItems": 0
           },
+          "functions": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/FunctionDefinition"
+            },
+            "minItems": 0,
+            "description": "Server-side functions of the app, including scheduled functions"
+          },
           "visibility": {
             "type": "string",
             "enum": [
@@ -4816,10 +4931,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 +5052,14 @@
             "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
+          },
           "installed_version": {
             "type": "string",
             "description": "Version of the app that is installed",
@@ -5043,6 +5167,14 @@
             },
             "minItems": 0
           },
+          "functions": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/FunctionDefinition"
+            },
+            "minItems": 0,
+            "description": "Server-side functions of the app, including scheduled functions"
+          },
           "is_beta": {
             "type": "boolean",
             "description": "Flag to indicate if the app is in beta.",

package/definitions/integration-toolkit.json

@@ -2,7 +2,7 @@
   "openapi": "3.0.3",
   "info": {
     "title": "Integration Toolkit API",
-    "version": "1.13.0",
+    "version": "1.15.0",
     "description": "API for integrating with external systems in a standardised way."
   },
   "tags": [
@@ -3744,7 +3744,7 @@
       "post": {
         "operationId": "createErpImport",
         "summary": "createErpImport",
-        "description": "Register an already-uploaded file (S3 ref) as a pricing-file import job and return its id. Nothing runs yet: no use case is chosen and no validation starts here. Rank the candidates with POST /v2/erp/imports/{importId}:suggest-use-cases, then start the validate phase with POST /v2/erp/imports/{importId}:validate.",
+        "description": "Register an already-uploaded file (S3 ref) as a pricing-file import job. Returns the job and a file preview. Nothing runs yet: no use case is chosen and no validation starts here. Optionally rank candidates with POST /v2/erp/imports/{importId}:suggest-use-cases, then start validation with POST /v2/erp/imports/{importId}:validate.",
         "tags": [
           "erp-imports"
         ],
@@ -3759,8 +3759,16 @@
           }
         },
         "responses": {
-          "202": {
-            "description": "Import job accepted",
+          "201": {
+            "description": "Import job created",
+            "headers": {
+              "Location": {
+                "description": "URL of the created job (`/v2/erp/imports/{importId}`).",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -3941,7 +3949,7 @@
       "post": {
         "operationId": "suggestErpImportUseCases",
         "summary": "suggestErpImportUseCases",
-        "description": "Rank the org's inbound use cases against this file's columns — the input to the ranked picker (\"matches 6 of your 7 columns\"). Reads only the file's first row, not its data.\nEvery eligible use case is returned, including ones matching nothing: the \"nothing fits, pick anyway\" view needs the full list. Highest match first.\nCSV only — an xlsx import fails with 400 rather than silently returning zero matches, which would look identical to \"we checked and nothing matches\".",
+        "description": "Rank the org's inbound use cases against this file's columns — the input to the ranked picker (\"matches 6 of your 7 columns\"). Optional: skip this and call `:validate` directly when the use case is already known. Reads only the file's first row, not its data.\nEvery eligible use case is returned, including ones matching nothing: the \"nothing fits, pick anyway\" view needs the full list. Highest match first.\nCSV only — an xlsx import fails with 400 rather than silently returning zero matches, which would look identical to \"we checked and nothing matches\".",
         "tags": [
           "erp-imports"
         ],
@@ -4010,7 +4018,7 @@
           }
         },
         "responses": {
-          "200": {
+          "202": {
             "description": "Execution started",
             "content": {
               "application/json": {
@@ -4129,7 +4137,7 @@
           "include_preview": {
             "type": "boolean",
             "default": false,
-            "description": "Return a sample of the file's first rows. Informational only — `:validate` is still the authority. `preview` is present iff this is true."
+            "description": "Return a sample of the file's first rows in `preview`. Only controls whether the sample comes BACK — the head is read either way, because that read is how an unreadable file gets refused."
           }
         }
       },
@@ -4158,7 +4166,6 @@
           "use_case_slug",
           "use_case_name",
           "matched_columns",
-          "file_columns",
           "entity_types"
         ],
         "properties": {
@@ -4181,19 +4188,20 @@
           "matched_columns": {
             "type": "integer",
             "description": "How many of the FILE's columns this use case reads, by exact trimmed name."
-          },
-          "file_columns": {
-            "type": "integer",
-            "description": "Columns in the file. Identical across entries; repeated per entry so each row renders standalone as \"matches N of your M columns\"."
           }
         }
       },
       "SuggestErpImportUseCasesResponse": {
         "type": "object",
         "required": [
+          "file_columns",
           "suggestions"
         ],
         "properties": {
+          "file_columns": {
+            "type": "integer",
+            "description": "Columns in the file. Present even when `suggestions` is empty."
+          },
           "suggestions": {
             "type": "array",
             "items": {
@@ -4215,11 +4223,10 @@
       },
       "ErpImportIssue": {
         "type": "object",
-        "description": "A problem found during validation, scoped to the file as a whole rather than to individual rows. See `code` for the kinds reported.",
+        "description": "A problem found during validation, scoped to the file as a whole rather than to individual rows.\n`code` is the translation key and the other fields are its parameters — there is deliberately no message to display. Each code appears at most once, with everything it has to say aggregated into that one entry.",
         "required": [
           "code",
-          "severity",
-          "message"
+          "severity"
         ],
         "properties": {
           "code": {
@@ -4241,16 +4248,29 @@
               "blocking"
             ]
           },
-          "message": {
-            "type": "string",
-            "description": "User-facing explanation. Lists at most 10 column names; `columns` has all of them."
-          },
           "columns": {
             "type": "array",
-            "description": "The columns this issue is about, so clients render names rather than parsing the message.",
+            "description": "The columns this issue is about, at most one entry per column per entity.\nOn UNIQUE_ID_COLUMN_MISSING the file has NONE of these. Do NOT tell the user that adding one of them is enough: a unique id may read several columns through a JSONata expression, and whether it combines them (`A & B`, both needed) or falls back between them (`A ? A : B`, either will do) is not knowable here.",
             "items": {
-              "type": "string"
+              "type": "object",
+              "required": [
+                "name"
+              ],
+              "properties": {
+                "name": {
+                  "type": "string",
+                  "description": "The column name, spelled as the mapping reads it."
+                },
+                "entity": {
+                  "type": "string",
+                  "description": "Slug of the entity this column helps identify. UNIQUE_ID_COLUMN_MISSING only."
+                }
+              }
             }
+          },
+          "row": {
+            "type": "integer",
+            "description": "The offending data row, 1-based as the user counts rows. MALFORMED_ROW only."
           }
         }
       },
@@ -4269,7 +4289,8 @@
             "description": "Data rows read from the file."
           },
           "blocking": {
-            "type": "integer"
+            "type": "integer",
+            "description": "Blocking problems found, counting per-row ones that are not listed in `issues`."
           },
           "warnings": {
             "type": "integer"
@@ -4283,7 +4304,7 @@
           },
           "issues": {
             "type": "array",
-            "description": "Whole-file issues. At most 20 are kept; the count of everything found is in blocking and warnings. Warnings here are what `ack_warnings` on `:execute` acknowledges.",
+            "description": "Whole-file issues, at most one per `code`. Do not expect the length to match blocking + warnings: those also count per-row problems, which are recorded for support but never listed here. Warnings here are what `ack_warnings` on `:execute` acknowledges.",
             "items": {
               "$ref": "#/components/schemas/ErpImportIssue"
             }
@@ -4309,7 +4330,7 @@
       },
       "ErpImportError": {
         "type": "object",
-        "description": "Why the import failed — present if and only if status = FAILED.",
+        "description": "Why the import failed — present if and only if status = FAILED. `code` is the translation key; for VALIDATION_BLOCKED the specifics are in `validation`.",
         "required": [
           "code",
           "message"
@@ -4331,36 +4352,28 @@
           },
           "message": {
             "type": "string",
-            "description": "User-facing explanation of `type`."
+            "description": "One English sentence, derived from `code` so the two always agree. A fallback for a client that has no translation for this code — prefer translating `code`, and never parse this. It deliberately does NOT restate `validation.issues`."
           }
         }
       },
       "ErpImportFilePreview": {
         "type": "object",
-        "description": "Sample of the file's first rows, using the same parser as `:validate`. `status` is the outcome of this read, not a verdict on the file.",
+        "description": "Sample of the file's first rows, using the same parser as `:validate`. Registration refuses a file it cannot read, so a created job always includes this.",
         "required": [
-          "status"
+          "columns",
+          "rows"
         ],
         "properties": {
-          "status": {
-            "type": "string",
-            "description": "Treat an unrecognized value as \"no preview available\". Values may be added. UNREADABLE covers empty, header-only, malformed, or gone — there is no breakdown; `:validate` reports the reason.",
-            "enum": [
-              "AVAILABLE",
-              "FORMAT_UNSUPPORTED",
-              "UNREADABLE"
-            ]
-          },
           "columns": {
             "type": "array",
-            "description": "Effective column names (trimmed, duplicates collapsed). Set iff `status` is AVAILABLE.",
+            "description": "Effective column names (trimmed, duplicates collapsed).",
             "items": {
               "type": "string"
             }
           },
           "rows": {
             "type": "array",
-            "description": "Up to the first 5 data rows, aligned to `columns`.",
+            "description": "Up to the first 3 data rows, aligned to `columns`.",
             "items": {
               "type": "array",
               "items": {
@@ -4373,12 +4386,11 @@
       "CreateErpImportResponse": {
         "type": "object",
         "required": [
-          "import_id"
+          "job"
         ],
         "properties": {
-          "import_id": {
-            "type": "string",
-            "description": "`imp_{ULID}` — time-ordered, also used as the job's correlation_id."
+          "job": {
+            "$ref": "#/components/schemas/ErpImportJob"
           },
           "preview": {
             "$ref": "#/components/schemas/ErpImportFilePreview"

package/dist/{add-component-UPHG3VNG.js → add-component-TCF7V3KU.js}

@@ -3,7 +3,7 @@ import {
   log,
   readManifest,
   writeManifest
-} from "./chunk-QOD77YLW.js";
+} from "./chunk-UDGF4AVJ.js";
 import "./chunk-M3M3C5WH.js";
 import "./chunk-YHQA2AVG.js";
 import "./chunk-7ZQ666ZQ.js";
@@ -15,16 +15,6 @@ import { existsSync, readFileSync, writeFileSync, readdirSync } from "fs";
 import { resolve, join } from "path";
 var TEMPLATES_REPO = "epilot-dev/app-templates";
 var TEMPLATE_REGISTRY = {
-  CUSTOM_FLOW_ACTION_SANDBOX: {
-    configOnly: false,
-    manifestType: "CUSTOM_FLOW_ACTION",
-    templateDir: "custom-flow-action-sandbox",
-    description: "Sandboxed flow action (JS runs in epilot)",
-    configuration: () => ({
-      type: "sandbox",
-      sandbox_settings: { code: "// code is read from dist/ during deploy" }
-    })
-  },
   CUSTOM_FLOW_ACTION_EXTERNAL: {
     configOnly: true,
     manifestType: "CUSTOM_FLOW_ACTION",