@trigger.dev/sdk 3.2.2 → 3.3.1

package/dist/commonjs/v3/shared.d.ts

@@ -1,8 +1,8 @@
 import { SerializableJson } from "@trigger.dev/core";
-import { ApiRequestOptions, InitOutput, Queue, QueueOptions, SubtaskUnwrapError, TaskRunContext, TaskRunPromise } from "@trigger.dev/core/v3";
+import { ApiRequestOptions, InitOutput, Queue, QueueOptions, SubtaskUnwrapError, TaskRunContext, TaskRunPromise, TaskFromIdentifier } from "@trigger.dev/core/v3";
 import { PollOptions } from "./runs.js";
-import type { AnyRunHandle, AnyTask, BatchItem, BatchResult, BatchRunHandle, BatchRunHandleFromTypes, InferRunTypes, RetrieveRunResult, RunHandle, RunHandleFromTypes, RunHandleOutput, RunHandlePayload, Task, TaskBatchOutputHandle, TaskIdentifier, TaskOptions, TaskOutput, TaskOutputHandle, TaskPayload, TaskRunOptions, TaskRunResult, TaskSchema, TaskWithSchema, TaskWithSchemaOptions, TaskWithToolOptions, ToolTask, ToolTaskParameters, TriggerApiRequestOptions } from "@trigger.dev/core/v3";
-export type { AnyRunHandle, AnyTask, BatchItem, BatchResult, BatchRunHandle, Queue, RunHandle, RunHandleOutput, RunHandlePayload, SerializableJson, Task, TaskBatchOutputHandle, TaskIdentifier, TaskOptions, TaskOutput, TaskOutputHandle, TaskPayload, TaskRunOptions, TaskRunResult, };
+import type { AnyRunHandle, AnyTask, BatchByIdAndWaitItem, BatchByTaskAndWaitItem, BatchByIdItem, BatchByTaskItem, BatchByTaskResult, BatchByIdResult, BatchItem, BatchResult, BatchRunHandle, BatchRunHandleFromTypes, BatchTasksRunHandleFromTypes, BatchTriggerOptions, InferRunTypes, RetrieveRunResult, RunHandle, RunHandleFromTypes, RunHandleOutput, RunHandlePayload, Task, TaskBatchOutputHandle, TaskIdentifier, TaskOptions, TaskOutput, TaskOutputHandle, TaskPayload, TaskRunResult, TaskSchema, TaskWithSchema, TaskWithSchemaOptions, TaskWithToolOptions, ToolTask, ToolTaskParameters, TriggerAndWaitOptions, TriggerApiRequestOptions, TriggerOptions } from "@trigger.dev/core/v3";
+export type { AnyRunHandle, AnyTask, BatchItem, BatchResult, BatchRunHandle, BatchTriggerOptions, Queue, RunHandle, RunHandleOutput, RunHandlePayload, SerializableJson, Task, TaskBatchOutputHandle, TaskIdentifier, TaskOptions, TaskOutput, TaskOutputHandle, TaskPayload, TaskRunResult, TriggerOptions, TaskFromIdentifier, };
 export { SubtaskUnwrapError, TaskRunPromise };
 export type Context = TaskRunContext;
 export declare function queue(options: {
@@ -27,7 +27,7 @@ export declare function createSchemaTask<TIdentifier extends string, TSchema ext
  *
  * @returns {RunHandle} An object with the `id` of the run. Can be used to retrieve the completed run output in a typesafe manner.
  */
-export declare function trigger<TTask extends AnyTask>(id: TaskIdentifier<TTask>, payload: TaskPayload<TTask>, options?: TaskRunOptions, requestOptions?: TriggerApiRequestOptions): Promise<RunHandleFromTypes<InferRunTypes<TTask>>>;
+export declare function trigger<TTask extends AnyTask>(id: TaskIdentifier<TTask>, payload: TaskPayload<TTask>, options?: TriggerOptions, requestOptions?: TriggerApiRequestOptions): Promise<RunHandleFromTypes<InferRunTypes<TTask>>>;
 /**
  * Trigger a task with the given payload, and wait for the result. Returns the result of the task run
  * @param id - The id of the task to trigger
@@ -46,7 +46,7 @@ export declare function trigger<TTask extends AnyTask>(id: TaskIdentifier<TTask>
  * }
  * ```
  */
-export declare function triggerAndWait<TTask extends AnyTask>(id: TaskIdentifier<TTask>, payload: TaskPayload<TTask>, options?: TaskRunOptions, requestOptions?: ApiRequestOptions): TaskRunPromise<TaskOutput<TTask>>;
+export declare function triggerAndWait<TTask extends AnyTask>(id: TaskIdentifier<TTask>, payload: TaskPayload<TTask>, options?: TriggerAndWaitOptions, requestOptions?: ApiRequestOptions): TaskRunPromise<TaskIdentifier<TTask>, TaskOutput<TTask>>;
 /**
  * Batch trigger multiple task runs with the given payloads, and wait for the results. Returns the results of the task runs.
  * @param id - The id of the task to trigger
@@ -71,7 +71,7 @@ export declare function triggerAndWait<TTask extends AnyTask>(id: TaskIdentifier
  * }
  * ```
  */
-export declare function batchTriggerAndWait<TTask extends AnyTask>(id: TaskIdentifier<TTask>, items: Array<BatchItem<TaskPayload<TTask>>>, requestOptions?: ApiRequestOptions): Promise<BatchResult<TaskOutput<TTask>>>;
+export declare function batchTriggerAndWait<TTask extends AnyTask>(id: TaskIdentifier<TTask>, items: Array<BatchItem<TaskPayload<TTask>>>, requestOptions?: ApiRequestOptions): Promise<BatchResult<TaskIdentifier<TTask>, TaskOutput<TTask>>>;
 /**
  * Trigger a task by its identifier with the given payload and poll until the run is completed.
  *
@@ -87,5 +87,297 @@ export declare function batchTriggerAndWait<TTask extends AnyTask>(id: TaskIdent
  *
  * @returns {Run} The completed run, either successful or failed.
  */
-export declare function triggerAndPoll<TTask extends AnyTask>(id: TaskIdentifier<TTask>, payload: TaskPayload<TTask>, options?: TaskRunOptions & PollOptions, requestOptions?: TriggerApiRequestOptions): Promise<RetrieveRunResult<TTask>>;
-export declare function batchTrigger<TTask extends AnyTask>(id: TaskIdentifier<TTask>, items: Array<BatchItem<TaskPayload<TTask>>>, requestOptions?: TriggerApiRequestOptions): Promise<BatchRunHandleFromTypes<InferRunTypes<TTask>>>;
+export declare function triggerAndPoll<TTask extends AnyTask>(id: TaskIdentifier<TTask>, payload: TaskPayload<TTask>, options?: TriggerOptions & PollOptions, requestOptions?: TriggerApiRequestOptions): Promise<RetrieveRunResult<TTask>>;
+export declare function batchTrigger<TTask extends AnyTask>(id: TaskIdentifier<TTask>, items: Array<BatchItem<TaskPayload<TTask>>>, options?: BatchTriggerOptions, requestOptions?: TriggerApiRequestOptions): Promise<BatchRunHandleFromTypes<InferRunTypes<TTask>>>;
+/**
+ * Triggers multiple runs of different tasks with specified payloads and options.
+ *
+ * @template TTask - The type of task(s) to be triggered, extends AnyTask
+ *
+ * @param {Array<BatchByIdItem<InferRunTypes<TTask>>>} items - Array of task items to trigger
+ * @param {BatchTriggerOptions} [options] - Optional batch-level trigger options
+ * @param {TriggerApiRequestOptions} [requestOptions] - Optional API request configuration
+ *
+ * @returns {Promise<BatchRunHandleFromTypes<InferRunTypes<TTask>>>} A promise that resolves with the batch run handle
+ * containing batch ID, cached status, idempotency info, runs, and public access token
+ *
+ * @example
+ * ```ts
+ * import { batch } from "@trigger.dev/sdk/v3";
+ * import type { myTask1, myTask2 } from "~/trigger/myTasks";
+ *
+ * // Trigger multiple tasks with different payloads
+ * const result = await batch.trigger<typeof myTask1 | typeof myTask2>([
+ *   {
+ *     id: "my-task-1",
+ *     payload: { some: "data" },
+ *     options: {
+ *       queue: "default",
+ *       concurrencyKey: "key",
+ *       idempotencyKey: "unique-key",
+ *       delay: "5m",
+ *       tags: ["tag1", "tag2"]
+ *     }
+ *   },
+ *   {
+ *     id: "my-task-2",
+ *     payload: { other: "data" }
+ *   }
+ * ]);
+ * ```
+ *
+ * @description
+ * Each task item in the array can include:
+ * - `id`: The unique identifier of the task
+ * - `payload`: The data to pass to the task
+ * - `options`: Optional task-specific settings including:
+ *   - `queue`: Specify a queue for the task
+ *   - `concurrencyKey`: Control concurrent execution
+ *   - `idempotencyKey`: Prevent duplicate runs
+ *   - `idempotencyKeyTTL`: Time-to-live for idempotency key
+ *   - `delay`: Delay before task execution
+ *   - `ttl`: Time-to-live for the task
+ *   - `tags`: Array of tags for the task
+ *   - `maxAttempts`: Maximum retry attempts
+ *   - `metadata`: Additional metadata
+ *   - `maxDuration`: Maximum execution duration
+ */
+export declare function batchTriggerById<TTask extends AnyTask>(items: Array<BatchByIdItem<InferRunTypes<TTask>>>, options?: BatchTriggerOptions, requestOptions?: TriggerApiRequestOptions): Promise<BatchRunHandleFromTypes<InferRunTypes<TTask>>>;
+/**
+ * Triggers multiple tasks and waits for all of them to complete before returning their results.
+ * This function must be called from within a task.run() context.
+ *
+ * @template TTask - Union type of tasks to be triggered, extends AnyTask
+ *
+ * @param {Array<BatchByIdAndWaitItem<InferRunTypes<TTask>>>} items - Array of task items to trigger
+ * @param {TriggerApiRequestOptions} [requestOptions] - Optional API request configuration
+ *
+ * @returns {Promise<BatchByIdResult<TTask>>} A promise that resolves with the batch results, including
+ * success/failure status and strongly-typed outputs for each task
+ *
+ * @throws {Error} If called outside of a task.run() context
+ * @throws {Error} If no API client is configured
+ *
+ * @example
+ * ```ts
+ * import { batch, task } from "@trigger.dev/sdk/v3";
+ *
+ * export const parentTask = task({
+ *   id: "parent-task",
+ *   run: async (payload: string) => {
+ *     const results = await batch.triggerAndWait<typeof childTask1 | typeof childTask2>([
+ *       {
+ *         id: "child-task-1",
+ *         payload: { foo: "World" },
+ *         options: {
+ *           queue: "default",
+ *           delay: "5m",
+ *           tags: ["batch", "child1"]
+ *         }
+ *       },
+ *       {
+ *         id: "child-task-2",
+ *         payload: { bar: 42 }
+ *       }
+ *     ]);
+ *
+ *     // Type-safe result handling
+ *     for (const result of results) {
+ *       if (result.ok) {
+ *         switch (result.taskIdentifier) {
+ *           case "child-task-1":
+ *             console.log("Child task 1 output:", result.output); // string type
+ *             break;
+ *           case "child-task-2":
+ *             console.log("Child task 2 output:", result.output); // number type
+ *             break;
+ *         }
+ *       } else {
+ *         console.error("Task failed:", result.error);
+ *       }
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * @description
+ * Each task item in the array can include:
+ * - `id`: The task identifier (must match one of the tasks in the union type)
+ * - `payload`: Strongly-typed payload matching the task's input type
+ * - `options`: Optional task-specific settings including:
+ *   - `queue`: Specify a queue for the task
+ *   - `concurrencyKey`: Control concurrent execution
+ *   - `delay`: Delay before task execution
+ *   - `ttl`: Time-to-live for the task
+ *   - `tags`: Array of tags for the task
+ *   - `maxAttempts`: Maximum retry attempts
+ *   - `metadata`: Additional metadata
+ *   - `maxDuration`: Maximum execution duration
+ *
+ * The function provides full type safety for:
+ * - Task IDs
+ * - Payload types
+ * - Return value types
+ * - Error handling
+ */
+export declare function batchTriggerByIdAndWait<TTask extends AnyTask>(items: Array<BatchByIdAndWaitItem<InferRunTypes<TTask>>>, requestOptions?: TriggerApiRequestOptions): Promise<BatchByIdResult<TTask>>;
+/**
+ * Triggers multiple tasks and waits for all of them to complete before returning their results.
+ * This function must be called from within a task.run() context.
+ *
+ * @template TTask - Union type of tasks to be triggered, extends AnyTask
+ *
+ * @param {Array<BatchByIdAndWaitItem<InferRunTypes<TTask>>>} items - Array of task items to trigger
+ * @param {TriggerApiRequestOptions} [requestOptions] - Optional API request configuration
+ *
+ * @returns {Promise<BatchByIdResult<TTask>>} A promise that resolves with the batch results, including
+ * success/failure status and strongly-typed outputs for each task
+ *
+ * @throws {Error} If called outside of a task.run() context
+ * @throws {Error} If no API client is configured
+ *
+ * @example
+ * ```ts
+ * import { batch, task } from "@trigger.dev/sdk/v3";
+ *
+ * export const parentTask = task({
+ *   id: "parent-task",
+ *   run: async (payload: string) => {
+ *     const results = await batch.triggerAndWait<typeof childTask1 | typeof childTask2>([
+ *       {
+ *         id: "child-task-1",
+ *         payload: { foo: "World" },
+ *         options: {
+ *           queue: "default",
+ *           delay: "5m",
+ *           tags: ["batch", "child1"]
+ *         }
+ *       },
+ *       {
+ *         id: "child-task-2",
+ *         payload: { bar: 42 }
+ *       }
+ *     ]);
+ *
+ *     // Type-safe result handling
+ *     for (const result of results) {
+ *       if (result.ok) {
+ *         switch (result.taskIdentifier) {
+ *           case "child-task-1":
+ *             console.log("Child task 1 output:", result.output); // string type
+ *             break;
+ *           case "child-task-2":
+ *             console.log("Child task 2 output:", result.output); // number type
+ *             break;
+ *         }
+ *       } else {
+ *         console.error("Task failed:", result.error);
+ *       }
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * @description
+ * Each task item in the array can include:
+ * - `id`: The task identifier (must match one of the tasks in the union type)
+ * - `payload`: Strongly-typed payload matching the task's input type
+ * - `options`: Optional task-specific settings including:
+ *   - `queue`: Specify a queue for the task
+ *   - `concurrencyKey`: Control concurrent execution
+ *   - `delay`: Delay before task execution
+ *   - `ttl`: Time-to-live for the task
+ *   - `tags`: Array of tags for the task
+ *   - `maxAttempts`: Maximum retry attempts
+ *   - `metadata`: Additional metadata
+ *   - `maxDuration`: Maximum execution duration
+ *
+ * The function provides full type safety for:
+ * - Task IDs
+ * - Payload types
+ * - Return value types
+ * - Error handling
+ */
+export declare function batchTriggerTasks<TTasks extends readonly AnyTask[]>(items: {
+    [K in keyof TTasks]: BatchByTaskItem<TTasks[K]>;
+}, options?: BatchTriggerOptions, requestOptions?: TriggerApiRequestOptions): Promise<BatchTasksRunHandleFromTypes<TTasks>>;
+/**
+ * Triggers multiple tasks and waits for all of them to complete before returning their results.
+ * This function must be called from within a task.run() context.
+ *
+ * @template TTask - Union type of tasks to be triggered, extends AnyTask
+ *
+ * @param {Array<BatchByIdAndWaitItem<InferRunTypes<TTask>>>} items - Array of task items to trigger
+ * @param {TriggerApiRequestOptions} [requestOptions] - Optional API request configuration
+ *
+ * @returns {Promise<BatchByIdResult<TTask>>} A promise that resolves with the batch results, including
+ * success/failure status and strongly-typed outputs for each task
+ *
+ * @throws {Error} If called outside of a task.run() context
+ * @throws {Error} If no API client is configured
+ *
+ * @example
+ * ```ts
+ * import { batch, task } from "@trigger.dev/sdk/v3";
+ *
+ * export const parentTask = task({
+ *   id: "parent-task",
+ *   run: async (payload: string) => {
+ *     const results = await batch.triggerAndWait<typeof childTask1 | typeof childTask2>([
+ *       {
+ *         id: "child-task-1",
+ *         payload: { foo: "World" },
+ *         options: {
+ *           queue: "default",
+ *           delay: "5m",
+ *           tags: ["batch", "child1"]
+ *         }
+ *       },
+ *       {
+ *         id: "child-task-2",
+ *         payload: { bar: 42 }
+ *       }
+ *     ]);
+ *
+ *     // Type-safe result handling
+ *     for (const result of results) {
+ *       if (result.ok) {
+ *         switch (result.taskIdentifier) {
+ *           case "child-task-1":
+ *             console.log("Child task 1 output:", result.output); // string type
+ *             break;
+ *           case "child-task-2":
+ *             console.log("Child task 2 output:", result.output); // number type
+ *             break;
+ *         }
+ *       } else {
+ *         console.error("Task failed:", result.error);
+ *       }
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * @description
+ * Each task item in the array can include:
+ * - `id`: The task identifier (must match one of the tasks in the union type)
+ * - `payload`: Strongly-typed payload matching the task's input type
+ * - `options`: Optional task-specific settings including:
+ *   - `queue`: Specify a queue for the task
+ *   - `concurrencyKey`: Control concurrent execution
+ *   - `delay`: Delay before task execution
+ *   - `ttl`: Time-to-live for the task
+ *   - `tags`: Array of tags for the task
+ *   - `maxAttempts`: Maximum retry attempts
+ *   - `metadata`: Additional metadata
+ *   - `maxDuration`: Maximum execution duration
+ *
+ * The function provides full type safety for:
+ * - Task IDs
+ * - Payload types
+ * - Return value types
+ * - Error handling
+ */
+export declare function batchTriggerAndWaitTasks<TTasks extends readonly AnyTask[]>(items: {
+    [K in keyof TTasks]: BatchByTaskAndWaitItem<TTasks[K]>;
+}, requestOptions?: TriggerApiRequestOptions): Promise<BatchByTaskResult<TTasks>>;