@teamkeel/functions-runtime 0.413.9 → 0.414.1

package/dist/index.d.cts

@@ -352,11 +352,12 @@ type PageOptions<C extends FlowConfig, A extends PageActions[], T extends UIElem
     validate?: (data: ExtractFormData<T>) => Promise<true | string>;
     actions?: A;
 };
-type UiPage<C extends FlowConfig> = <T extends UIElements, const A extends PageActions[] = []>(name: string, options: PageOptions<C, A, T>) => A["length"] extends 0 ? ExtractFormData<T> : {
+type UiPage<C extends FlowConfig> = <T extends UIElements, const A extends PageActions[] = []>(name: string, options: PageOptions<C, A, T>) => Promise<A["length"] extends 0 ? ExtractFormData<T> : {
     data: ExtractFormData<T>;
     action: ActionValue<A[number]>;
-};
-type PageActions = string | {
+}>;
+type PageActions = string | PageActionConfig;
+type PageActionConfig = {
     label: string;
     value: string;
     mode?: "primary" | "secondary" | "destructive";
@@ -545,19 +546,31 @@ type UIApiResponses = {
     };
 };
 
-interface FlowContext<C extends FlowConfig> {
+interface FlowContext<C extends FlowConfig, E = any, S = any> {
     step: Step<C>;
     ui: UI<C>;
+    env: E;
+    now: Date;
+    secrets: S;
 }
 type JsonSerializable = string | number | boolean | null | JsonSerializable[] | {
     [key: string]: JsonSerializable;
 };
 type Step<C extends FlowConfig> = {
-    <R extends JsonSerializable | void>(name: string, options: {
+    <R extends JsonSerializable | void>(
+    /** The unique name of this step. */
+    name: string, 
+    /** Configuration options for the step. */
+    options: {
+        /** The stage this step belongs to. Used for organising steps in the UI. */
         stage?: ExtractStageKeys<C>;
-        maxRetries?: number;
-        timeoutInMs?: number;
-    }, fn: () => Promise<R> & {
+        /** Number of times to retry the step if it fails. Defaults to 5. */
+        retries?: number;
+        /** Maximum time in milliseconds to wait for the step to complete. Defaults to 60000 (1 minute). */
+        timeout?: number;
+    }, 
+    /** The step function to execute. */
+    fn: () => Promise<R> & {
         catch: (errorHandler: (err: Error) => Promise<void> | void) => Promise<any>;
     }): Promise<R>;
     <R extends JsonSerializable | void>(name: string, fn: () => Promise<R> & {
@@ -565,8 +578,11 @@ type Step<C extends FlowConfig> = {
     }): Promise<R>;
 };
 interface FlowConfig {
+    /** The stages to organise the steps in the flow. */
     stages?: StageConfig[];
+    /** The title of the flow as shown in the Console. */
     title?: string;
+    /** The description of the flow as shown in the Console. */
     description?: string;
 }
 interface FlowConfigAPI {
@@ -574,20 +590,28 @@ interface FlowConfigAPI {
     title: string;
     description?: string;
 }
-type FlowFunction<C extends FlowConfig, I extends any = {}> = (ctx: FlowContext<C>, inputs: I) => Promise<void>;
+type FlowFunction<C extends FlowConfig, E extends any = {}, S extends any = {}, I extends any = {}> = (ctx: FlowContext<C, E, S>, inputs: I) => Promise<void>;
 type ExtractStageKeys<T extends FlowConfig> = T extends {
     stages: infer S;
 } ? S extends ReadonlyArray<infer U> ? U extends string ? U : U extends {
     key: infer K extends string;
 } ? K : never : never : never;
 type StageConfigObject = {
+    /** The unique key of the stage. */
     key: string;
+    /** The name of the stage as shown in the Console. */
     name: string;
+    /** The description of the stage as shown in the Console. */
     description?: string;
+    /** Whether the stage is initially hidden in the Console. */
     initiallyHidden?: boolean;
 };
 type StageConfig = string | StageConfigObject;
-declare function createFlowContext<C extends FlowConfig>(runId: string, data: any, spanId: string): FlowContext<C>;
+declare function createFlowContext<C extends FlowConfig, E = any, S = any>(runId: string, data: any, action: string | null, spanId: string, ctx: {
+    env: E;
+    now: Date;
+    secrets: S;
+}): FlowContext<C, E, S>;
 
 declare function ksuid(): string;
 

package/dist/index.d.ts

@@ -352,11 +352,12 @@ type PageOptions<C extends FlowConfig, A extends PageActions[], T extends UIElem
     validate?: (data: ExtractFormData<T>) => Promise<true | string>;
     actions?: A;
 };
-type UiPage<C extends FlowConfig> = <T extends UIElements, const A extends PageActions[] = []>(name: string, options: PageOptions<C, A, T>) => A["length"] extends 0 ? ExtractFormData<T> : {
+type UiPage<C extends FlowConfig> = <T extends UIElements, const A extends PageActions[] = []>(name: string, options: PageOptions<C, A, T>) => Promise<A["length"] extends 0 ? ExtractFormData<T> : {
     data: ExtractFormData<T>;
     action: ActionValue<A[number]>;
-};
-type PageActions = string | {
+}>;
+type PageActions = string | PageActionConfig;
+type PageActionConfig = {
     label: string;
     value: string;
     mode?: "primary" | "secondary" | "destructive";
@@ -545,19 +546,31 @@ type UIApiResponses = {
     };
 };
 
-interface FlowContext<C extends FlowConfig> {
+interface FlowContext<C extends FlowConfig, E = any, S = any> {
     step: Step<C>;
     ui: UI<C>;
+    env: E;
+    now: Date;
+    secrets: S;
 }
 type JsonSerializable = string | number | boolean | null | JsonSerializable[] | {
     [key: string]: JsonSerializable;
 };
 type Step<C extends FlowConfig> = {
-    <R extends JsonSerializable | void>(name: string, options: {
+    <R extends JsonSerializable | void>(
+    /** The unique name of this step. */
+    name: string, 
+    /** Configuration options for the step. */
+    options: {
+        /** The stage this step belongs to. Used for organising steps in the UI. */
         stage?: ExtractStageKeys<C>;
-        maxRetries?: number;
-        timeoutInMs?: number;
-    }, fn: () => Promise<R> & {
+        /** Number of times to retry the step if it fails. Defaults to 5. */
+        retries?: number;
+        /** Maximum time in milliseconds to wait for the step to complete. Defaults to 60000 (1 minute). */
+        timeout?: number;
+    }, 
+    /** The step function to execute. */
+    fn: () => Promise<R> & {
         catch: (errorHandler: (err: Error) => Promise<void> | void) => Promise<any>;
     }): Promise<R>;
     <R extends JsonSerializable | void>(name: string, fn: () => Promise<R> & {
@@ -565,8 +578,11 @@ type Step<C extends FlowConfig> = {
     }): Promise<R>;
 };
 interface FlowConfig {
+    /** The stages to organise the steps in the flow. */
     stages?: StageConfig[];
+    /** The title of the flow as shown in the Console. */
     title?: string;
+    /** The description of the flow as shown in the Console. */
     description?: string;
 }
 interface FlowConfigAPI {
@@ -574,20 +590,28 @@ interface FlowConfigAPI {
     title: string;
     description?: string;
 }
-type FlowFunction<C extends FlowConfig, I extends any = {}> = (ctx: FlowContext<C>, inputs: I) => Promise<void>;
+type FlowFunction<C extends FlowConfig, E extends any = {}, S extends any = {}, I extends any = {}> = (ctx: FlowContext<C, E, S>, inputs: I) => Promise<void>;
 type ExtractStageKeys<T extends FlowConfig> = T extends {
     stages: infer S;
 } ? S extends ReadonlyArray<infer U> ? U extends string ? U : U extends {
     key: infer K extends string;
 } ? K : never : never : never;
 type StageConfigObject = {
+    /** The unique key of the stage. */
     key: string;
+    /** The name of the stage as shown in the Console. */
     name: string;
+    /** The description of the stage as shown in the Console. */
     description?: string;
+    /** Whether the stage is initially hidden in the Console. */
     initiallyHidden?: boolean;
 };
 type StageConfig = string | StageConfigObject;
-declare function createFlowContext<C extends FlowConfig>(runId: string, data: any, spanId: string): FlowContext<C>;
+declare function createFlowContext<C extends FlowConfig, E = any, S = any>(runId: string, data: any, action: string | null, spanId: string, ctx: {
+    env: E;
+    now: Date;
+    secrets: S;
+}): FlowContext<C, E, S>;
 
 declare function ksuid(): string;
 

package/dist/index.js

@@ -2430,9 +2430,16 @@ var selectOne = /* @__PURE__ */ __name((name, options) => {
 }, "selectOne");
 
 // src/flows/ui/page.ts
-async function page(options, data) {
+async function page(options, data, action) {
   const content = options.content;
   let hasValidationErrors = false;
+  if (options.actions) {
+    const isValidAction = options.actions.some((a) => {
+      if (typeof a === "string") return a === action;
+      return a && typeof a === "object" && "value" in a && a.value === action;
+    });
+    hasValidationErrors = !isValidAction;
+  }
   const contentUiConfig = await Promise.all(
     content.map(async (c) => {
       const isInput = "__type" in c && c.__type == "input";
@@ -2457,7 +2464,14 @@ async function page(options, data) {
       title: options.title,
       description: options.description,
       content: contentUiConfig,
-      actions: options.actions
+      actions: options.actions?.map((a) => {
+        if (typeof a === "string") {
+          return { label: a, value: a, mode: "primary" };
+        } else if (typeof a === "object") {
+          a.mode = a.mode || "primary";
+        }
+        return a;
+      })
     },
     hasValidationErrors
   };
@@ -2583,15 +2597,33 @@ var header = /* @__PURE__ */ __name((options) => {
 
 // src/flows/index.ts
 var defaultOpts = {
-  maxRetries: 5,
-  timeoutInMs: 6e4
+  retries: 5,
+  timeout: 6e4
 };
-function createFlowContext(runId, data, spanId) {
+function createFlowContext(runId, data, action, spanId, ctx) {
+  const usedNames = /* @__PURE__ */ new Set();
   return {
+    env: ctx.env,
+    now: ctx.now,
+    secrets: ctx.secrets,
     step: /* @__PURE__ */ __name(async (name, optionsOrFn, fn) => {
       const options = typeof optionsOrFn === "function" ? {} : optionsOrFn;
       const actualFn = typeof optionsOrFn === "function" ? optionsOrFn : fn;
       const db = useDatabase();
+      if (usedNames.has(name)) {
+        await db.insertInto("keel.flow_step").values({
+          run_id: runId,
+          name,
+          stage: options.stage,
+          status: "FAILED" /* FAILED */,
+          type: "FUNCTION" /* FUNCTION */,
+          error: `Duplicate step name: ${name}`,
+          startTime: /* @__PURE__ */ new Date(),
+          endTime: /* @__PURE__ */ new Date()
+        }).returningAll().executeTakeFirst();
+        throw new Error(`Duplicate step name: ${name}`);
+      }
+      usedNames.add(name);
       const past = await db.selectFrom("keel.flow_step").where("run_id", "=", runId).where("name", "=", name).selectAll().execute();
       const newSteps = past.filter((step) => step.status === "NEW" /* NEW */);
       const completedSteps = past.filter(
@@ -2622,7 +2654,7 @@ function createFlowContext(runId, data, spanId) {
         try {
           result = await withTimeout(
             actualFn(),
-            options.timeoutInMs ?? defaultOpts.timeoutInMs
+            options.timeout ?? defaultOpts.timeout
           );
         } catch (e) {
           await db.updateTable("keel.flow_step").set({
@@ -2631,7 +2663,7 @@ function createFlowContext(runId, data, spanId) {
             endTime: /* @__PURE__ */ new Date(),
             error: e instanceof Error ? e.message : "An error occurred"
           }).where("id", "=", newSteps[0].id).returningAll().executeTakeFirst();
-          if (failedSteps.length + 1 >= (options.maxRetries ?? defaultOpts.maxRetries)) {
+          if (failedSteps.length + 1 >= (options.retries ?? defaultOpts.retries)) {
             throw new ExhuastedRetriesDisrupt();
           }
           await db.insertInto("keel.flow_step").values({
@@ -2663,8 +2695,25 @@ function createFlowContext(runId, data, spanId) {
     ui: {
       page: /* @__PURE__ */ __name(async (name, options) => {
         const db = useDatabase();
+        if (usedNames.has(name)) {
+          await db.insertInto("keel.flow_step").values({
+            run_id: runId,
+            name,
+            stage: options.stage,
+            status: "FAILED" /* FAILED */,
+            type: "UI" /* UI */,
+            error: `Duplicate step name: ${name}`,
+            startTime: /* @__PURE__ */ new Date(),
+            endTime: /* @__PURE__ */ new Date()
+          }).returningAll().executeTakeFirst();
+          throw new Error(`Duplicate step name: ${name}`);
+        }
+        usedNames.add(name);
         let step = await db.selectFrom("keel.flow_step").where("run_id", "=", runId).where("name", "=", name).selectAll().executeTakeFirst();
         if (step && step.status === "COMPLETED" /* COMPLETED */) {
+          if (step.action) {
+            return { data: step.value, action: step.action };
+          }
           return step.value;
         }
         if (!step) {
@@ -2676,22 +2725,29 @@ function createFlowContext(runId, data, spanId) {
             type: "UI" /* UI */,
             startTime: /* @__PURE__ */ new Date()
           }).returningAll().executeTakeFirst();
-          throw new UIRenderDisrupt(step?.id, (await page(options, null)).page);
+          throw new UIRenderDisrupt(
+            step?.id,
+            (await page(options, null, null)).page
+          );
         }
         if (!data) {
-          throw new UIRenderDisrupt(step?.id, (await page(options, null)).page);
+          throw new UIRenderDisrupt(
+            step?.id,
+            (await page(options, null, null)).page
+          );
         }
-        const p = await page(options, data);
+        const p = await page(options, data, action);
         if (p.hasValidationErrors) {
           throw new UIRenderDisrupt(step?.id, p.page);
         }
         await db.updateTable("keel.flow_step").set({
           status: "COMPLETED" /* COMPLETED */,
           value: JSON.stringify(data),
+          action,
           spanId,
           endTime: /* @__PURE__ */ new Date()
         }).where("id", "=", step.id).returningAll().executeTakeFirst();
-        return data;
+        return { data, action };
       }, "page"),
       inputs: {
         text: textInput,
@@ -2746,7 +2802,7 @@ async function handleFlow(request, config) {
         if (!runId) {
           throw new Error("no runId provided");
         }
-        const { flows } = config;
+        const { flows, createFlowContextAPI } = config;
         if (!(request.method in flows)) {
           const message = `no corresponding flow found for '${request.method}'`;
           span.setStatus({
@@ -2765,7 +2821,11 @@ async function handleFlow(request, config) {
         const ctx = createFlowContext(
           request.meta.runId,
           request.meta.data,
-          span.spanContext().spanId
+          request.meta.action,
+          span.spanContext().spanId,
+          createFlowContextAPI({
+            meta: request.meta
+          })
         );
         const flowFunction = flows[request.method].fn;
         const rawFlowConfig = flows[request.method].config;