@teamkeel/testing-runtime 0.463.1 → 0.465.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teamkeel/testing-runtime",
-  "version": "0.463.1",
+  "version": "0.465.0",
   "description": "Internal package used by the generated @teamkeel/testing package",
   "exports": "./src/index.mjs",
   "typings": "src/index.d.ts",

package/src/FlowExecutor.mjs

@@ -1,6 +1,13 @@
 import jwt from "jsonwebtoken";
 import { parseInputs, parseOutputs, reviver } from "./parsing.mjs";
 
+// Interval (ms) between flow-run status polls in untilFinished/untilAwaitingInput.
+// A lower interval means less dead wait per flow assertion (at the cost of a few
+// more cheap status requests); overridable via env for tuning. In a test suite with
+// many flow assertions the previous 50ms floor added up to meaningful wall-clock.
+const FLOW_POLL_INTERVAL_MS =
+  Number(process.env.KEEL_FLOW_POLL_INTERVAL_MS) || 10;
+
 export class FlowExecutor {
   constructor(props) {
     this._flowUrl =
@@ -78,29 +85,53 @@ export class FlowExecutor {
     }).then(handleResponse);
   }
 
-  async signedLink(options = {}) {
-    const body = {};
-    if (options.inputs !== undefined) body.inputs = options.inputs;
-    if (options.reusable !== undefined) body.reusable = options.reusable;
-    if (options.expiresAt !== undefined && options.expiresAt !== null) {
-      body.expiresAt =
-        options.expiresAt instanceof Date
-          ? options.expiresAt.toISOString()
-          : options.expiresAt;
-    }
-
-    const result = await fetch(this._flowUrl + "/share", {
-      method: "POST",
-      body: JSON.stringify(body),
-      headers: this.headers(),
-    }).then(handleResponse);
+  // The signed-link management namespace for this flow: create, list and revoke signed links. The
+  // generated testing types only expose `signedLinks` on flows declared with @externalAccess.
+  get signedLinks() {
+    const flowUrl = this._flowUrl;
+    const headers = () => this.headers();
 
     return {
-      url: result.url,
-      expiresAt: result.expiresAt ? new Date(result.expiresAt) : null,
-      flow: {
-        name: result.flow?.name ?? this._name,
-        runId: result.flow?.runId ?? null,
+      async create(options = {}) {
+        const body = {};
+        if (options.inputs !== undefined) body.inputs = options.inputs;
+        if (options.reusable !== undefined) body.reusable = options.reusable;
+        if (options.expiresAt !== undefined && options.expiresAt !== null) {
+          body.expiresAt =
+            options.expiresAt instanceof Date
+              ? options.expiresAt.toISOString()
+              : options.expiresAt;
+        }
+
+        return fetch(flowUrl + "/share", {
+          method: "POST",
+          body: JSON.stringify(body),
+          headers: headers(),
+        }).then(handleResponse);
+      },
+
+      async list(options = {}) {
+        let url = flowUrl + "/share";
+        if (options.status !== undefined && options.status !== null) {
+          const queryString = new URLSearchParams({
+            status: options.status,
+          }).toString();
+          url = `${url}?${queryString}`;
+        }
+
+        const result = await fetch(url, {
+          method: "GET",
+          headers: headers(),
+        }).then(handleResponse);
+
+        return { results: result.signedLinks || [] };
+      },
+
+      async revoke(linkId) {
+        return fetch(flowUrl + "/share/" + encodeURIComponent(linkId), {
+          method: "DELETE",
+          headers: headers(),
+        }).then(handleResponse);
       },
     };
   }
@@ -172,7 +203,9 @@ export class FlowExecutor {
         return flow;
       }
 
-      await new Promise((resolve) => setTimeout(resolve, 50));
+      await new Promise((resolve) =>
+        setTimeout(resolve, FLOW_POLL_INTERVAL_MS)
+      );
     }
   }
 
@@ -204,7 +237,9 @@ export class FlowExecutor {
         );
       }
 
-      await new Promise((resolve) => setTimeout(resolve, 50));
+      await new Promise((resolve) =>
+        setTimeout(resolve, FLOW_POLL_INTERVAL_MS)
+      );
     }
   }
 }

package/src/index.d.ts

@@ -138,19 +138,10 @@ export type UIElement =
 // Union type for UI configurations
 export type UIConfig = UIPage | UIComplete;
 
-declare class FlowExecutor<Input = {}> {
+export declare class FlowExecutor<Input = {}> {
   withIdentity(identity: sdk.Identity): FlowExecutor<Input>;
   withAuthToken(token: string): FlowExecutor<Input>;
   start(inputs: Input): Promise<FlowRun<Input>>;
-  signedLink(options?: {
-    inputs?: Input;
-    expiresAt?: Date;
-    reusable?: boolean;
-  }): Promise<{
-    url: string;
-    expiresAt: Date | null;
-    flow: { name: string; runId: string | null };
-  }>;
   get(id: string): Promise<FlowRun<Input>>;
   cancel(id: string): Promise<FlowRun<Input>>;
   back(id: string): Promise<FlowRun<Input>>;
@@ -171,6 +162,63 @@ declare class FlowExecutor<Input = {}> {
   untilFinished(id: string, timeout?: number): Promise<FlowRun<Input>>;
 }
 
+// The signed-link management namespace exposed on a shareable flow's executor as `signedLinks`.
+export interface SignedLinksAPI<Input = {}> {
+  // Mint a signed link that lets an external, unauthenticated actor execute this flow.
+  create(options?: {
+    inputs?: Input;
+    expiresAt?: Date;
+    reusable?: boolean;
+  }): Promise<SignedLinkRecord>;
+  // List the signed links minted for this flow, optionally filtered by status.
+  list(options?: {
+    status?: "active" | "revoked" | "expired";
+  }): Promise<{ results: SignedLinkRecord[] }>;
+  // Revoke a signed link by id so it can no longer be opened. Idempotent.
+  revoke(linkId: string): Promise<SignedLinkRecord>;
+}
+
+// A FlowExecutor for flows declared with @externalAccess: adds the signed-link management
+// namespace. Runtime-wise there is a single FlowExecutor class; this declaration-only split lets
+// generated testing types expose `signedLinks` only on shareable flows.
+export declare class ShareableFlowExecutor<
+  Input = {},
+> extends FlowExecutor<Input> {
+  withIdentity(identity: sdk.Identity): ShareableFlowExecutor<Input>;
+  withAuthToken(token: string): ShareableFlowExecutor<Input>;
+  readonly signedLinks: SignedLinksAPI<Input>;
+}
+
+// A persisted shareable signed link for a flow. The shareable url is exposed so the link can be
+// re-shared; the raw token/hash is never exposed. url is absent for links minted before the token
+// was persisted.
+export interface SignedLinkRecord {
+  id: string;
+  flowName: string;
+  inputs: Record<string, any> | null;
+  reusable: boolean;
+  createdBy: string | null;
+  expiresAt: Date | null;
+  usedCount: number;
+  revokedAt: Date | null;
+  createdAt: Date;
+  updatedAt: Date;
+  status: "active" | "revoked" | "expired";
+  url?: string;
+}
+
+// Live progress snapshot reported by a step while it runs
+export interface StepProgress {
+  message?: string;
+  current?: number;
+  total?: number;
+  unit?: string;
+  counter?: "count" | "percent" | "none";
+  logs?: string[];
+  data?: Record<string, unknown>;
+  updatedAt: string;
+}
+
 // Step Definition
 export interface FlowStep {
   id: string;
@@ -186,6 +234,7 @@ export interface FlowStep {
   createdAt: string;
   updatedAt: string;
   ui: UIConfig | null;
+  progress: StepProgress | null;
 }
 
 // Flow Run Definition

package/src/index.mjs

@@ -1,6 +1,9 @@
 export { sql } from "kysely";
 export { ActionExecutor } from "./ActionExecutor.mjs";
 export { FlowExecutor } from "./FlowExecutor.mjs";
+// ShareableFlowExecutor is a declaration-only refinement of FlowExecutor (see index.d.ts); at
+// runtime they are the same class.
+export { FlowExecutor as ShareableFlowExecutor } from "./FlowExecutor.mjs";
 export { JobExecutor } from "./JobExecutor.mjs";
 export { SubscriberExecutor } from "./SubscriberExecutor.mjs";
 export { toHaveError } from "./toHaveError.mjs";