windmill-client 1.769.0 → 1.771.0

package/dist/client.d.ts

@@ -448,7 +448,11 @@ export declare let _workflowCtx: WorkflowCtx | null;
 export declare function setWorkflowCtx(ctx: WorkflowCtx | null): void;
 export declare class WorkflowCtx {
     private completed;
+    /** Null-prototype: step keys are caller-supplied, and a plain object would
+     *  resolve `toString`/`constructor`/`__proto__` off `Object.prototype`. */
     private counters;
+    /** Every key handed out by `_allocKey`, so distinct names can't alias one key. */
+    private _usedKeys;
     private pending;
     private _suspended;
     /** When set, the task matching this key executes its inner function directly */
@@ -464,7 +468,10 @@ export declare class WorkflowCtx {
      *  `completed_steps[key]`. Initialized to a resolved promise. */
     private _inlineChain;
     constructor(checkpoint?: Record<string, any>);
-    /** Name-based key: `double` for first call, `double_2`, `double_3` for subsequent. */
+    /** Name-based key: `double` for first call, `double_2`, `double_3` for subsequent.
+     *  Suffixing alone can alias — a second `step("x")` and a first `step("x_2")` both
+     *  want `x_2` — so keep bumping past keys already handed out. Allocation order is
+     *  fixed by the workflow body, so replays reproduce the same keys. */
     _allocKey(name: string): string;
     _nextStep(name: string, script: string, args?: Record<string, any>, dispatch_type?: string, options?: TaskOptions): PromiseLike<any>;
     /** Return and clear any pending (unawaited) steps. */
@@ -479,6 +486,7 @@ export declare class WorkflowCtx {
         timeout?: number;
         form?: object;
         selfApproval?: boolean;
+        key?: string;
     }): PromiseLike<{
         value: any;
         approver: string;
@@ -529,23 +537,51 @@ export declare function workflow<T>(fn: (...args: any[]) => Promise<T>): (...arg
 /**
  * Suspend the workflow and wait for an external approval.
  *
- * Use `getResumeUrls()` (wrapped in `step()`) to obtain resume/cancel/approvalPage
- * URLs before calling this function.
+ * Pass `key` to name the step, then `getApprovalUrls(key)` yields the URLs that
+ * resume exactly this approval — route them through your own channel. Without a
+ * key the steps are named `approval`, `approval_2`, ...
  *
  * @example
- * const urls = await step("urls", () => getResumeUrls());
- * await step("notify", () => sendEmail(urls.approvalPage));
- * const { value, approver } = await waitForApproval({ timeout: 3600 });
+ * const urls = await step("urls", () => getApprovalUrls("manager"));
+ * await step("notify", () => sendEmail(urls.resume, urls.cancel));
+ * const { value, approver } = await waitForApproval({ key: "manager", timeout: 3600 });
  */
 export declare function waitForApproval(options?: {
     timeout?: number;
     form?: object;
     selfApproval?: boolean;
+    key?: string;
 }): PromiseLike<{
     value: any;
     approver: string;
     approved: boolean;
 }>;
+/**
+ * Resume/cancel/approval-page URLs bound to one `waitForApproval` step.
+ *
+ * Unlike `getResumeUrls()`, which signs a random nonce, these address the very
+ * `resume_job` record the step's built-in approval buttons use, so they are
+ * stable across replays and safe to embed in a custom notification.
+ *
+ * `stepKey` must match the `key` given to `waitForApproval`. Keys must be unique
+ * within a workflow; reusing one throws rather than silently renaming it. The URL
+ * only resumes while that step is awaiting approval; used at any other moment it is
+ * rejected rather than banking a row a different approval would consume. Send it
+ * ahead of time — approvers just cannot act before the workflow reaches the step.
+ *
+ * `resume` and `cancel` are step-bound; `approvalPage` is not — it opens the job's
+ * approval page, which acts on whichever approval is pending when it is used.
+ *
+ * @example
+ * const urls = await step("urls", () => getApprovalUrls("manager"));
+ * await step("notify", () => sendEmail(urls.resume, urls.cancel));
+ * await waitForApproval({ key: "manager" });
+ */
+export declare function getApprovalUrls(stepKey?: string, approver?: string): Promise<{
+    approvalPage: string;
+    resume: string;
+    cancel: string;
+}>;
 /**
  * Process items in parallel with optional concurrency control.
  *

package/dist/client.mjs

@@ -958,6 +958,13 @@ var StepSuspend = class extends Error {
 		this.name = "StepSuspend";
 	}
 };
+/** A step key travels as one path segment when its URLs are minted, so it must be
+*  non-empty and free of `/` and dot segments — otherwise `waitForApproval` would
+*  accept a key `getApprovalUrls` can never address. */
+function assertUsableStepKey(key, what) {
+	const k = key.trim();
+	if (k === "" || k === "." || k === ".." || key.includes("/") || key.includes("\\")) throw new Error(`${what} must be a non-empty step name without \`/\` or dot segments`);
+}
 let _workflowCtx = null;
 function setWorkflowCtx(ctx) {
 	_workflowCtx = ctx;
@@ -965,7 +972,11 @@ function setWorkflowCtx(ctx) {
 }
 var WorkflowCtx = class {
 	completed;
-	counters = {};
+	/** Null-prototype: step keys are caller-supplied, and a plain object would
+	*  resolve `toString`/`constructor`/`__proto__` off `Object.prototype`. */
+	counters = Object.create(null);
+	/** Every key handed out by `_allocKey`, so distinct names can't alias one key. */
+	_usedKeys = new Set();
 	pending = [];
 	_suspended = false;
 	/** When set, the task matching this key executes its inner function directly */
@@ -981,14 +992,23 @@ var WorkflowCtx = class {
 	*  `completed_steps[key]`. Initialized to a resolved promise. */
 	_inlineChain = Promise.resolve();
 	constructor(checkpoint = {}) {
-		this.completed = checkpoint?.completed_steps ?? {};
+		this.completed = Object.assign(Object.create(null), checkpoint?.completed_steps ?? {});
 		this._executingKey = checkpoint?._executing_key ?? null;
 	}
-	/** Name-based key: `double` for first call, `double_2`, `double_3` for subsequent. */
+	/** Name-based key: `double` for first call, `double_2`, `double_3` for subsequent.
+	*  Suffixing alone can alias — a second `step("x")` and a first `step("x_2")` both
+	*  want `x_2` — so keep bumping past keys already handed out. Allocation order is
+	*  fixed by the workflow body, so replays reproduce the same keys. */
 	_allocKey(name) {
-		const n = (this.counters[name] ?? 0) + 1;
+		let n = (this.counters[name] ?? 0) + 1;
+		let key = n === 1 ? name : `${name}_${n}`;
+		while (this._usedKeys.has(key)) {
+			n++;
+			key = `${name}_${n}`;
+		}
 		this.counters[name] = n;
-		return n === 1 ? name : `${name}_${n}`;
+		this._usedKeys.add(key);
+		return key;
 	}
 	_nextStep(name, script, args = {}, dispatch_type = "inline", options) {
 		const key = this._allocKey(name || script || "step");
@@ -1048,7 +1068,9 @@ var WorkflowCtx = class {
 		return steps;
 	}
 	_waitForApproval(options) {
-		const key = this._allocKey("approval");
+		if (options?.key !== void 0) assertUsableStepKey(options.key, "waitForApproval key");
+		const key = this._allocKey(options?.key || "approval");
+		if (options?.key && key !== options.key) throw new Error(`WAC step key "${options.key}" is already used in this workflow. Give each waitForApproval() its own key so getApprovalUrls() can address it.`);
 		if (key in this.completed) {
 			const value = this.completed[key];
 			return { then: (resolve) => resolve(value) };
@@ -1287,13 +1309,14 @@ function workflow(fn) {
 /**
 * Suspend the workflow and wait for an external approval.
 *
-* Use `getResumeUrls()` (wrapped in `step()`) to obtain resume/cancel/approvalPage
-* URLs before calling this function.
+* Pass `key` to name the step, then `getApprovalUrls(key)` yields the URLs that
+* resume exactly this approval — route them through your own channel. Without a
+* key the steps are named `approval`, `approval_2`, ...
 *
 * @example
-* const urls = await step("urls", () => getResumeUrls());
-* await step("notify", () => sendEmail(urls.approvalPage));
-* const { value, approver } = await waitForApproval({ timeout: 3600 });
+* const urls = await step("urls", () => getApprovalUrls("manager"));
+* await step("notify", () => sendEmail(urls.resume, urls.cancel));
+* const { value, approver } = await waitForApproval({ key: "manager", timeout: 3600 });
 */
 function waitForApproval(options) {
 	const ctx = _workflowCtx ?? Reflect.get(globalThis, "__wmill_wf_ctx");
@@ -1301,6 +1324,37 @@ function waitForApproval(options) {
 	return ctx._waitForApproval(options);
 }
 /**
+* Resume/cancel/approval-page URLs bound to one `waitForApproval` step.
+*
+* Unlike `getResumeUrls()`, which signs a random nonce, these address the very
+* `resume_job` record the step's built-in approval buttons use, so they are
+* stable across replays and safe to embed in a custom notification.
+*
+* `stepKey` must match the `key` given to `waitForApproval`. Keys must be unique
+* within a workflow; reusing one throws rather than silently renaming it. The URL
+* only resumes while that step is awaiting approval; used at any other moment it is
+* rejected rather than banking a row a different approval would consume. Send it
+* ahead of time — approvers just cannot act before the workflow reaches the step.
+*
+* `resume` and `cancel` are step-bound; `approvalPage` is not — it opens the job's
+* approval page, which acts on whichever approval is pending when it is used.
+*
+* @example
+* const urls = await step("urls", () => getApprovalUrls("manager"));
+* await step("notify", () => sendEmail(urls.resume, urls.cancel));
+* await waitForApproval({ key: "manager" });
+*/
+async function getApprovalUrls(stepKey = "approval", approver) {
+	assertUsableStepKey(stepKey, "getApprovalUrls stepKey");
+	const workspace = getWorkspace();
+	return await JobService.getWacApprovalUrls({
+		workspace,
+		stepKey,
+		approver,
+		id: getEnv("WM_JOB_ID") ?? "NO_JOB_ID"
+	});
+}
+/**
 * Process items in parallel with optional concurrency control.
 *
 * Each item is processed by calling `fn(item)`, which should be a task().
@@ -1342,4 +1396,4 @@ async function commitKafkaOffsets(triggerPath, topic, partition, offset) {
 }
 
 //#endregion
-export { SHARED_FOLDER, StepSuspend, WorkflowCtx, _workflowCtx, appendToResultStream, base64ToUint8Array, commitKafkaOffsets, databaseUrlFromResource, deleteS3File, denoS3LightClientSettings, getEnv, getFlowUserState, getIdToken, getInternalState, getPresignedS3PublicUrl, getPresignedS3PublicUrls, getProgress, getResource, getResult, getResultMaybe, getResumeEndpoints, getResumeUrls, getRootJobId, getState, getStatePath, getVariable, getWorkspace, loadS3File, loadS3FileStream, parallel, requestInteractiveSlackApproval, requestInteractiveTeamsApproval, resolveDefaultResource, runFlow, runFlowAsync, runScript, runScriptAsync, runScriptByHash, runScriptByHashAsync, runScriptByPath, runScriptByPathAsync, setClient, setFlowUserState, setInternalState, setProgress, setResource, setState, setVariable, setWorkflowCtx, signS3Object, signS3Objects, sleep, step, streamResult, task, taskFlow, taskScript, uint8ArrayToBase64, usernameToEmail, waitForApproval, waitJob, workerHasInternalServer, workflow, writeS3File };
+export { SHARED_FOLDER, StepSuspend, WorkflowCtx, _workflowCtx, appendToResultStream, base64ToUint8Array, commitKafkaOffsets, databaseUrlFromResource, deleteS3File, denoS3LightClientSettings, getApprovalUrls, getEnv, getFlowUserState, getIdToken, getInternalState, getPresignedS3PublicUrl, getPresignedS3PublicUrls, getProgress, getResource, getResult, getResultMaybe, getResumeEndpoints, getResumeUrls, getRootJobId, getState, getStatePath, getVariable, getWorkspace, loadS3File, loadS3FileStream, parallel, requestInteractiveSlackApproval, requestInteractiveTeamsApproval, resolveDefaultResource, runFlow, runFlowAsync, runScript, runScriptAsync, runScriptByHash, runScriptByHashAsync, runScriptByPath, runScriptByPathAsync, setClient, setFlowUserState, setInternalState, setProgress, setResource, setState, setVariable, setWorkflowCtx, signS3Object, signS3Objects, sleep, step, streamResult, task, taskFlow, taskScript, uint8ArrayToBase64, usernameToEmail, waitForApproval, waitJob, workerHasInternalServer, workflow, writeS3File };

package/dist/core/OpenAPI.mjs

@@ -29,7 +29,7 @@ const OpenAPI = {
 	PASSWORD: void 0,
 	TOKEN: getEnv("WM_TOKEN"),
 	USERNAME: void 0,
-	VERSION: "1.769.0",
+	VERSION: "1.771.0",
 	WITH_CREDENTIALS: true,
 	interceptors: {
 		request: new Interceptors(),

package/dist/index.d.ts

@@ -4,8 +4,8 @@ export { OpenAPI, type OpenAPIConfig } from './core/OpenAPI';
 export * from './services.gen';
 export * from './types.gen';
 export type { DenoS3LightClientSettings } from "./s3Types";
-export { type Base64, setClient, getVariable, setVariable, getResource, setResource, getResumeUrls, setState, setProgress, getProgress, getState, getIdToken, denoS3LightClientSettings, loadS3FileStream, loadS3File, writeS3File, deleteS3File, signS3Objects, signS3Object, getPresignedS3PublicUrls, getPresignedS3PublicUrl, task, taskScript, taskFlow, workflow, step, sleep, parallel, waitForApproval, type TaskOptions, WorkflowCtx, _workflowCtx, setWorkflowCtx, StepSuspend, runScript, runScriptAsync, runScriptByPath, runScriptByHash, runScriptByPathAsync, runScriptByHashAsync, runFlow, runFlowAsync, waitJob, getRootJobId, setFlowUserState, getFlowUserState, usernameToEmail, requestInteractiveSlackApproval, type Sql, requestInteractiveTeamsApproval, appendToResultStream, streamResult, datatable, ducklake, upsertPartition, appendPartition, type DucklakeMaterializeOptions, type SqlStatement, type DatatableSqlTemplateFunction, type SqlTemplateFunction, type S3Object, type S3ObjectRecord, type S3ObjectURI, commitKafkaOffsets } from "./client";
-import { setClient, getVariable, setVariable, getResource, setResource, getResumeUrls, setState, setProgress, getProgress, getState, getIdToken, denoS3LightClientSettings, loadS3FileStream, loadS3File, writeS3File, deleteS3File, signS3Objects, signS3Object, getPresignedS3PublicUrls, getPresignedS3PublicUrl, task, taskScript, taskFlow, workflow, step, sleep, parallel, waitForApproval, WorkflowCtx, setWorkflowCtx, StepSuspend, runScript, runScriptAsync, runScriptByPath, runScriptByHash, runScriptByPathAsync, runScriptByHashAsync, runFlow, runFlowAsync, waitJob, getRootJobId, setFlowUserState, getFlowUserState, usernameToEmail, requestInteractiveSlackApproval, requestInteractiveTeamsApproval, appendToResultStream, streamResult, datatable, ducklake, upsertPartition, appendPartition, getWorkspace, getStatePath, getInternalState, setInternalState, getResumeEndpoints, getResult, getResultMaybe, resolveDefaultResource, databaseUrlFromResource, base64ToUint8Array, uint8ArrayToBase64, parseS3Object, commitKafkaOffsets } from "./client";
+export { type Base64, setClient, getVariable, setVariable, getResource, setResource, getResumeUrls, setState, setProgress, getProgress, getState, getIdToken, denoS3LightClientSettings, loadS3FileStream, loadS3File, writeS3File, deleteS3File, signS3Objects, signS3Object, getPresignedS3PublicUrls, getPresignedS3PublicUrl, task, taskScript, taskFlow, workflow, step, sleep, parallel, waitForApproval, getApprovalUrls, type TaskOptions, WorkflowCtx, _workflowCtx, setWorkflowCtx, StepSuspend, runScript, runScriptAsync, runScriptByPath, runScriptByHash, runScriptByPathAsync, runScriptByHashAsync, runFlow, runFlowAsync, waitJob, getRootJobId, setFlowUserState, getFlowUserState, usernameToEmail, requestInteractiveSlackApproval, type Sql, requestInteractiveTeamsApproval, appendToResultStream, streamResult, datatable, ducklake, upsertPartition, appendPartition, type DucklakeMaterializeOptions, type SqlStatement, type DatatableSqlTemplateFunction, type SqlTemplateFunction, type S3Object, type S3ObjectRecord, type S3ObjectURI, commitKafkaOffsets } from "./client";
+import { setClient, getVariable, setVariable, getResource, setResource, getResumeUrls, setState, setProgress, getProgress, getState, getIdToken, denoS3LightClientSettings, loadS3FileStream, loadS3File, writeS3File, deleteS3File, signS3Objects, signS3Object, getPresignedS3PublicUrls, getPresignedS3PublicUrl, task, taskScript, taskFlow, workflow, step, sleep, parallel, waitForApproval, getApprovalUrls, WorkflowCtx, setWorkflowCtx, StepSuspend, runScript, runScriptAsync, runScriptByPath, runScriptByHash, runScriptByPathAsync, runScriptByHashAsync, runFlow, runFlowAsync, waitJob, getRootJobId, setFlowUserState, getFlowUserState, usernameToEmail, requestInteractiveSlackApproval, requestInteractiveTeamsApproval, appendToResultStream, streamResult, datatable, ducklake, upsertPartition, appendPartition, getWorkspace, getStatePath, getInternalState, setInternalState, getResumeEndpoints, getResult, getResultMaybe, resolveDefaultResource, databaseUrlFromResource, base64ToUint8Array, uint8ArrayToBase64, parseS3Object, commitKafkaOffsets } from "./client";
 import { AdminService, AuditService, FlowService, GranularAclService, GroupService, JobService, ResourceService, VariableService, ScriptService, ScheduleService, SettingsService, UserService, WorkspaceService, TeamsService } from "./services.gen";
 declare const wmill: {
     setClient: typeof setClient;
@@ -36,6 +36,7 @@ declare const wmill: {
     sleep: typeof sleep;
     parallel: typeof parallel;
     waitForApproval: typeof waitForApproval;
+    getApprovalUrls: typeof getApprovalUrls;
     WorkflowCtx: typeof WorkflowCtx;
     _workflowCtx: WorkflowCtx | null;
     setWorkflowCtx: typeof setWorkflowCtx;