windmill-client 1.618.2 → 1.618.3

package/dist/client.d.ts

@@ -0,0 +1,414 @@
+import { DenoS3LightClientSettings, S3ObjectRecord, type S3Object } from "./s3Types";
+export { type S3Object, type S3ObjectRecord, type S3ObjectURI, } from "./s3Types";
+export { datatable, ducklake, type SqlTemplateFunction, type DatatableSqlTemplateFunction, } from "./sqlUtils";
+export { AdminService, AuditService, FlowService, GranularAclService, GroupService, JobService, ResourceService, VariableService, ScriptService, ScheduleService, SettingsService, UserService, WorkspaceService, TeamsService, } from "./index";
+export type Sql = string;
+export type Email = string;
+export type Base64 = string;
+export type Resource<S extends string> = any;
+export declare const SHARED_FOLDER = "/shared";
+/**
+ * Initialize the Windmill client with authentication token and base URL
+ * @param token - Authentication token (defaults to WM_TOKEN env variable)
+ * @param baseUrl - API base URL (defaults to BASE_INTERNAL_URL or BASE_URL env variable)
+ */
+export declare function setClient(token?: string, baseUrl?: string): void;
+/**
+ * Create a client configuration from env variables
+ * @returns client configuration
+ */
+export declare function getWorkspace(): string;
+/**
+ * Get a resource value by path
+ * @param path path of the resource,  default to internal state path
+ * @param undefinedIfEmpty if the resource does not exist, return undefined instead of throwing an error
+ * @returns resource value
+ */
+export declare function getResource(path?: string, undefinedIfEmpty?: boolean): Promise<any>;
+/**
+ * Get the true root job id
+ * @param jobId job id to get the root job id from (default to current job)
+ * @returns root job id
+ */
+export declare function getRootJobId(jobId?: string): Promise<string>;
+/**
+ * @deprecated Use runScriptByPath or runScriptByHash instead
+ */
+export declare function runScript(path?: string | null, hash_?: string | null, args?: Record<string, any> | null, verbose?: boolean): Promise<any>;
+/**
+ * Run a script synchronously by its path and wait for the result
+ * @param path - Script path in Windmill
+ * @param args - Arguments to pass to the script
+ * @param verbose - Enable verbose logging
+ * @returns Script execution result
+ */
+export declare function runScriptByPath(path: string, args?: Record<string, any> | null, verbose?: boolean): Promise<any>;
+/**
+ * Run a script synchronously by its hash and wait for the result
+ * @param hash_ - Script hash in Windmill
+ * @param args - Arguments to pass to the script
+ * @param verbose - Enable verbose logging
+ * @returns Script execution result
+ */
+export declare function runScriptByHash(hash_: string, args?: Record<string, any> | null, verbose?: boolean): Promise<any>;
+/**
+ * Append a text to the result stream
+ * @param text text to append to the result stream
+ */
+export declare function appendToResultStream(text: string): void;
+/**
+ * Stream to the result stream
+ * @param stream stream to stream to the result stream
+ */
+export declare function streamResult(stream: AsyncIterable<string>): Promise<void>;
+/**
+ * Run a flow synchronously by its path and wait for the result
+ * @param path - Flow path in Windmill
+ * @param args - Arguments to pass to the flow
+ * @param verbose - Enable verbose logging
+ * @returns Flow execution result
+ */
+export declare function runFlow(path?: string | null, args?: Record<string, any> | null, verbose?: boolean): Promise<any>;
+/**
+ * Wait for a job to complete and return its result
+ * @param jobId - ID of the job to wait for
+ * @param verbose - Enable verbose logging
+ * @returns Job result when completed
+ */
+export declare function waitJob(jobId: string, verbose?: boolean): Promise<any>;
+/**
+ * Get the result of a completed job
+ * @param jobId - ID of the completed job
+ * @returns Job result
+ */
+export declare function getResult(jobId: string): Promise<any>;
+/**
+ * Get the result of a job if completed, or its current status
+ * @param jobId - ID of the job
+ * @returns Object with started, completed, success, and result properties
+ */
+export declare function getResultMaybe(jobId: string): Promise<any>;
+/**
+ * Wrap a function to execute as a Windmill task within a flow context
+ * @param f - Function to wrap as a task
+ * @returns Async wrapper function that executes as a Windmill job
+ */
+export declare function task<P, T>(f: (_: P) => T): (_: P) => Promise<T>;
+/**
+ * @deprecated Use runScriptByPathAsync or runScriptByHashAsync instead
+ */
+export declare function runScriptAsync(path: string | null, hash_: string | null, args: Record<string, any> | null, scheduledInSeconds?: number | null): Promise<string>;
+/**
+ * Run a script asynchronously by its path
+ * @param path - Script path in Windmill
+ * @param args - Arguments to pass to the script
+ * @param scheduledInSeconds - Schedule execution for a future time (in seconds)
+ * @returns Job ID of the created job
+ */
+export declare function runScriptByPathAsync(path: string, args?: Record<string, any> | null, scheduledInSeconds?: number | null): Promise<string>;
+/**
+ * Run a script asynchronously by its hash
+ * @param hash_ - Script hash in Windmill
+ * @param args - Arguments to pass to the script
+ * @param scheduledInSeconds - Schedule execution for a future time (in seconds)
+ * @returns Job ID of the created job
+ */
+export declare function runScriptByHashAsync(hash_: string, args?: Record<string, any> | null, scheduledInSeconds?: number | null): Promise<string>;
+/**
+ * Run a flow asynchronously by its path
+ * @param path - Flow path in Windmill
+ * @param args - Arguments to pass to the flow
+ * @param scheduledInSeconds - Schedule execution for a future time (in seconds)
+ * @param doNotTrackInParent - If false, tracks state in parent job (only use when fully awaiting the job)
+ * @returns Job ID of the created job
+ */
+export declare function runFlowAsync(path: string | null, args: Record<string, any> | null, scheduledInSeconds?: number | null, doNotTrackInParent?: boolean): Promise<string>;
+/**
+ * Resolve a resource value in case the default value was picked because the input payload was undefined
+ * @param obj resource value or path of the resource under the format `$res:path`
+ * @returns resource value
+ */
+export declare function resolveDefaultResource(obj: any): Promise<any>;
+/**
+ * Get the state file path from environment variables
+ * @returns State path string
+ */
+export declare function getStatePath(): string;
+/**
+ * Set a resource value by path
+ * @param path path of the resource to set, default to state path
+ * @param value new value of the resource to set
+ * @param initializeToTypeIfNotExist if the resource does not exist, initialize it with this type
+ */
+export declare function setResource(value: any, path?: string, initializeToTypeIfNotExist?: string): Promise<void>;
+/**
+ * Set the state
+ * @param state state to set
+ * @deprecated use setState instead
+ */
+export declare function setInternalState(state: any): Promise<void>;
+/**
+ * Set the state
+ * @param state state to set
+ * @param path Optional state resource path override. Defaults to `getStatePath()`.
+ */
+export declare function setState(state: any, path?: string): Promise<void>;
+/**
+ * Set the progress
+ * Progress cannot go back and limited to 0% to 99% range
+ * @param percent Progress to set in %
+ * @param jobId? Job to set progress for
+ */
+export declare function setProgress(percent: number, jobId?: any): Promise<void>;
+/**
+ * Get the progress
+ * @param jobId? Job to get progress from
+ * @returns Optional clamped between 0 and 100 progress value
+ */
+export declare function getProgress(jobId?: any): Promise<number | null>;
+/**
+ * Set a flow user state
+ * @param key key of the state
+ * @param value value of the state
+
+ */
+export declare function setFlowUserState(key: string, value: any, errorIfNotPossible?: boolean): Promise<void>;
+/**
+ * Get a flow user state
+ * @param path path of the variable
+
+ */
+export declare function getFlowUserState(key: string, errorIfNotPossible?: boolean): Promise<any>;
+/**
+ * Get the internal state
+ * @deprecated use getState instead
+ */
+export declare function getInternalState(): Promise<any>;
+/**
+ * Get the state shared across executions
+ * @param path Optional state resource path override. Defaults to `getStatePath()`.
+ */
+export declare function getState(path?: string): Promise<any>;
+/**
+ * Get a variable by path
+ * @param path path of the variable
+ * @returns variable value
+ */
+export declare function getVariable(path: string): Promise<string>;
+/**
+ * Set a variable by path, create if not exist
+ * @param path path of the variable
+ * @param value value of the variable
+ * @param isSecretIfNotExist if the variable does not exist, create it as secret or not (default: false)
+ * @param descriptionIfNotExist if the variable does not exist, create it with this description (default: "")
+ */
+export declare function setVariable(path: string, value: string, isSecretIfNotExist?: boolean, descriptionIfNotExist?: string): Promise<void>;
+/**
+ * Build a PostgreSQL connection URL from a database resource
+ * @param path - Path to the database resource
+ * @returns PostgreSQL connection URL string
+ */
+export declare function databaseUrlFromResource(path: string): Promise<string>;
+/**
+ * Get S3 client settings from a resource or workspace default
+ * @param s3_resource_path - Path to S3 resource (uses workspace default if undefined)
+ * @returns S3 client configuration settings
+ */
+export declare function denoS3LightClientSettings(s3_resource_path: string | undefined): Promise<DenoS3LightClientSettings>;
+/**
+ * Load the content of a file stored in S3. If the s3ResourcePath is undefined, it will default to the workspace S3 resource.
+ *
+ * ```typescript
+ * let fileContent = await wmill.loadS3FileContent(inputFile)
+ * // if the file is a raw text file, it can be decoded and printed directly:
+ * const text = new TextDecoder().decode(fileContentStream)
+ * console.log(text);
+ * ```
+ */
+export declare function loadS3File(s3object: S3Object, s3ResourcePath?: string | undefined): Promise<Uint8Array | undefined>;
+/**
+ * Load the content of a file stored in S3 as a stream. If the s3ResourcePath is undefined, it will default to the workspace S3 resource.
+ *
+ * ```typescript
+ * let fileContentBlob = await wmill.loadS3FileStream(inputFile)
+ * // if the content is plain text, the blob can be read directly:
+ * console.log(await fileContentBlob.text());
+ * ```
+ */
+export declare function loadS3FileStream(s3object: S3Object, s3ResourcePath?: string | undefined): Promise<Blob | undefined>;
+/**
+ * Persist a file to the S3 bucket. If the s3ResourcePath is undefined, it will default to the workspace S3 resource.
+ *
+ * ```typescript
+ * const s3object = await writeS3File(s3Object, "Hello Windmill!")
+ * const fileContentAsUtf8Str = (await s3object.toArray()).toString('utf-8')
+ * console.log(fileContentAsUtf8Str)
+ * ```
+ */
+export declare function writeS3File(s3object: S3Object | undefined, fileContent: string | Blob, s3ResourcePath?: string | undefined, contentType?: string | undefined, contentDisposition?: string | undefined): Promise<S3Object>;
+/**
+ * Sign S3 objects to be used by anonymous users in public apps
+ * @param s3objects s3 objects to sign
+ * @returns signed s3 objects
+ */
+export declare function signS3Objects(s3objects: S3Object[]): Promise<S3Object[]>;
+/**
+ * Sign S3 object to be used by anonymous users in public apps
+ * @param s3object s3 object to sign
+ * @returns signed s3 object
+ */
+export declare function signS3Object(s3object: S3Object): Promise<S3Object>;
+/**
+ * Generate a presigned public URL for an array of S3 objects.
+ * If an S3 object is not signed yet, it will be signed first.
+ * @param s3Objects s3 objects to sign
+ * @returns list of signed public URLs
+ */
+export declare function getPresignedS3PublicUrls(s3Objects: S3Object[], { baseUrl }?: {
+    baseUrl?: string;
+}): Promise<string[]>;
+/**
+ * Generate a presigned public URL for an S3 object. If the S3 object is not signed yet, it will be signed first.
+ * @param s3Object s3 object to sign
+ * @returns signed public URL
+ */
+export declare function getPresignedS3PublicUrl(s3Objects: S3Object, { baseUrl }?: {
+    baseUrl?: string;
+}): Promise<string>;
+/**
+ * Get URLs needed for resuming a flow after this step
+ * @param approver approver name
+ * @param flowLevel if true, generate resume URLs for the parent flow instead of the specific step.
+ *                  This allows pre-approvals that can be consumed by any later suspend step in the same flow.
+ * @returns approval page UI URL, resume and cancel API URLs for resuming the flow
+ */
+export declare function getResumeUrls(approver?: string, flowLevel?: boolean): Promise<{
+    approvalPage: string;
+    resume: string;
+    cancel: string;
+}>;
+/**
+ * @deprecated use getResumeUrls instead
+ */
+export declare function getResumeEndpoints(approver?: string): Promise<{
+    approvalPage: string;
+    resume: string;
+    cancel: string;
+}>;
+/**
+ * Get an OIDC jwt token for auth to external services (e.g: Vault, AWS) (ee only)
+ * @param audience audience of the token
+ * @param expiresIn Optional number of seconds until the token expires
+ * @returns jwt token
+ */
+export declare function getIdToken(audience: string, expiresIn?: number): Promise<string>;
+/**
+ * Convert a base64-encoded string to Uint8Array
+ * @param data - Base64-encoded string
+ * @returns Decoded Uint8Array
+ */
+export declare function base64ToUint8Array(data: string): Uint8Array;
+/**
+ * Convert a Uint8Array to base64-encoded string
+ * @param arrayBuffer - Uint8Array to encode
+ * @returns Base64-encoded string
+ */
+export declare function uint8ArrayToBase64(arrayBuffer: Uint8Array): string;
+/**
+ * Get email from workspace username
+ * This method is particularly useful for apps that require the email address of the viewer.
+ * Indeed, in the viewer context, WM_USERNAME is set to the username of the viewer but WM_EMAIL is set to the email of the creator of the app.
+ * @param username
+ * @returns email address
+ */
+export declare function usernameToEmail(username: string): Promise<string>;
+interface SlackApprovalOptions {
+    slackResourcePath: string;
+    channelId: string;
+    message?: string;
+    approver?: string;
+    defaultArgsJson?: Record<string, any>;
+    dynamicEnumsJson?: Record<string, any>;
+}
+interface TeamsApprovalOptions {
+    teamName: string;
+    channelName: string;
+    message?: string;
+    approver?: string;
+    defaultArgsJson?: Record<string, any>;
+    dynamicEnumsJson?: Record<string, any>;
+}
+/**
+ * Sends an interactive approval request via Slack, allowing optional customization of the message, approver, and form fields.
+ *
+ * **[Enterprise Edition Only]** To include form fields in the Slack approval request, go to **Advanced -> Suspend -> Form**
+ * and define a form. Learn more at [Windmill Documentation](https://www.windmill.dev/docs/flows/flow_approval#form).
+ *
+ * @param {Object} options - The configuration options for the Slack approval request.
+ * @param {string} options.slackResourcePath - The path to the Slack resource in Windmill.
+ * @param {string} options.channelId - The Slack channel ID where the approval request will be sent.
+ * @param {string} [options.message] - Optional custom message to include in the Slack approval request.
+ * @param {string} [options.approver] - Optional user ID or name of the approver for the request.
+ * @param {DefaultArgs} [options.defaultArgsJson] - Optional object defining or overriding the default arguments to a form field.
+ * @param {Enums} [options.dynamicEnumsJson] - Optional object overriding the enum default values of an enum form field.
+ *
+ * @returns {Promise<void>} Resolves when the Slack approval request is successfully sent.
+ *
+ * @throws {Error} If the function is not called within a flow or flow preview.
+ * @throws {Error} If the `JobService.getSlackApprovalPayload` call fails.
+ *
+ * **Usage Example:**
+ * ```typescript
+ * await requestInteractiveSlackApproval({
+ *   slackResourcePath: "/u/alex/my_slack_resource",
+ *   channelId: "admins-slack-channel",
+ *   message: "Please approve this request",
+ *   approver: "approver123",
+ *   defaultArgsJson: { key1: "value1", key2: 42 },
+ *   dynamicEnumsJson: { foo: ["choice1", "choice2"], bar: ["optionA", "optionB"] },
+ * });
+ * ```
+ *
+ * **Note:** This function requires execution within a Windmill flow or flow preview.
+ */
+export declare function requestInteractiveSlackApproval({ slackResourcePath, channelId, message, approver, defaultArgsJson, dynamicEnumsJson, }: SlackApprovalOptions): Promise<void>;
+/**
+ * Sends an interactive approval request via Teams, allowing optional customization of the message, approver, and form fields.
+ *
+ * **[Enterprise Edition Only]** To include form fields in the Teams approval request, go to **Advanced -> Suspend -> Form**
+ * and define a form. Learn more at [Windmill Documentation](https://www.windmill.dev/docs/flows/flow_approval#form).
+ *
+ * @param {Object} options - The configuration options for the Teams approval request.
+ * @param {string} options.teamName - The Teams team name where the approval request will be sent.
+ * @param {string} options.channelName - The Teams channel name where the approval request will be sent.
+ * @param {string} [options.message] - Optional custom message to include in the Teams approval request.
+ * @param {string} [options.approver] - Optional user ID or name of the approver for the request.
+ * @param {DefaultArgs} [options.defaultArgsJson] - Optional object defining or overriding the default arguments to a form field.
+ * @param {Enums} [options.dynamicEnumsJson] - Optional object overriding the enum default values of an enum form field.
+ *
+ * @returns {Promise<void>} Resolves when the Teams approval request is successfully sent.
+ *
+ * @throws {Error} If the function is not called within a flow or flow preview.
+ * @throws {Error} If the `JobService.getTeamsApprovalPayload` call fails.
+ *
+ * **Usage Example:**
+ * ```typescript
+ * await requestInteractiveTeamsApproval({
+ *   teamName: "admins-teams",
+ *   channelName: "admins-teams-channel",
+ *   message: "Please approve this request",
+ *   approver: "approver123",
+ *   defaultArgsJson: { key1: "value1", key2: 42 },
+ *   dynamicEnumsJson: { foo: ["choice1", "choice2"], bar: ["optionA", "optionB"] },
+ * });
+ * ```
+ *
+ * **Note:** This function requires execution within a Windmill flow or flow preview.
+ */
+export declare function requestInteractiveTeamsApproval({ teamName, channelName, message, approver, defaultArgsJson, dynamicEnumsJson, }: TeamsApprovalOptions): Promise<void>;
+/**
+ * Parse an S3 object from URI string or record format
+ * @param s3Object - S3 object as URI string (s3://storage/key) or record
+ * @returns S3 object record with storage and s3 key
+ */
+export declare function parseS3Object(s3Object: S3Object): S3ObjectRecord;

package/dist/core/ApiError.d.ts

@@ -0,0 +1,10 @@
+import type { ApiRequestOptions } from './ApiRequestOptions';
+import type { ApiResult } from './ApiResult';
+export declare class ApiError extends Error {
+    readonly url: string;
+    readonly status: number;
+    readonly statusText: string;
+    readonly body: unknown;
+    readonly request: ApiRequestOptions;
+    constructor(request: ApiRequestOptions, response: ApiResult, message: string);
+}

package/dist/core/ApiRequestOptions.d.ts

@@ -0,0 +1,13 @@
+export type ApiRequestOptions = {
+    readonly method: 'GET' | 'PUT' | 'POST' | 'DELETE' | 'OPTIONS' | 'HEAD' | 'PATCH';
+    readonly url: string;
+    readonly path?: Record<string, unknown>;
+    readonly cookies?: Record<string, unknown>;
+    readonly headers?: Record<string, unknown>;
+    readonly query?: Record<string, unknown>;
+    readonly formData?: Record<string, unknown>;
+    readonly body?: any;
+    readonly mediaType?: string;
+    readonly responseHeader?: string;
+    readonly errors?: Record<number, string>;
+};

package/dist/core/ApiResult.d.ts

@@ -0,0 +1,7 @@
+export type ApiResult<TData = any> = {
+    readonly body: TData;
+    readonly ok: boolean;
+    readonly status: number;
+    readonly statusText: string;
+    readonly url: string;
+};

package/dist/core/CancelablePromise.d.ts

@@ -0,0 +1,26 @@
+export declare class CancelError extends Error {
+    constructor(message: string);
+    get isCancelled(): boolean;
+}
+export interface OnCancel {
+    readonly isResolved: boolean;
+    readonly isRejected: boolean;
+    readonly isCancelled: boolean;
+    (cancelHandler: () => void): void;
+}
+export declare class CancelablePromise<T> implements Promise<T> {
+    private _isResolved;
+    private _isRejected;
+    private _isCancelled;
+    readonly cancelHandlers: (() => void)[];
+    readonly promise: Promise<T>;
+    private _resolve?;
+    private _reject?;
+    constructor(executor: (resolve: (value: T | PromiseLike<T>) => void, reject: (reason?: unknown) => void, onCancel: OnCancel) => void);
+    get [Symbol.toStringTag](): string;
+    then<TResult1 = T, TResult2 = never>(onFulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null, onRejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+    catch<TResult = never>(onRejected?: ((reason: unknown) => TResult | PromiseLike<TResult>) | null): Promise<T | TResult>;
+    finally(onFinally?: (() => void) | null): Promise<T>;
+    cancel(): void;
+    get isCancelled(): boolean;
+}

package/dist/core/OpenAPI.d.ts

@@ -0,0 +1,27 @@
+import type { ApiRequestOptions } from './ApiRequestOptions';
+type Headers = Record<string, string>;
+type Middleware<T> = (value: T) => T | Promise<T>;
+type Resolver<T> = (options: ApiRequestOptions) => Promise<T>;
+export declare class Interceptors<T> {
+    _fns: Middleware<T>[];
+    constructor();
+    eject(fn: Middleware<T>): void;
+    use(fn: Middleware<T>): void;
+}
+export type OpenAPIConfig = {
+    BASE: string;
+    CREDENTIALS: 'include' | 'omit' | 'same-origin';
+    ENCODE_PATH?: ((path: string) => string) | undefined;
+    HEADERS?: Headers | Resolver<Headers> | undefined;
+    PASSWORD?: string | Resolver<string> | undefined;
+    TOKEN?: string | Resolver<string> | undefined;
+    USERNAME?: string | Resolver<string> | undefined;
+    VERSION: string;
+    WITH_CREDENTIALS: boolean;
+    interceptors: {
+        request: Interceptors<RequestInit>;
+        response: Interceptors<Response>;
+    };
+};
+export declare const OpenAPI: OpenAPIConfig;
+export {};

package/dist/core/request.d.ts

@@ -0,0 +1,29 @@
+import type { ApiRequestOptions } from './ApiRequestOptions';
+import type { ApiResult } from './ApiResult';
+import { CancelablePromise } from './CancelablePromise';
+import type { OnCancel } from './CancelablePromise';
+import type { OpenAPIConfig } from './OpenAPI';
+export declare const isString: (value: unknown) => value is string;
+export declare const isStringWithValue: (value: unknown) => value is string;
+export declare const isBlob: (value: any) => value is Blob;
+export declare const isFormData: (value: unknown) => value is FormData;
+export declare const base64: (str: string) => string;
+export declare const getQueryString: (params: Record<string, unknown>) => string;
+export declare const getFormData: (options: ApiRequestOptions) => FormData | undefined;
+type Resolver<T> = (options: ApiRequestOptions) => Promise<T>;
+export declare const resolve: <T>(options: ApiRequestOptions, resolver?: T | Resolver<T>) => Promise<T | undefined>;
+export declare const getHeaders: (config: OpenAPIConfig, options: ApiRequestOptions) => Promise<Headers>;
+export declare const getRequestBody: (options: ApiRequestOptions) => unknown;
+export declare const sendRequest: (config: OpenAPIConfig, options: ApiRequestOptions, url: string, body: any, formData: FormData | undefined, headers: Headers, onCancel: OnCancel) => Promise<Response>;
+export declare const getResponseHeader: (response: Response, responseHeader?: string) => string | undefined;
+export declare const getResponseBody: (response: Response) => Promise<unknown>;
+export declare const catchErrorCodes: (options: ApiRequestOptions, result: ApiResult) => void;
+/**
+ * Request method
+ * @param config The OpenAPI configuration object
+ * @param options The request options from the service
+ * @returns CancelablePromise<T>
+ * @throws ApiError
+ */
+export declare const request: <T>(config: OpenAPIConfig, options: ApiRequestOptions) => CancelablePromise<T>;
+export {};