@upstash/workflow 0.2.16 → 0.2.18

package/index.d.mts

@@ -1,5 +1,5 @@
-import { R as RouteFunction, W as WorkflowServeOptions, E as ExclusiveValidationOptions, T as Telemetry, S as StepType, a as RawStep, N as NotifyResponse, b as Waiter } from './types-Dd-3bPoU.mjs';
-export { A as AsyncStepFunction, C as CallResponse, u as CallSettings, D as Duration, o as FailureFunctionPayload, F as FinishCondition, H as HeaderParams, w as InvokableWorkflow, v as InvokeStepResponse, I as InvokeWorkflowRequest, L as LazyInvokeStepParams, x as LogLevel, s as NotifyStepResponse, P as ParallelCallState, n as PublicServeOptions, p as RequiredExceptFields, k as Step, m as StepFunction, j as StepTypes, l as SyncStepFunction, t as WaitEventOptions, q as WaitRequest, r as WaitStepResponse, d as WorkflowAbort, h as WorkflowClient, g as WorkflowContext, c as WorkflowError, z as WorkflowLogger, y as WorkflowLoggerOptions, e as WorkflowNonRetryableError, i as WorkflowReceiver, f as WorkflowTool } from './types-Dd-3bPoU.mjs';
+import { R as RouteFunction, W as WorkflowServeOptions, E as ExclusiveValidationOptions, T as Telemetry, S as StepType, a as RawStep, N as NotifyResponse, b as Waiter } from './types-B7_5AkKQ.mjs';
+export { A as AsyncStepFunction, C as CallResponse, v as CallSettings, D as DetailedFinishCondition, t as Duration, o as FailureFunctionPayload, F as FinishCondition, H as HeaderParams, x as InvokableWorkflow, w as InvokeStepResponse, I as InvokeWorkflowRequest, L as LazyInvokeStepParams, y as LogLevel, s as NotifyStepResponse, P as ParallelCallState, n as PublicServeOptions, p as RequiredExceptFields, k as Step, m as StepFunction, j as StepTypes, l as SyncStepFunction, u as WaitEventOptions, q as WaitRequest, r as WaitStepResponse, d as WorkflowAbort, h as WorkflowClient, g as WorkflowContext, c as WorkflowError, B as WorkflowLogger, z as WorkflowLoggerOptions, e as WorkflowNonRetryableError, i as WorkflowReceiver, f as WorkflowTool } from './types-B7_5AkKQ.mjs';
 import { FlowControl, PublishRequest, HTTPMethods, State, Client as Client$1 } from '@upstash/qstash';
 import 'zod';
 import 'ai';
@@ -64,6 +64,10 @@ type BaseStepLog = {
      * number of retries for the step
      */
     retries: number;
+    /**
+     * retry delay parameter for the step if it was set
+     */
+    retryDelay?: string;
     /**
      * number of parallel steps
      *
@@ -163,6 +167,25 @@ type StepLog = BaseStepLog & AsOptional<CallUrlGroup> & AsOptional<CallResponseS
 }> & AsOptional<{
     sleepUntil: number;
 }> & AsOptional<WaitEventGroup>;
+type StepError = {
+    /**
+     * error message associated with the request
+     *
+     * example:
+     * ```
+     * detected a non-workflow destination for trigger/invoke.
+     * make sure you are sending the request to the correct endpoint
+     * ```
+     */
+    error: string;
+    /**
+     * response body returned in the request which resulted in an error
+     */
+    body: string;
+    headers: Record<string, string[]>;
+    status: number;
+    time: number;
+};
 type StepLogGroup = {
     /**
      * Log which belongs to a single step
@@ -192,15 +215,14 @@ type StepLogGroup = {
          * retries
          */
         retries: number;
+        /**
+         * retry delay parameter for the step if it was set
+         */
+        retryDelay?: string;
         /**
          * errors which occured in the step
          */
-        errors?: {
-            error: string;
-            headers: Record<string, string[]>;
-            status: number;
-            time: number;
-        }[];
+        errors?: StepError[];
     }[];
     /**
      * Log which belongs to the next step
@@ -236,6 +258,22 @@ type FailureFunctionLog = {
      * @deprecated use dlqId field of the workflow run itself
      */
     dlqId: string;
+    /**
+     * Errors received while running failure function
+     */
+    errors?: StepError[];
+    /**
+     * String body returned from the failure function
+     */
+    responseBody?: string;
+    /**
+     * Headers received from the failure function
+     */
+    responseHeaders?: Record<string, string[]>;
+    /**
+     * Status code of the response from the failure function
+     */
+    responseStatus?: number;
 };
 type WorkflowRunLog = {
     /**
@@ -305,6 +343,10 @@ type WorkflowRunLog = {
      * If the workflow run has failed, id of the run in DLQ
      */
     dlqId?: string;
+    /**
+     * Label of the workflow run
+     */
+    label?: string;
 };
 type WorkflowRunLogs = {
     cursor: string;
@@ -334,6 +376,37 @@ type TriggerOptions = {
      * @default 3
      */
     retries?: number;
+    /**
+     * Delay between retries.
+     *
+     * By default, the `retryDelay` is exponential backoff.
+     * More details can be found in: https://upstash.com/docs/qstash/features/retry.
+     *
+     * The `retryDelay` option allows you to customize the delay (in milliseconds) between retry attempts when message delivery fails.
+     *
+     * You can use mathematical expressions and the following built-in functions to calculate the delay dynamically.
+     * The special variable `retried` represents the current retry attempt count (starting from 0).
+     *
+     * Supported functions:
+     * - `pow`
+     * - `sqrt`
+     * - `abs`
+     * - `exp`
+     * - `floor`
+     * - `ceil`
+     * - `round`
+     * - `min`
+     * - `max`
+     *
+     * Examples of valid `retryDelay` values:
+     * ```ts
+     * 1000 // 1 second
+     * 1000 * (1 + retried)  // 1 second multiplied by the current retry attempt
+     * pow(2, retried) // 2 to the power of the current retry attempt
+     * max(10, pow(2, retried)) // The greater of 10 or 2^retried
+     * ```
+     */
+    retryDelay?: string;
     /**
      * Flow control to use for the workflow run.
      * If not provided, no flow control will be used.
@@ -343,6 +416,12 @@ type TriggerOptions = {
      * Delay to apply before triggering the workflow.
      */
     delay?: PublishRequest["delay"];
+    /**
+     * Label to apply to the workflow run.
+     *
+     * Can be used to filter the workflow run logs.
+     */
+    label?: string;
 } & ({
     /**
      * URL to call if the first request to the workflow endpoint fails
@@ -383,9 +462,23 @@ type DLQResumeRestartResponse = {
 };
 
 type QStashDLQFilterOptions = NonNullable<Required<Parameters<Client$1["dlq"]["listMessages"]>[0]>>["filter"];
-type DLQFilterOptions = Pick<QStashDLQFilterOptions, "fromDate" | "toDate" | "url" | "responseStatus">;
+type DLQFilterOptions = Pick<QStashDLQFilterOptions, "fromDate" | "toDate" | "url" | "responseStatus"> & {
+    workflowRunId?: string;
+    workflowCreatedAt?: string;
+    failureFunctionState?: FailureCallbackInfo["state"];
+    label?: string;
+};
+type FailureCallbackInfo = {
+    state?: "CALLBACK_FAIL" | "CALLBACK_SUCCESS" | "CALLBACK_INPROGRESS";
+    responseStatus?: number;
+    responseBody?: string;
+    responseHeaders?: Record<string, string[]>;
+};
 type DLQMessage = {
     messageId: string;
+    /**
+     * URL of the workflow
+     */
     url: string;
     method: string;
     header: Record<string, string[]>;
@@ -401,8 +494,20 @@ type DLQMessage = {
     responseHeader: Record<string, string[]>;
     responseBody: string;
     dlqId: string;
+    /**
+     * URL of the failure callback
+     */
+    failureCallback?: string;
+    /**
+     * status of the failure callback
+     */
+    failureCallbackInfo?: FailureCallbackInfo;
+    /**
+     * label passed when triggering workflow
+     */
+    label?: string;
 };
-type PublicDLQMessage = Pick<DLQMessage, "header" | "body" | "maxRetries" | "notBefore" | "createdAt" | "callerIP" | "workflowRunId" | "workflowCreatedAt" | "workflowUrl" | "responseStatus" | "responseHeader" | "responseBody" | "dlqId">;
+type PublicDLQMessage = Pick<DLQMessage, "header" | "body" | "maxRetries" | "notBefore" | "createdAt" | "callerIP" | "workflowRunId" | "workflowCreatedAt" | "workflowUrl" | "responseStatus" | "responseHeader" | "responseBody" | "dlqId" | "failureCallback" | "failureCallbackInfo" | "label">;
 declare class DLQ {
     private client;
     constructor(client: Client$1);
@@ -515,6 +620,16 @@ declare class DLQ {
      */
     restart(parameters: DLQResumeRestartOptions<string>): Promise<DLQResumeRestartResponse>;
     restart(parameters: DLQResumeRestartOptions<string[]>): Promise<DLQResumeRestartResponse[]>;
+    /**
+     * Retry the failure callback of a workflow run whose failureUrl/failureFunction
+     * request has failed.
+     *
+     * @param dlqId - The ID of the DLQ message to retry.
+     * @returns
+     */
+    retryFailureFunction({ dlqId }: Pick<DLQResumeRestartOptions<string>, "dlqId">): Promise<DLQResumeRestartResponse & {
+        error?: string;
+    }>;
     private static handleDLQOptions;
     private static getDlqIdQueryParameter;
 }
@@ -640,6 +755,7 @@ declare class Client {
      *   headers: { ... },             // Optional headers
      *   workflowRunId: "my-workflow", // Optional workflow run ID
      *   retries: 3                    // Optional retries for the initial request
+     *   retryDelay: "1000"            // Optional retry delay for the delay between retries
      * });
      *
      * console.log(workflowRunId)
@@ -654,6 +770,7 @@ declare class Client {
      *   headers: { ... },             // Optional headers
      *   workflowRunId: "my-workflow", // Optional workflow run ID
      *   retries: 3                    // Optional retries for the initial request
+     *   retryDelay: "1000"            // Optional retry delay for the delay between retries
      * },
      *   {
      *   url: "https://workflow-endpoint-2.com",
@@ -661,6 +778,7 @@ declare class Client {
      *   headers: { ... },               // Optional headers
      *   workflowRunId: "my-workflow-2", // Optional workflow run ID
      *   retries: 5                      // Optional retries for the initial request
+     *   retryDelay: "1000"              // Optional retry delay for the delay between retries
      * },
      * ]);
      *
@@ -681,6 +799,7 @@ declare class Client {
      *   with `wfr_`.
      * @param retries retry to use in the initial request. in the rest of
      *   the workflow, `retries` option of the `serve` will be used.
+     * @param retryDelay delay between retries.
      * @param flowControl Settings for controlling the number of active requests
      *   and number of requests per second with the same key.
      * @param delay Delay for the workflow run. This is used to delay the
@@ -728,8 +847,9 @@ declare class Client {
         state?: WorkflowRunLog["workflowState"];
         workflowUrl?: WorkflowRunLog["workflowUrl"];
         workflowCreatedAt?: WorkflowRunLog["workflowRunCreatedAt"];
+        label?: WorkflowRunLog["label"];
     }): Promise<WorkflowRunLogs>;
     get dlq(): DLQ;
 }
 
-export { Client, type DLQResumeRestartOptions, type DLQResumeRestartResponse, ExclusiveValidationOptions, NotifyResponse, RawStep, RouteFunction, type StepLog, StepType, Telemetry, type TriggerOptions, Waiter, type WorkflowRunLog, type WorkflowRunLogs, WorkflowServeOptions, serve };
+export { Client, type DLQResumeRestartOptions, type DLQResumeRestartResponse, ExclusiveValidationOptions, NotifyResponse, RawStep, RouteFunction, type StepError, type StepLog, StepType, Telemetry, type TriggerOptions, Waiter, type WorkflowRunLog, type WorkflowRunLogs, WorkflowServeOptions, serve };

package/index.d.ts

@@ -1,5 +1,5 @@
-import { R as RouteFunction, W as WorkflowServeOptions, E as ExclusiveValidationOptions, T as Telemetry, S as StepType, a as RawStep, N as NotifyResponse, b as Waiter } from './types-Dd-3bPoU.js';
-export { A as AsyncStepFunction, C as CallResponse, u as CallSettings, D as Duration, o as FailureFunctionPayload, F as FinishCondition, H as HeaderParams, w as InvokableWorkflow, v as InvokeStepResponse, I as InvokeWorkflowRequest, L as LazyInvokeStepParams, x as LogLevel, s as NotifyStepResponse, P as ParallelCallState, n as PublicServeOptions, p as RequiredExceptFields, k as Step, m as StepFunction, j as StepTypes, l as SyncStepFunction, t as WaitEventOptions, q as WaitRequest, r as WaitStepResponse, d as WorkflowAbort, h as WorkflowClient, g as WorkflowContext, c as WorkflowError, z as WorkflowLogger, y as WorkflowLoggerOptions, e as WorkflowNonRetryableError, i as WorkflowReceiver, f as WorkflowTool } from './types-Dd-3bPoU.js';
+import { R as RouteFunction, W as WorkflowServeOptions, E as ExclusiveValidationOptions, T as Telemetry, S as StepType, a as RawStep, N as NotifyResponse, b as Waiter } from './types-B7_5AkKQ.js';
+export { A as AsyncStepFunction, C as CallResponse, v as CallSettings, D as DetailedFinishCondition, t as Duration, o as FailureFunctionPayload, F as FinishCondition, H as HeaderParams, x as InvokableWorkflow, w as InvokeStepResponse, I as InvokeWorkflowRequest, L as LazyInvokeStepParams, y as LogLevel, s as NotifyStepResponse, P as ParallelCallState, n as PublicServeOptions, p as RequiredExceptFields, k as Step, m as StepFunction, j as StepTypes, l as SyncStepFunction, u as WaitEventOptions, q as WaitRequest, r as WaitStepResponse, d as WorkflowAbort, h as WorkflowClient, g as WorkflowContext, c as WorkflowError, B as WorkflowLogger, z as WorkflowLoggerOptions, e as WorkflowNonRetryableError, i as WorkflowReceiver, f as WorkflowTool } from './types-B7_5AkKQ.js';
 import { FlowControl, PublishRequest, HTTPMethods, State, Client as Client$1 } from '@upstash/qstash';
 import 'zod';
 import 'ai';
@@ -64,6 +64,10 @@ type BaseStepLog = {
      * number of retries for the step
      */
     retries: number;
+    /**
+     * retry delay parameter for the step if it was set
+     */
+    retryDelay?: string;
     /**
      * number of parallel steps
      *
@@ -163,6 +167,25 @@ type StepLog = BaseStepLog & AsOptional<CallUrlGroup> & AsOptional<CallResponseS
 }> & AsOptional<{
     sleepUntil: number;
 }> & AsOptional<WaitEventGroup>;
+type StepError = {
+    /**
+     * error message associated with the request
+     *
+     * example:
+     * ```
+     * detected a non-workflow destination for trigger/invoke.
+     * make sure you are sending the request to the correct endpoint
+     * ```
+     */
+    error: string;
+    /**
+     * response body returned in the request which resulted in an error
+     */
+    body: string;
+    headers: Record<string, string[]>;
+    status: number;
+    time: number;
+};
 type StepLogGroup = {
     /**
      * Log which belongs to a single step
@@ -192,15 +215,14 @@ type StepLogGroup = {
          * retries
          */
         retries: number;
+        /**
+         * retry delay parameter for the step if it was set
+         */
+        retryDelay?: string;
         /**
          * errors which occured in the step
          */
-        errors?: {
-            error: string;
-            headers: Record<string, string[]>;
-            status: number;
-            time: number;
-        }[];
+        errors?: StepError[];
     }[];
     /**
      * Log which belongs to the next step
@@ -236,6 +258,22 @@ type FailureFunctionLog = {
      * @deprecated use dlqId field of the workflow run itself
      */
     dlqId: string;
+    /**
+     * Errors received while running failure function
+     */
+    errors?: StepError[];
+    /**
+     * String body returned from the failure function
+     */
+    responseBody?: string;
+    /**
+     * Headers received from the failure function
+     */
+    responseHeaders?: Record<string, string[]>;
+    /**
+     * Status code of the response from the failure function
+     */
+    responseStatus?: number;
 };
 type WorkflowRunLog = {
     /**
@@ -305,6 +343,10 @@ type WorkflowRunLog = {
      * If the workflow run has failed, id of the run in DLQ
      */
     dlqId?: string;
+    /**
+     * Label of the workflow run
+     */
+    label?: string;
 };
 type WorkflowRunLogs = {
     cursor: string;
@@ -334,6 +376,37 @@ type TriggerOptions = {
      * @default 3
      */
     retries?: number;
+    /**
+     * Delay between retries.
+     *
+     * By default, the `retryDelay` is exponential backoff.
+     * More details can be found in: https://upstash.com/docs/qstash/features/retry.
+     *
+     * The `retryDelay` option allows you to customize the delay (in milliseconds) between retry attempts when message delivery fails.
+     *
+     * You can use mathematical expressions and the following built-in functions to calculate the delay dynamically.
+     * The special variable `retried` represents the current retry attempt count (starting from 0).
+     *
+     * Supported functions:
+     * - `pow`
+     * - `sqrt`
+     * - `abs`
+     * - `exp`
+     * - `floor`
+     * - `ceil`
+     * - `round`
+     * - `min`
+     * - `max`
+     *
+     * Examples of valid `retryDelay` values:
+     * ```ts
+     * 1000 // 1 second
+     * 1000 * (1 + retried)  // 1 second multiplied by the current retry attempt
+     * pow(2, retried) // 2 to the power of the current retry attempt
+     * max(10, pow(2, retried)) // The greater of 10 or 2^retried
+     * ```
+     */
+    retryDelay?: string;
     /**
      * Flow control to use for the workflow run.
      * If not provided, no flow control will be used.
@@ -343,6 +416,12 @@ type TriggerOptions = {
      * Delay to apply before triggering the workflow.
      */
     delay?: PublishRequest["delay"];
+    /**
+     * Label to apply to the workflow run.
+     *
+     * Can be used to filter the workflow run logs.
+     */
+    label?: string;
 } & ({
     /**
      * URL to call if the first request to the workflow endpoint fails
@@ -383,9 +462,23 @@ type DLQResumeRestartResponse = {
 };
 
 type QStashDLQFilterOptions = NonNullable<Required<Parameters<Client$1["dlq"]["listMessages"]>[0]>>["filter"];
-type DLQFilterOptions = Pick<QStashDLQFilterOptions, "fromDate" | "toDate" | "url" | "responseStatus">;
+type DLQFilterOptions = Pick<QStashDLQFilterOptions, "fromDate" | "toDate" | "url" | "responseStatus"> & {
+    workflowRunId?: string;
+    workflowCreatedAt?: string;
+    failureFunctionState?: FailureCallbackInfo["state"];
+    label?: string;
+};
+type FailureCallbackInfo = {
+    state?: "CALLBACK_FAIL" | "CALLBACK_SUCCESS" | "CALLBACK_INPROGRESS";
+    responseStatus?: number;
+    responseBody?: string;
+    responseHeaders?: Record<string, string[]>;
+};
 type DLQMessage = {
     messageId: string;
+    /**
+     * URL of the workflow
+     */
     url: string;
     method: string;
     header: Record<string, string[]>;
@@ -401,8 +494,20 @@ type DLQMessage = {
     responseHeader: Record<string, string[]>;
     responseBody: string;
     dlqId: string;
+    /**
+     * URL of the failure callback
+     */
+    failureCallback?: string;
+    /**
+     * status of the failure callback
+     */
+    failureCallbackInfo?: FailureCallbackInfo;
+    /**
+     * label passed when triggering workflow
+     */
+    label?: string;
 };
-type PublicDLQMessage = Pick<DLQMessage, "header" | "body" | "maxRetries" | "notBefore" | "createdAt" | "callerIP" | "workflowRunId" | "workflowCreatedAt" | "workflowUrl" | "responseStatus" | "responseHeader" | "responseBody" | "dlqId">;
+type PublicDLQMessage = Pick<DLQMessage, "header" | "body" | "maxRetries" | "notBefore" | "createdAt" | "callerIP" | "workflowRunId" | "workflowCreatedAt" | "workflowUrl" | "responseStatus" | "responseHeader" | "responseBody" | "dlqId" | "failureCallback" | "failureCallbackInfo" | "label">;
 declare class DLQ {
     private client;
     constructor(client: Client$1);
@@ -515,6 +620,16 @@ declare class DLQ {
      */
     restart(parameters: DLQResumeRestartOptions<string>): Promise<DLQResumeRestartResponse>;
     restart(parameters: DLQResumeRestartOptions<string[]>): Promise<DLQResumeRestartResponse[]>;
+    /**
+     * Retry the failure callback of a workflow run whose failureUrl/failureFunction
+     * request has failed.
+     *
+     * @param dlqId - The ID of the DLQ message to retry.
+     * @returns
+     */
+    retryFailureFunction({ dlqId }: Pick<DLQResumeRestartOptions<string>, "dlqId">): Promise<DLQResumeRestartResponse & {
+        error?: string;
+    }>;
     private static handleDLQOptions;
     private static getDlqIdQueryParameter;
 }
@@ -640,6 +755,7 @@ declare class Client {
      *   headers: { ... },             // Optional headers
      *   workflowRunId: "my-workflow", // Optional workflow run ID
      *   retries: 3                    // Optional retries for the initial request
+     *   retryDelay: "1000"            // Optional retry delay for the delay between retries
      * });
      *
      * console.log(workflowRunId)
@@ -654,6 +770,7 @@ declare class Client {
      *   headers: { ... },             // Optional headers
      *   workflowRunId: "my-workflow", // Optional workflow run ID
      *   retries: 3                    // Optional retries for the initial request
+     *   retryDelay: "1000"            // Optional retry delay for the delay between retries
      * },
      *   {
      *   url: "https://workflow-endpoint-2.com",
@@ -661,6 +778,7 @@ declare class Client {
      *   headers: { ... },               // Optional headers
      *   workflowRunId: "my-workflow-2", // Optional workflow run ID
      *   retries: 5                      // Optional retries for the initial request
+     *   retryDelay: "1000"              // Optional retry delay for the delay between retries
      * },
      * ]);
      *
@@ -681,6 +799,7 @@ declare class Client {
      *   with `wfr_`.
      * @param retries retry to use in the initial request. in the rest of
      *   the workflow, `retries` option of the `serve` will be used.
+     * @param retryDelay delay between retries.
      * @param flowControl Settings for controlling the number of active requests
      *   and number of requests per second with the same key.
      * @param delay Delay for the workflow run. This is used to delay the
@@ -728,8 +847,9 @@ declare class Client {
         state?: WorkflowRunLog["workflowState"];
         workflowUrl?: WorkflowRunLog["workflowUrl"];
         workflowCreatedAt?: WorkflowRunLog["workflowRunCreatedAt"];
+        label?: WorkflowRunLog["label"];
     }): Promise<WorkflowRunLogs>;
     get dlq(): DLQ;
 }
 
-export { Client, type DLQResumeRestartOptions, type DLQResumeRestartResponse, ExclusiveValidationOptions, NotifyResponse, RawStep, RouteFunction, type StepLog, StepType, Telemetry, type TriggerOptions, Waiter, type WorkflowRunLog, type WorkflowRunLogs, WorkflowServeOptions, serve };
+export { Client, type DLQResumeRestartOptions, type DLQResumeRestartResponse, ExclusiveValidationOptions, NotifyResponse, RawStep, RouteFunction, type StepError, type StepLog, StepType, Telemetry, type TriggerOptions, Waiter, type WorkflowRunLog, type WorkflowRunLogs, WorkflowServeOptions, serve };