@upstash/workflow 0.2.13 → 0.2.15

package/index.d.mts

@@ -1,6 +1,6 @@
-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, c as Step } from './types-C1WIgVLA.mjs';
-export { A as AsyncStepFunction, C as CallResponse, r as CallSettings, D as Duration, l as FailureFunctionPayload, F as FinishCondition, H as HeaderParams, t as InvokableWorkflow, s as InvokeStepResponse, I as InvokeWorkflowRequest, L as LazyInvokeStepParams, u as LogLevel, p as NotifyStepResponse, P as ParallelCallState, k as PublicServeOptions, m as RequiredExceptFields, j as StepFunction, h as StepTypes, i as SyncStepFunction, q as WaitEventOptions, n as WaitRequest, o as WaitStepResponse, f as WorkflowClient, e as WorkflowContext, w as WorkflowLogger, v as WorkflowLoggerOptions, g as WorkflowReceiver, d as WorkflowTool } from './types-C1WIgVLA.mjs';
-import { HTTPMethods, State, FlowControl, PublishRequest, Client as Client$1, QstashError } from '@upstash/qstash';
+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 { FlowControl, PublishRequest, HTTPMethods, State, Client as Client$1 } from '@upstash/qstash';
 import 'zod';
 import 'ai';
 import '@ai-sdk/openai';
@@ -60,6 +60,10 @@ type BaseStepLog = {
      * will be undefined for an unfinished parallel step.
      */
     out: unknown;
+    /**
+     * number of retries for the step
+     */
+    retries: number;
     /**
      * number of parallel steps
      *
@@ -184,6 +188,19 @@ type StepLogGroup = {
     steps: {
         messageId: string;
         state: "STEP_PROGRESS" | "STEP_RETRY" | "STEP_FAILED" | "STEP_CANCELED";
+        /**
+         * retries
+         */
+        retries: number;
+        /**
+         * errors which occured in the step
+         */
+        errors?: {
+            error: string;
+            headers: Record<string, string[]>;
+            status: number;
+            time: number;
+        }[];
     }[];
     /**
      * Log which belongs to the next step
@@ -215,6 +232,9 @@ type FailureFunctionLog = {
      * Response body of the step which caused the workflow to fail
      */
     failResponse: string;
+    /**
+     * @deprecated use dlqId field of the workflow run itself
+     */
     dlqId: string;
 };
 type WorkflowRunLog = {
@@ -281,11 +301,223 @@ type WorkflowRunLog = {
          */
         workflowRunCreatedAt: number;
     };
+    /**
+     * If the workflow run has failed, id of the run in DLQ
+     */
+    dlqId?: string;
 };
 type WorkflowRunLogs = {
     cursor: string;
     runs: WorkflowRunLog[];
 };
+type TriggerOptions = {
+    /**
+     * URL of the workflow to trigger
+     */
+    url: string;
+    /**
+     * Body to send to the workflow
+     */
+    body?: unknown;
+    /**
+     * Headers to send to the workflow
+     */
+    headers?: Record<string, string>;
+    /**
+     * Workflow run id to use for the workflow run.
+     * If not provided, a random workflow run id will be generated.
+     */
+    workflowRunId?: string;
+    /**
+     * Number of retries to perform if the request fails.
+     *
+     * @default 3
+     */
+    retries?: number;
+    /**
+     * Flow control to use for the workflow run.
+     * If not provided, no flow control will be used.
+     */
+    flowControl?: FlowControl;
+    /**
+     * Delay to apply before triggering the workflow.
+     */
+    delay?: PublishRequest["delay"];
+} & ({
+    /**
+     * URL to call if the first request to the workflow endpoint fails
+     */
+    failureUrl?: never;
+    /**
+     * Whether the workflow endpoint has a failure function
+     * defined to be invoked if the first request fails.
+     *
+     * If true, the failureUrl will be ignored.
+     */
+    useFailureFunction?: true;
+} | {
+    /**
+     * URL to call if the first request to the workflow endpoint fails
+     */
+    failureUrl?: string;
+    /**
+     * Whether the workflow endpoint has a failure function
+     * defined to be invoked if the first request fails.
+     *
+     * If true, the failureUrl will be ignored.
+     */
+    useFailureFunction?: never;
+});
+type DLQResumeRestartOptions<TDLQId extends string | string[] = string | string[]> = {
+    dlqId: TDLQId;
+} & Pick<TriggerOptions, "flowControl" | "retries">;
+type DLQResumeRestartResponse = {
+    /**
+     * id of the workflow run created to resume or restart the DLQ message
+     */
+    workflowRunId: string;
+    /**
+     * Time when the new workflow run was created
+     */
+    workflowCreatedAt: string;
+};
+
+type QStashDLQFilterOptions = NonNullable<Required<Parameters<Client$1["dlq"]["listMessages"]>[0]>>["filter"];
+type DLQFilterOptions = Pick<QStashDLQFilterOptions, "fromDate" | "toDate" | "url" | "responseStatus">;
+type DLQMessage = {
+    messageId: string;
+    url: string;
+    method: string;
+    header: Record<string, string[]>;
+    body: string;
+    maxRetries: number;
+    notBefore: number;
+    createdAt: number;
+    callerIP: string;
+    workflowRunId: string;
+    workflowCreatedAt: number;
+    workflowUrl: string;
+    responseStatus: number;
+    responseHeader: Record<string, string[]>;
+    responseBody: string;
+    dlqId: string;
+};
+type PublicDLQMessage = Pick<DLQMessage, "header" | "body" | "maxRetries" | "notBefore" | "createdAt" | "callerIP" | "workflowRunId" | "workflowCreatedAt" | "workflowUrl" | "responseStatus" | "responseHeader" | "responseBody" | "dlqId">;
+declare class DLQ {
+    private client;
+    constructor(client: Client$1);
+    /**
+     * list the items in the DLQ
+     *
+     * @param cursor - Optional cursor for pagination.
+     * @param count - Optional number of items to return.
+     * @param filter - Optional filter options to apply to the DLQ items.
+     *    The available filter options are:
+     *    - `fromDate`: Filter items which entered the DLQ after this date.
+     *    - `toDate`: Filter items which entered the DLQ before this date.
+     *    - `url`: Filter items by the URL they were sent to.
+     *    - `responseStatus`: Filter items by the response status code.
+     * @returns
+     */
+    list(parameters?: {
+        cursor?: string;
+        count?: number;
+        filter?: DLQFilterOptions;
+    }): Promise<{
+        messages: PublicDLQMessage[];
+        cursor?: string;
+    }>;
+    /**
+     * Resumes the workflow run for the given DLQ message(s).
+     *
+     * Resuming means that the new workflow run will start executing from where
+     * the original workflow run failed, using the same input and context.
+     *
+     * If you want to restart the workflow run from the beginning, use
+     * `restart` method instead.
+     *
+     * Example with a single DLQ ID:
+     * ```ts
+     * const response = await client.dlq.resume({
+     *   dlqId: "dlq-12345",
+     *   flowControl: {
+     *     key: "my-flow-control-key",
+     *     value: "my-flow-control-value",
+     *   },
+     *   retries: 3,
+     * });
+     *
+     * console.log(response.workflowRunId); // ID of the new workflow run
+     * ```
+     *
+     * Example with multiple DLQ IDs:
+     * ```ts
+     * const response = await client.dlq.resume({
+     *  dlqId: ["dlq-12345", "dlq-67890"],
+     *  // other parameters...
+     * });
+     * console.log(response[0].workflowRunId); // ID of the first workflow run
+     * console.log(response[1].workflowRunId); // ID of the second workflow run
+     * ```
+     *
+     * if the dlqId is not found, throws an error.
+     *
+     * @param dlqId - The ID(s) of the DLQ message(s) to resume.
+     * @param flowControl - Optional flow control parameters. If not passed, flow
+     *     control of the failing workflow will be used
+     * @param retries - Optional number of retries to perform if the request fails.
+     *     If not passed, retries settings of the failing workflow will be used.
+     * @returns run id and creation time of the new workflow run(s).
+     */
+    resume(parameters: DLQResumeRestartOptions<string>): Promise<DLQResumeRestartResponse>;
+    resume(parameters: DLQResumeRestartOptions<string[]>): Promise<DLQResumeRestartResponse[]>;
+    /**
+     * Restarts the workflow run for the given DLQ message(s).
+     *
+     * Restarting means that the new workflow run will start executing from the
+     * beginning with the same initial payload and configuration.
+     *
+     * If you want to resume the workflow run from where it failed, use
+     * `resume` method instead.
+     *
+     * Example with a single DLQ ID:
+     * ```ts
+     * const response = await client.dlq.restart({
+     *   dlqId: "dlq-12345",
+     *   flowControl: {
+     *     key: "my-flow-control-key",
+     *     value: "my-flow-control-value",
+     *   },
+     *   retries: 3,
+     * });
+     *
+     * console.log(response.workflowRunId); // ID of the new workflow run
+     * ```
+     *
+     * Example with multiple DLQ IDs:
+     * ```ts
+     * const response = await client.dlq.restart({
+     *  dlqId: ["dlq-12345", "dlq-67890"],
+     *  // other parameters...
+     * });
+     * console.log(response[0].workflowRunId); // ID of the first workflow run
+     * console.log(response[1].workflowRunId); // ID of the second workflow run
+     * ```
+     *
+     * if the dlqId is not found, throws an error.
+     *
+     * @param dlqId - The ID(s) of the DLQ message(s) to restart.
+     * @param flowControl - Optional flow control parameters. If not passed, flow
+     *     control of the failing workflow will be used
+     * @param retries - Optional number of retries to perform if the request fails.
+     *     If not passed, retries settings of the failing workflow will be used.
+     * @returns run id and creation time of the new workflow run(s).
+     */
+    restart(parameters: DLQResumeRestartOptions<string>): Promise<DLQResumeRestartResponse>;
+    restart(parameters: DLQResumeRestartOptions<string[]>): Promise<DLQResumeRestartResponse[]>;
+    private static handleDLQOptions;
+    private static getDlqIdQueryParameter;
+}
 
 type ClientConfig = ConstructorParameters<typeof Client$1>[0];
 /**
@@ -398,8 +630,9 @@ declare class Client {
         eventId: string;
     }): Promise<Required<Waiter>[]>;
     /**
-     * Trigger new workflow run and returns the workflow run id
+     * Trigger new workflow run and returns the workflow run id or an array of workflow run ids
      *
+     * trigger a single workflow run:
      * ```ts
      * const { workflowRunId } = await client.trigger({
      *   url: "https://workflow-endpoint.com",
@@ -412,6 +645,31 @@ declare class Client {
      * console.log(workflowRunId)
      * // wfr_my-workflow
      * ```
+     * trigger multiple workflow runs:
+     * ```ts
+     * const result = await client.trigger([
+     *   {
+     *   url: "https://workflow-endpoint.com",
+     *   body: "hello there!",         // Optional body
+     *   headers: { ... },             // Optional headers
+     *   workflowRunId: "my-workflow", // Optional workflow run ID
+     *   retries: 3                    // Optional retries for the initial request
+     * },
+     *   {
+     *   url: "https://workflow-endpoint-2.com",
+     *   body: "hello world!",           // Optional body
+     *   headers: { ... },               // Optional headers
+     *   workflowRunId: "my-workflow-2", // Optional workflow run ID
+     *   retries: 5                      // Optional retries for the initial request
+     * },
+     * ]);
+     *
+     * console.log(result)
+     * // [
+     * //   { workflowRunId: "wfr_my-workflow" },
+     * //   { workflowRunId: "wfr_my-workflow-2" },
+     * // ]
+     * ```
      *
      * @param url URL of the workflow
      * @param body body to start the workflow with
@@ -428,19 +686,14 @@ declare class Client {
      * @param delay Delay for the workflow run. This is used to delay the
      *   execution of the workflow run. The delay is in seconds or can be passed
      *   as a string with a time unit (e.g. "1h", "30m", "15s").
-     * @returns workflow run id
-     */
-    trigger({ url, body, headers, workflowRunId, retries, flowControl, delay, }: {
-        url: string;
-        body?: unknown;
-        headers?: Record<string, string>;
-        workflowRunId?: string;
-        retries?: number;
-        flowControl?: FlowControl;
-        delay?: PublishRequest["delay"];
-    }): Promise<{
+     * @returns workflow run id or an array of workflow run ids
+     */
+    trigger(params: TriggerOptions): Promise<{
         workflowRunId: string;
     }>;
+    trigger(params: TriggerOptions[]): Promise<{
+        workflowRunId: string;
+    }[]>;
     /**
      * Fetches logs for workflow runs.
      *
@@ -476,32 +729,7 @@ declare class Client {
         workflowUrl?: WorkflowRunLog["workflowUrl"];
         workflowCreatedAt?: WorkflowRunLog["workflowRunCreatedAt"];
     }): Promise<WorkflowRunLogs>;
+    get dlq(): DLQ;
 }
 
-/**
- * Error raised during Workflow execution
- */
-declare class WorkflowError extends QstashError {
-    constructor(message: string);
-}
-/**
- * Raised when the workflow executes a function successfully
- * and aborts to end the execution
- */
-declare class WorkflowAbort extends Error {
-    stepInfo?: Step;
-    stepName: string;
-    /**
-     * whether workflow is to be canceled on abort
-     */
-    cancelWorkflow: boolean;
-    /**
-     *
-     * @param stepName name of the aborting step
-     * @param stepInfo step information
-     * @param cancelWorkflow
-     */
-    constructor(stepName: string, stepInfo?: Step, cancelWorkflow?: boolean);
-}
-
-export { Client, ExclusiveValidationOptions, NotifyResponse, RawStep, RouteFunction, Step, type StepLog, StepType, Telemetry, Waiter, WorkflowAbort, WorkflowError, type WorkflowRunLog, type WorkflowRunLogs, WorkflowServeOptions, serve };
+export { Client, type DLQResumeRestartOptions, type DLQResumeRestartResponse, ExclusiveValidationOptions, NotifyResponse, RawStep, RouteFunction, type StepLog, StepType, Telemetry, type TriggerOptions, Waiter, type WorkflowRunLog, type WorkflowRunLogs, WorkflowServeOptions, serve };