@epilot/cli 0.1.108 → 0.1.109

package/README.md

@@ -29,7 +29,7 @@ npm install -g @epilot/cli
 
 <!-- usage-help -->
 ```
-epilot v0.1.108 — 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/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",

package/dist/add-function-VRVBRNY3.js

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+import {
+  log,
+  readManifest,
+  validateScheduleExpression,
+  writeManifest
+} from "./chunk-UDGF4AVJ.js";
+import "./chunk-M3M3C5WH.js";
+import "./chunk-YHQA2AVG.js";
+import "./chunk-7ZQ666ZQ.js";
+
+// src/commands/app/add-function.ts
+import { defineCommand } from "citty";
+import { existsSync, mkdirSync, writeFileSync } from "fs";
+import { join, resolve } from "path";
+var NAME_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
+var add_function_default = defineCommand({
+  meta: {
+    name: "add-function",
+    description: "Add a server-side function (optionally scheduled) to the app"
+  },
+  args: {
+    name: { type: "positional", description: "Function name (kebab-case)", required: true },
+    type: {
+      type: "string",
+      description: '"workflow" (selectable as flow action) or "scheduled" (cron per installation). Default: scheduled when --schedule is given, workflow otherwise'
+    },
+    schedule: {
+      type: "string",
+      description: 'Cron ("0 3 * * *") or rate ("rate(30 minutes)") expression to run the function once per installation'
+    },
+    label: { type: "string", description: "Display name shown to org admins (e.g. in the flow builder)" },
+    timezone: { type: "string", description: "IANA timezone for cron schedules (default: Europe/Berlin)" },
+    path: { type: "string", description: "Path to manifest.json (default: manifest.json)" }
+  },
+  run: ({ args }) => {
+    const name = args.name;
+    if (!NAME_PATTERN.test(name)) {
+      log.error(`Invalid function name "${name}" \u2014 use kebab-case (a-z, 0-9, dashes; max 64 chars)`);
+      process.exit(1);
+    }
+    const fnType = args.type ?? (args.schedule ? "scheduled" : "workflow");
+    if (fnType !== "workflow" && fnType !== "scheduled") {
+      log.error(`Invalid --type "${args.type}" \u2014 use "workflow" or "scheduled"`);
+      process.exit(1);
+    }
+    if (fnType === "scheduled" && !args.schedule) {
+      log.error("Scheduled functions require --schedule (cron or rate expression)");
+      process.exit(1);
+    }
+    if (fnType === "workflow" && args.schedule) {
+      log.error("Workflow functions cannot have a schedule \u2014 drop --schedule or use --type scheduled");
+      process.exit(1);
+    }
+    if (args.schedule) {
+      const result = validateScheduleExpression(args.schedule);
+      if (!result.valid) {
+        log.error(`Invalid schedule: ${result.error}`);
+        process.exit(1);
+      }
+    }
+    const manifestPath = resolve(args.path ?? "manifest.json");
+    const manifest = readManifest(manifestPath);
+    const rootDir = resolve(manifestPath, "..");
+    if (manifest.functions?.some((fn2) => fn2.name === name)) {
+      log.error(`Function "${name}" already exists in the manifest`);
+      process.exit(1);
+    }
+    const fnDir = join(rootDir, "functions", name);
+    if (existsSync(fnDir)) {
+      log.error(`Directory already exists: ${fnDir}`);
+      process.exit(1);
+    }
+    mkdirSync(join(fnDir, "src"), { recursive: true });
+    writeFileSync(
+      join(fnDir, "package.json"),
+      `${JSON.stringify(
+        {
+          name,
+          private: true,
+          version: "0.0.1",
+          type: "module",
+          scripts: { build: "tsc", dev: "tsx watch src/handler.ts" },
+          devDependencies: { typescript: "~5.8.3", tsx: "^4.0.0" }
+        },
+        null,
+        2
+      )}
+`
+    );
+    writeFileSync(
+      join(fnDir, "tsconfig.json"),
+      `${JSON.stringify(
+        {
+          compilerOptions: {
+            target: "ES2022",
+            lib: ["ES2022", "DOM"],
+            module: "ESNext",
+            moduleResolution: "bundler",
+            strict: true,
+            rootDir: "src",
+            outDir: "dist",
+            esModuleInterop: true,
+            skipLibCheck: true
+          },
+          include: ["src"]
+        },
+        null,
+        2
+      )}
+`
+    );
+    writeFileSync(join(fnDir, "src", "handler.ts"), handlerTemplate(name, fnType, args.schedule));
+    const fn = {
+      name,
+      type: fnType,
+      ...args.label ? { label: { de: args.label } } : {},
+      handler: `./functions/${name}/dist/handler.js`,
+      ...args.schedule ? { schedule: args.schedule } : {},
+      ...args.timezone ? { schedule_timezone: args.timezone } : {}
+    };
+    manifest.functions = [...manifest.functions ?? [], fn];
+    writeManifest(manifestPath, manifest);
+    log.success(`Added ${fnType} function "${name}"`);
+    log.info(`Code:     functions/${name}/src/handler.ts`);
+    if (args.schedule) {
+      log.info(`Schedule: ${args.schedule} (runs once per installation, max 60s per run)`);
+    } else {
+      log.info("Selectable as an action in the flow builder once the app is installed");
+    }
+    log.dim('Build with "npm run build", then "epilot app deploy"');
+  }
+});
+var handlerTemplate = (name, fnType, schedule) => `// App function: ${name}
+//${fnType === "scheduled" ? `
+// Runs automatically ${schedule?.startsWith("rate(") ? `every ${schedule.slice(5, -1)}` : `on "${schedule}"`} \u2014 once per installation,
+// inside the epilot code-execution sandbox with a 60 second budget. Do a
+// bounded amount of work per run; the next tick picks up the rest.` : `
+// Selectable as an action in the flow builder. Runs inside the epilot
+// code-execution sandbox with the triggering entity in \`input.entity\`.`}
+//
+// Runtime contract:
+//   - top-level \`async function handler(input, context)\` \u2014 no \`export\`.
+//   - \`input.trigger\` \u2192 { type: '${fnType === "scheduled" ? "schedule" : "workflow"}', ... }.${fnType === "workflow" ? `
+//   - \`input.entity\` \u2192 the entity the flow ran on.
+//   - \`input.action_config\` \u2192 the action's configuration from the flow builder.` : `
+//   - \`input.org_id\` / \`input.app_id\` \u2192 the installation this run belongs to.`}
+//   - \`context.epilot\` \u2192 the bundled @epilot/sdk, pre-authorized with the app token
+//     (scoped to the app's permissions): \`await context.epilot.entity.searchEntities(...)\`.
+//   - \`context.fetch\` \u2192 plain fetch, e.g. for the app's API proxy or non-prod stages
+//     (derive base URLs from \`input.app_options.stage\`).
+//   - \`input.app_options.token\` \u2192 the raw app token, if you need it for fetch calls.
+//   - Return \`{ skip_reason }\` to skip, \`{ error_reason }\` to fail the run.
+
+interface FunctionInput {
+  trigger?: { type: string; schedule?: string; scheduled_time?: string };
+  org_id?: string;
+  app_id?: string;${fnType === "workflow" ? `
+  entity?: Record<string, unknown>;
+  action_config?: Record<string, unknown>;` : ""}
+  app_options?: { token?: string; stage?: string } & Record<string, unknown>;
+}
+
+interface FunctionContext {
+  /** Bundled @epilot/sdk, pre-authorized \u2014 e.g. context.epilot.entity.searchEntities(...) */
+  epilot: Record<string, any>;
+  fetch: typeof fetch;
+}
+
+async function handler(input: FunctionInput, context: FunctionContext) {
+  const token = input.app_options?.token;
+  if (!token) {
+    return { error_reason: 'Missing app token in execution context.' };
+  }
+
+  // TODO: implement your logic here
+  console.log('${name} run', { trigger: input.trigger?.type, org: input.org_id });
+
+  return { success: true };
+}
+`;
+export {
+  add_function_default as default
+};

package/dist/app-NATUF3YX.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+
+// src/commands/app/index.ts
+import { defineCommand } from "citty";
+var app_default = defineCommand({
+  meta: {
+    name: "app",
+    description: "Manage epilot Apps \u2014 create, deploy, and manage app manifests"
+  },
+  subCommands: {
+    init: () => import("./init-C66L5GFR.js").then((m) => m.default),
+    "add-component": () => import("./add-component-TCF7V3KU.js").then((m) => m.default),
+    "remove-component": () => import("./remove-component-7C7MPSBF.js").then((m) => m.default),
+    "add-function": () => import("./add-function-VRVBRNY3.js").then((m) => m.default),
+    validate: () => import("./validate-J35DJW3H.js").then((m) => m.default),
+    deploy: () => import("./deploy-2U5FVEE7.js").then((m) => m.default),
+    dev: () => import("./dev-JEAHUYQU.js").then((m) => m.default),
+    export: () => import("./export-VLAY2KZP.js").then((m) => m.default),
+    versions: () => import("./versions-2TMTHO7W.js").then((m) => m.default),
+    review: () => import("./review-JZTMQNU3.js").then((m) => m.default),
+    api: () => import("./api-5W2UMWCW.js").then((m) => m.default)
+  }
+});
+export {
+  app_default as default
+};

package/dist/bin/epilot.js

@@ -11,7 +11,7 @@ import { defineCommand } from "citty";
 var main = defineCommand({
   meta: {
     name: "epilot",
-    version: "0.1.108",
+    version: "0.1.109",
     description: "CLI for epilot APIs"
   },
   args: {
@@ -31,12 +31,12 @@ var main = defineCommand({
     profile: () => import("../profile-OZJL5ZPT.js").then((m) => m.default),
     config: () => import("../config-DGZIMLZK.js").then((m) => m.default),
     completion: () => import("../completion-TFHA4W2J.js").then((m) => m.default),
-    upgrade: () => import("../upgrade-HU256V6J.js").then((m) => m.default),
+    upgrade: () => import("../upgrade-5RFPLKLG.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),
     "ai-agents": () => import("../ai-agents-53M2KHPI.js").then((m) => m.default),
-    app: () => import("../app-RULTIGMJ.js").then((m) => m.default),
+    app: () => import("../app-NATUF3YX.js").then((m) => m.default),
     "audit-logs": () => import("../audit-logs-YFRK3EFU.js").then((m) => m.default),
     automation: () => import("../automation-4DEE3TUI.js").then((m) => m.default),
     billing: () => import("../billing-XX4VVOPI.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.108" : (await null).default.version;
+var VERSION = true ? "0.1.109" : (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);