@trigger.dev/sdk 3.0.0-beta.5 → 3.0.0-beta.50

package/dist/v3/index.d.ts

@@ -1,7 +1,324 @@
-import { TaskRunContext, InitOutput, RetryOptions, QueueOptions, MachineCpu, MachineMemory, RunFnParams, InitFnParams, HandleErrorFnParams, HandleErrorResult, MiddlewareFnParams, SuccessFnParams, FetchRetryOptions } from '@trigger.dev/core/v3';
-export { HandleErrorArgs, HandleErrorFunction, LogLevel, RetryOptions, ProjectConfig as TriggerConfig, logger } from '@trigger.dev/core/v3';
+import { RetryOptions, FetchRetryOptions, ListProjectRunsQueryParams, ApiRequestOptions, CursorPagePromise, ListRunResponseItem, ListRunsQueryParams, ApiPromise, ReplayRunResponse, CanceledRunResponse, RescheduleRunRequestBody, RetrieveRunResponse, TaskRunContext, QueueOptions, InitOutput, MachineCpu, MachineMemory, RunFnParams, InitFnParams, HandleErrorFnParams, HandleErrorResult, MiddlewareFnParams, StartFnParams, SuccessFnParams, FailureFnParams, ScheduledTaskPayload, CreateScheduleOptions, ScheduleObject, UpdateScheduleOptions, DeletedScheduleObject, ListScheduleOptions, OffsetLimitPagePromise, ImportEnvironmentVariablesParams, EnvironmentVariableResponseBody, EnvironmentVariables, CreateEnvironmentVariableParams, EnvironmentVariableValue, UpdateEnvironmentVariableParams, ApiClientConfiguration } from '@trigger.dev/core/v3';
+export { AbortTaskRunError, ApiClientConfiguration, ApiError, AuthenticationError, BadRequestError, ConflictError, HandleErrorArgs, HandleErrorFunction, ImportEnvironmentVariablesParams, InternalServerError, LogLevel, NotFoundError, PermissionDeniedError, RateLimitError, ResolveEnvironmentVariablesFunction, ResolveEnvironmentVariablesParams, ResolveEnvironmentVariablesResult, RetryOptions, ProjectConfig as TriggerConfig, UnprocessableEntityError, logger } from '@trigger.dev/core/v3';
 import { HttpHandler } from 'msw';
 
+type CacheMetadata = {
+    createdTime: number;
+    ttl?: number | null;
+};
+type CacheEntry<Value = unknown> = {
+    metadata: CacheMetadata;
+    value: Value;
+};
+type Eventually<Value> = Value | null | undefined | Promise<Value | null | undefined>;
+type CacheStore<Value = any> = {
+    name?: string;
+    get: (key: string) => Eventually<CacheEntry<Value>>;
+    set: (key: string, value: CacheEntry<Value>) => unknown | Promise<unknown>;
+    delete: (key: string) => unknown | Promise<unknown>;
+};
+type CacheFunction = <Value>(cacheKey: string, fn: () => Promise<Value> | Value) => Promise<Value> | Value;
+declare class InMemoryCache<Value = any> {
+    private _cache;
+    get(key: string): Eventually<CacheEntry<Value>>;
+    set(key: string, value: CacheEntry<Value>): unknown;
+    delete(key: string): unknown;
+}
+/**
+ * Create a cache function that uses the provided store to cache values. Using InMemoryCache is safe because each task run is isolated.
+ * @param store
+ * @returns
+ */
+declare function createCache(store: CacheStore): CacheFunction;
+
+declare function onThrow<T>(fn: (options: {
+    attempt: number;
+    maxAttempts: number;
+}) => Promise<T>, options: RetryOptions): Promise<T>;
+interface RetryFetchRequestInit extends RequestInit {
+    retry?: FetchRetryOptions;
+    timeoutInMs?: number;
+}
+declare function retryFetch(input: RequestInfo | URL, init?: RetryFetchRequestInit | undefined): Promise<Response>;
+declare const retry: {
+    onThrow: typeof onThrow;
+    fetch: typeof retryFetch;
+    interceptFetch: (...handlers: Array<HttpHandler>) => {
+        run: <T>(fn: (...args: any[]) => Promise<T>) => Promise<T>;
+    };
+};
+
+type RetrieveRunResult<TOutput> = Prettify<TOutput extends RunHandle<infer THandleOutput> ? Omit<RetrieveRunResponse, "output"> & {
+    output?: THandleOutput;
+} : Omit<RetrieveRunResponse, "output"> & {
+    output?: TOutput;
+}>;
+declare const runs: {
+    replay: typeof replayRun;
+    cancel: typeof cancelRun;
+    retrieve: typeof retrieveRun;
+    list: typeof listRuns;
+    reschedule: typeof rescheduleRun;
+    poll: typeof poll;
+};
+declare function listRuns(projectRef: string, params?: ListProjectRunsQueryParams, requestOptions?: ApiRequestOptions): CursorPagePromise<typeof ListRunResponseItem>;
+declare function listRuns(params?: ListRunsQueryParams, requestOptions?: ApiRequestOptions): CursorPagePromise<typeof ListRunResponseItem>;
+declare function retrieveRun<TRunId extends RunHandle<any> | string>(runId: TRunId, requestOptions?: ApiRequestOptions): ApiPromise<RetrieveRunResult<TRunId>>;
+declare function replayRun(runId: string, requestOptions?: ApiRequestOptions): ApiPromise<ReplayRunResponse>;
+declare function cancelRun(runId: string, requestOptions?: ApiRequestOptions): ApiPromise<CanceledRunResponse>;
+declare function rescheduleRun(runId: string, body: RescheduleRunRequestBody, requestOptions?: ApiRequestOptions): ApiPromise<RetrieveRunResponse>;
+type PollOptions = {
+    pollIntervalMs?: number;
+};
+declare function poll<TRunHandle extends RunHandle<any> | string>(handle: TRunHandle, options?: {
+    pollIntervalMs?: number;
+}, requestOptions?: ApiRequestOptions): Promise<(TRunHandle extends RunHandle<infer THandleOutput> ? Omit<{
+    status: "CANCELED" | "COMPLETED" | "FAILED" | "WAITING_FOR_DEPLOY" | "QUEUED" | "EXECUTING" | "REATTEMPTING" | "FROZEN" | "CRASHED" | "INTERRUPTED" | "SYSTEM_FAILURE" | "DELAYED" | "EXPIRED";
+    id: string;
+    isTest: boolean;
+    createdAt: Date;
+    attempts: ({
+        status: "PENDING" | "CANCELED" | "COMPLETED" | "FAILED" | "EXECUTING" | "PAUSED";
+        id: string;
+        createdAt: Date;
+        updatedAt: Date;
+        startedAt?: Date | undefined;
+        completedAt?: Date | undefined;
+        error?: {
+            message: string;
+            name?: string | undefined;
+            stackTrace?: string | undefined;
+        } | undefined;
+    } | undefined)[];
+    updatedAt: Date;
+    taskIdentifier: string;
+    isQueued: boolean;
+    isExecuting: boolean;
+    isCompleted: boolean;
+    isSuccess: boolean;
+    isFailed: boolean;
+    isCancelled: boolean;
+    payload?: any;
+    payloadPresignedUrl?: string | undefined;
+    output?: any;
+    outputPresignedUrl?: string | undefined;
+    schedule?: {
+        id: string;
+        generator: {
+            type: "CRON";
+            expression: string;
+            description: string;
+        };
+        externalId?: string | undefined;
+        deduplicationKey?: string | undefined;
+    } | undefined;
+    idempotencyKey?: string | undefined;
+    version?: string | undefined;
+    startedAt?: Date | undefined;
+    finishedAt?: Date | undefined;
+    delayedUntil?: Date | undefined;
+    ttl?: string | undefined;
+    expiredAt?: Date | undefined;
+}, "output"> & {
+    output?: THandleOutput | undefined;
+} : Omit<{
+    status: "CANCELED" | "COMPLETED" | "FAILED" | "WAITING_FOR_DEPLOY" | "QUEUED" | "EXECUTING" | "REATTEMPTING" | "FROZEN" | "CRASHED" | "INTERRUPTED" | "SYSTEM_FAILURE" | "DELAYED" | "EXPIRED";
+    id: string;
+    isTest: boolean;
+    createdAt: Date;
+    attempts: ({
+        status: "PENDING" | "CANCELED" | "COMPLETED" | "FAILED" | "EXECUTING" | "PAUSED";
+        id: string;
+        createdAt: Date;
+        updatedAt: Date;
+        startedAt?: Date | undefined;
+        completedAt?: Date | undefined;
+        error?: {
+            message: string;
+            name?: string | undefined;
+            stackTrace?: string | undefined;
+        } | undefined;
+    } | undefined)[];
+    updatedAt: Date;
+    taskIdentifier: string;
+    isQueued: boolean;
+    isExecuting: boolean;
+    isCompleted: boolean;
+    isSuccess: boolean;
+    isFailed: boolean;
+    isCancelled: boolean;
+    payload?: any;
+    payloadPresignedUrl?: string | undefined;
+    output?: any;
+    outputPresignedUrl?: string | undefined;
+    schedule?: {
+        id: string;
+        generator: {
+            type: "CRON";
+            expression: string;
+            description: string;
+        };
+        externalId?: string | undefined;
+        deduplicationKey?: string | undefined;
+    } | undefined;
+    idempotencyKey?: string | undefined;
+    version?: string | undefined;
+    startedAt?: Date | undefined;
+    finishedAt?: Date | undefined;
+    delayedUntil?: Date | undefined;
+    ttl?: string | undefined;
+    expiredAt?: Date | undefined;
+}, "output"> & {
+    output?: TRunHandle | undefined;
+}) extends infer T ? { [K in keyof T]: (TRunHandle extends RunHandle<infer THandleOutput> ? Omit<{
+    status: "CANCELED" | "COMPLETED" | "FAILED" | "WAITING_FOR_DEPLOY" | "QUEUED" | "EXECUTING" | "REATTEMPTING" | "FROZEN" | "CRASHED" | "INTERRUPTED" | "SYSTEM_FAILURE" | "DELAYED" | "EXPIRED";
+    id: string;
+    isTest: boolean;
+    createdAt: Date;
+    attempts: ({
+        status: "PENDING" | "CANCELED" | "COMPLETED" | "FAILED" | "EXECUTING" | "PAUSED";
+        id: string;
+        createdAt: Date;
+        updatedAt: Date;
+        startedAt?: Date | undefined;
+        completedAt?: Date | undefined;
+        error?: {
+            message: string;
+            name?: string | undefined;
+            stackTrace?: string | undefined;
+        } | undefined;
+    } | undefined)[];
+    updatedAt: Date;
+    taskIdentifier: string;
+    isQueued: boolean;
+    isExecuting: boolean;
+    isCompleted: boolean;
+    isSuccess: boolean;
+    isFailed: boolean;
+    isCancelled: boolean;
+    payload?: any;
+    payloadPresignedUrl?: string | undefined;
+    output?: any;
+    outputPresignedUrl?: string | undefined;
+    schedule?: {
+        id: string;
+        generator: {
+            type: "CRON";
+            expression: string;
+            description: string;
+        };
+        externalId?: string | undefined;
+        deduplicationKey?: string | undefined;
+    } | undefined;
+    idempotencyKey?: string | undefined;
+    version?: string | undefined;
+    startedAt?: Date | undefined;
+    finishedAt?: Date | undefined;
+    delayedUntil?: Date | undefined;
+    ttl?: string | undefined;
+    expiredAt?: Date | undefined;
+}, "output"> & {
+    output?: THandleOutput | undefined;
+} : Omit<{
+    status: "CANCELED" | "COMPLETED" | "FAILED" | "WAITING_FOR_DEPLOY" | "QUEUED" | "EXECUTING" | "REATTEMPTING" | "FROZEN" | "CRASHED" | "INTERRUPTED" | "SYSTEM_FAILURE" | "DELAYED" | "EXPIRED";
+    id: string;
+    isTest: boolean;
+    createdAt: Date;
+    attempts: ({
+        status: "PENDING" | "CANCELED" | "COMPLETED" | "FAILED" | "EXECUTING" | "PAUSED";
+        id: string;
+        createdAt: Date;
+        updatedAt: Date;
+        startedAt?: Date | undefined;
+        completedAt?: Date | undefined;
+        error?: {
+            message: string;
+            name?: string | undefined;
+            stackTrace?: string | undefined;
+        } | undefined;
+    } | undefined)[];
+    updatedAt: Date;
+    taskIdentifier: string;
+    isQueued: boolean;
+    isExecuting: boolean;
+    isCompleted: boolean;
+    isSuccess: boolean;
+    isFailed: boolean;
+    isCancelled: boolean;
+    payload?: any;
+    payloadPresignedUrl?: string | undefined;
+    output?: any;
+    outputPresignedUrl?: string | undefined;
+    schedule?: {
+        id: string;
+        generator: {
+            type: "CRON";
+            expression: string;
+            description: string;
+        };
+        externalId?: string | undefined;
+        deduplicationKey?: string | undefined;
+    } | undefined;
+    idempotencyKey?: string | undefined;
+    version?: string | undefined;
+    startedAt?: Date | undefined;
+    finishedAt?: Date | undefined;
+    delayedUntil?: Date | undefined;
+    ttl?: string | undefined;
+    expiredAt?: Date | undefined;
+}, "output"> & {
+    output?: TRunHandle | undefined;
+})[K]; } : never>;
+
+declare const idempotencyKeys: {
+    create: typeof createIdempotencyKey;
+};
+declare const __brand: unique symbol;
+type Brand<B> = {
+    [__brand]: B;
+};
+type Branded<T, B> = T & Brand<B>;
+type IdempotencyKey = Branded<string, "IdempotencyKey">;
+declare function isIdempotencyKey(value: string | string[] | IdempotencyKey): value is IdempotencyKey;
+/**
+ * Creates a deterministic idempotency key based on the provided key material.
+ *
+ * If running inside a task, the task run ID is automatically included in the key material, giving you a unique key per task run.
+ * This ensures that a given child task is only triggered once per task run, even if the parent task is retried.
+ *
+ * @param {string | string[]} key The key material to create the idempotency key from.
+ * @param {object} [options] Additional options.
+ * @param {"run" | "attempt" | "global"} [options.scope="run"] The scope of the idempotency key.
+ *
+ * @returns {Promise<IdempotencyKey>} The idempotency key as a branded string.
+ *
+ * @example
+ *
+ * ```typescript
+ * import { idempotencyKeys, task } from "@trigger.dev/sdk/v3";
+ *
+ * export const myTask = task({
+ *  id: "my-task",
+ *  run: async (payload: any) => {
+ *   const idempotencyKey = await idempotencyKeys.create("my-task-key");
+ *
+ *   // Use the idempotency key when triggering child tasks
+ *   await childTask.triggerAndWait(payload, { idempotencyKey });
+ *  }
+ * });
+ * ```
+ *
+ * You can also use the `scope` parameter to create a key that is unique per task run, task run attempts (retries of the same run), or globally:
+ *
+ * ```typescript
+ *  await idempotencyKeys.create("my-task-key", { scope: "attempt" }); // Creates a key that is unique per task run attempt
+ *  await idempotencyKeys.create("my-task-key", { scope: "global" }); // Skips including the task run ID
+ * ```
+ */
+declare function createIdempotencyKey(key: string | string[], options?: {
+    scope?: "run" | "attempt" | "global";
+}): Promise<IdempotencyKey>;
+
 type Context = TaskRunContext;
 type RequireOne<T, K extends keyof T> = {
     [X in Exclude<keyof T, K>]?: T[X];
@@ -9,9 +326,12 @@ type RequireOne<T, K extends keyof T> = {
     [P in K]-?: T[P];
 };
 type Queue = RequireOne<QueueOptions, "name">;
-type TaskOptions<TPayload, TOutput = any, TInitOutput extends InitOutput = any> = {
+declare function queue(options: {
+    name: string;
+} & QueueOptions): Queue;
+type TaskOptions<TIdentifier extends string, TPayload = void, TOutput = unknown, TInitOutput extends InitOutput = any> = {
     /** An id for your task. This must be unique inside your project and not change between versions.  */
-    id: string;
+    id: TIdentifier;
     /** The retry settings when an uncaught error is thrown.
      *
      * If omitted it will use the values in your `trigger.config.ts` file.
@@ -79,6 +399,7 @@ type TaskOptions<TPayload, TOutput = any, TInitOutput extends InitOutput = any>
          * - 1
          * - 2
          * - 4
+         * @deprecated use preset instead
          */
         cpu?: MachineCpu;
         /** In GBs of RAM. The default is 1.
@@ -90,8 +411,11 @@ type TaskOptions<TPayload, TOutput = any, TInitOutput extends InitOutput = any>
          * - 2
          * - 4
          * - 8
+         * * @deprecated use preset instead
          */
         memory?: MachineMemory;
+        /** Preset to use for the machine. Defaults to small-1x */
+        preset?: "micro" | "small-1x" | "small-2x" | "medium-1x" | "medium-2x" | "large-1x" | "large-2x";
     };
     /** This gets called when a task is triggered. It's where you put the code you want to execute.
      *
@@ -99,19 +423,64 @@ type TaskOptions<TPayload, TOutput = any, TInitOutput extends InitOutput = any>
      * @param params - Metadata about the run.
      */
     run: (payload: TPayload, params: RunFnParams<TInitOutput>) => Promise<TOutput>;
+    /**
+     * init is called before the run function is called. It's useful for setting up any global state.
+     */
     init?: (payload: TPayload, params: InitFnParams) => Promise<TInitOutput>;
-    handleError?: (payload: TPayload, error: unknown, params: HandleErrorFnParams<TInitOutput>) => HandleErrorResult;
+    /**
+     * cleanup is called after the run function has completed.
+     */
     cleanup?: (payload: TPayload, params: RunFnParams<TInitOutput>) => Promise<void>;
+    /**
+     * handleError is called when the run function throws an error. It can be used to modify the error or return new retry options.
+     */
+    handleError?: (payload: TPayload, error: unknown, params: HandleErrorFnParams<TInitOutput>) => HandleErrorResult;
+    /**
+     * middleware allows you to run code "around" the run function. This can be useful for logging, metrics, or other cross-cutting concerns.
+     *
+     * When writing middleware, you should always call `next()` to continue the execution of the task:
+     *
+     * ```ts
+     * export const middlewareTask = task({
+     *  id: "middleware-task",
+     *  middleware: async (payload, { ctx, next }) => {
+     *   console.log("Before run");
+     *   await next();
+     *   console.log("After run");
+     *  },
+     *  run: async (payload, { ctx }) => {}
+     * });
+     * ```
+     */
     middleware?: (payload: TPayload, params: MiddlewareFnParams) => Promise<void>;
-    onSuccess?: (payload: TPayload, params: SuccessFnParams<TOutput, TInitOutput>) => Promise<void>;
+    /**
+     * onStart is called the first time a task is executed in a run (not before every retry)
+     */
+    onStart?: (payload: TPayload, params: StartFnParams) => Promise<void>;
+    /**
+     * onSuccess is called after the run function has successfully completed.
+     */
+    onSuccess?: (payload: TPayload, output: TOutput, params: SuccessFnParams<TInitOutput>) => Promise<void>;
+    /**
+     * onFailure is called after a task run has failed (meaning the run function threw an error and won't be retried anymore)
+     */
+    onFailure?: (payload: TPayload, error: unknown, params: FailureFnParams<TInitOutput>) => Promise<void>;
 };
-type InvokeHandle = {
-    id: string;
+declare const __output: unique symbol;
+type BrandOutput<B> = {
+    [__output]: B;
 };
-type InvokeBatchHandle = {
+type BrandedOutput<T, B> = T & BrandOutput<B>;
+type RunHandle<TOutput> = BrandedOutput<{
+    id: string;
+}, TOutput>;
+/**
+ * A BatchRunHandle can be used to retrieve the runs of a batch trigger in a typesafe manner.
+ */
+type BatchRunHandle<TOutput> = BrandedOutput<{
     batchId: string;
-    runs: string[];
-};
+    runs: Array<RunHandle<TOutput>>;
+}, TOutput>;
 type TaskRunResult<TOutput = any> = {
     ok: true;
     id: string;
@@ -119,48 +488,202 @@ type TaskRunResult<TOutput = any> = {
 } | {
     ok: false;
     id: string;
-    error: any;
+    error: unknown;
 };
 type BatchResult<TOutput = any> = {
     id: string;
     runs: TaskRunResult<TOutput>[];
 };
-type Task<TInput, TOutput = any> = {
-    trigger: (params: {
-        payload: TInput;
-        options?: TaskRunOptions;
-    }) => Promise<InvokeHandle>;
-    batchTrigger: (params: {
-        items: {
-            payload: TInput;
-            options?: TaskRunOptions;
-        }[];
-        batchOptions?: BatchRunOptions;
-    }) => Promise<InvokeBatchHandle>;
-    triggerAndWait: (params: {
-        payload: TInput;
-        options?: TaskRunOptions;
-    }) => Promise<TOutput>;
-    batchTriggerAndWait: (params: {
-        items: {
-            payload: TInput;
-            options?: TaskRunOptions;
-        }[];
-        batchOptions?: BatchRunOptions;
-    }) => Promise<BatchResult<TOutput>>;
+type BatchItem<TInput> = TInput extends void ? {
+    payload?: TInput;
+    options?: TaskRunOptions;
+} : {
+    payload: TInput;
+    options?: TaskRunOptions;
 };
+interface Task<TIdentifier extends string, TInput = void, TOutput = any> {
+    /**
+     * The id of the task.
+     */
+    id: TIdentifier;
+    /**
+     * Trigger a task with the given payload, and continue without waiting for the result. If you want to wait for the result, use `triggerAndWait`. Returns the id of the triggered task run.
+     * @param payload
+     * @param options
+     * @returns RunHandle
+     * - `id` - The id of the triggered task run.
+     */
+    trigger: (payload: TInput, options?: TaskRunOptions) => Promise<RunHandle<TOutput>>;
+    /**
+     * Batch trigger multiple task runs with the given payloads, and continue without waiting for the results. If you want to wait for the results, use `batchTriggerAndWait`. Returns the id of the triggered batch.
+     * @param items
+     * @returns InvokeBatchHandle
+     * - `batchId` - The id of the triggered batch.
+     * - `runs` - The ids of the triggered task runs.
+     */
+    batchTrigger: (items: Array<BatchItem<TInput>>) => Promise<BatchRunHandle<TOutput>>;
+    /**
+     * Trigger a task with the given payload, and wait for the result. Returns the result of the task run
+     * @param payload
+     * @param options - Options for the task run
+     * @returns TaskRunResult
+     * @example
+     * ```
+     * const result = await task.triggerAndWait({ foo: "bar" });
+     *
+     * if (result.ok) {
+     *  console.log(result.output);
+     * } else {
+     *  console.error(result.error);
+     * }
+     * ```
+     */
+    triggerAndWait: (payload: TInput, options?: TaskRunOptions) => Promise<TaskRunResult<TOutput>>;
+    /**
+     * Batch trigger multiple task runs with the given payloads, and wait for the results. Returns the results of the task runs.
+     * @param items
+     * @returns BatchResult
+     * @example
+     * ```
+     * const result = await task.batchTriggerAndWait([
+     *  { payload: { foo: "bar" } },
+     *  { payload: { foo: "baz" } },
+     * ]);
+     *
+     * for (const run of result.runs) {
+     *  if (run.ok) {
+     *    console.log(run.output);
+     *  } else {
+     *    console.error(run.error);
+     *  }
+     * }
+     * ```
+     */
+    batchTriggerAndWait: (items: Array<BatchItem<TInput>>) => Promise<BatchResult<TOutput>>;
+}
+type AnyTask = Task<string, any, any>;
+type TaskPayload<TTask extends AnyTask> = TTask extends Task<string, infer TInput, any> ? TInput : never;
+type TaskOutput<TTask extends AnyTask> = TTask extends Task<string, any, infer TOutput> ? TOutput : never;
+type TaskOutputHandle<TTask extends AnyTask> = TTask extends Task<string, any, infer TOutput> ? RunHandle<TOutput> : never;
+type TaskBatchOutputHandle<TTask extends AnyTask> = TTask extends Task<string, any, infer TOutput> ? BatchRunHandle<TOutput> : never;
+type TaskIdentifier<TTask extends AnyTask> = TTask extends Task<infer TIdentifier, any, any> ? TIdentifier : never;
 type TaskRunOptions = {
-    idempotencyKey?: string;
+    /**
+     * A unique key that can be used to ensure that a task is only triggered once per key.
+     *
+     * You can use `idempotencyKeys.create` to create an idempotency key first, and then pass it to the task options.
+     *
+     * @example
+     *
+     * ```typescript
+     * import { idempotencyKeys, task } from "@trigger.dev/sdk/v3";
+     *
+     * export const myTask = task({
+     *  id: "my-task",
+     *  run: async (payload: any) => {
+     *   // scoped to the task run by default
+     *   const idempotencyKey = await idempotencyKeys.create("my-task-key");
+     *
+     *   // Use the idempotency key when triggering child tasks
+     *   await childTask.triggerAndWait(payload, { idempotencyKey });
+     *
+     *   // scoped globally, does not include the task run ID
+     *   const globalIdempotencyKey = await idempotencyKeys.create("my-task-key", { scope: "global" });
+     *
+     *   await childTask.triggerAndWait(payload, { idempotencyKey: globalIdempotencyKey });
+     *
+     *   // You can also pass a string directly, which is the same as a global idempotency key
+     *   await childTask.triggerAndWait(payload, { idempotencyKey: "my-very-unique-key" });
+     *  }
+     * });
+     * ```
+     *
+     * When triggering a task inside another task, we automatically inject the run ID into the key material.
+     *
+     * If you are triggering a task from your backend, ensure you include some sufficiently unique key material to prevent collisions.
+     *
+     * @example
+     *
+     * ```typescript
+     * import { idempotencyKeys, tasks } from "@trigger.dev/sdk/v3";
+     *
+     * // Somewhere in your backend
+     * const idempotencyKey = await idempotenceKeys.create(["my-task-trigger", "user-123"]);
+     * await tasks.trigger("my-task", { foo: "bar" }, { idempotencyKey });
+     * ```
+     *
+     */
+    idempotencyKey?: IdempotencyKey | string | string[];
     maxAttempts?: number;
-    startAt?: Date;
-    startAfter?: number;
     queue?: TaskRunConcurrencyOptions;
     concurrencyKey?: string;
+    /**
+     * The delay before the task is executed. This can be a string like "1h" or a Date object.
+     *
+     * @example
+     * "1h" - 1 hour
+     * "30d" - 30 days
+     * "15m" - 15 minutes
+     * "2w" - 2 weeks
+     * "60s" - 60 seconds
+     * new Date("2025-01-01T00:00:00Z")
+     */
+    delay?: string | Date;
+    /**
+     * Set a time-to-live for this run. If the run is not executed within this time, it will be removed from the queue and never execute.
+     *
+     * @example
+     *
+     * ```ts
+     * await myTask.trigger({ foo: "bar" }, { ttl: "1h" });
+     * await myTask.trigger({ foo: "bar" }, { ttl: 60 * 60 }); // 1 hour
+     * ```
+     *
+     * The minimum value is 1 second. Setting the `ttl` to `0` will disable the TTL and the run will never expire.
+     *
+     * **Note:** Runs in development have a default `ttl` of 10 minutes. You can override this by setting the `ttl` option.
+     */
+    ttl?: string | number;
 };
 type TaskRunConcurrencyOptions = Queue;
-type BatchRunOptions = TaskRunOptions & {
-    maxConcurrency?: number;
-};
+type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/**
+ * Trigger a task by its identifier with the given payload. Returns a typesafe `RunHandle`.
+ *
+ * @example
+ *
+ * ```ts
+ * import { tasks, runs } from "@trigger.dev/sdk/v3";
+ * import type { myTask } from "./myTasks"; // Import just the type of the task
+ *
+ * const handle = await tasks.trigger<typeof myTask>("my-task", { foo: "bar" }); // The id and payload are fully typesafe
+ * const run = await runs.retrieve(handle);
+ * console.log(run.output) // The output is also fully typed
+ * ```
+ *
+ * @returns {RunHandle} An object with the `id` of the run. Can be used to retrieve the completed run output in a typesafe manner.
+ */
+declare function trigger<TTask extends AnyTask>(id: TaskIdentifier<TTask>, payload: TaskPayload<TTask>, options?: TaskRunOptions, requestOptions?: ApiRequestOptions): Promise<TaskOutputHandle<TTask>>;
+declare function triggerAndWait<TTask extends AnyTask>(id: TaskIdentifier<TTask>, payload: TaskPayload<TTask>, options?: TaskRunOptions, requestOptions?: ApiRequestOptions): Promise<TaskRunResult<TaskOutput<TTask>>>;
+/**
+ * Trigger a task by its identifier with the given payload and poll until the run is completed.
+ *
+ * @example
+ *
+ * ```ts
+ * import { tasks, runs } from "@trigger.dev/sdk/v3";
+ * import type { myTask } from "./myTasks"; // Import just the type of the task
+ *
+ * const run = await tasks.triggerAndPoll<typeof myTask>("my-task", { foo: "bar" }); // The id and payload are fully typesafe
+ * console.log(run.output) // The output is also fully typed
+ * ```
+ *
+ * @returns {Run} The completed run, either successful or failed.
+ */
+declare function triggerAndPoll<TTask extends AnyTask>(id: TaskIdentifier<TTask>, payload: TaskPayload<TTask>, options?: TaskRunOptions & PollOptions, requestOptions?: ApiRequestOptions): Promise<RetrieveRunResult<TaskOutputHandle<TTask>>>;
+declare function batchTrigger<TTask extends AnyTask>(id: TaskIdentifier<TTask>, items: Array<BatchItem<TaskPayload<TTask>>>, requestOptions?: ApiRequestOptions): Promise<TaskBatchOutputHandle<TTask>>;
 
 /** Creates a task that can be triggered
  * @param options - Task options
@@ -180,7 +703,13 @@ type BatchRunOptions = TaskRunOptions & {
  *
  * @returns A task that can be triggered
  */
-declare function task<TInput, TOutput = any, TInitOutput extends InitOutput = any>(options: TaskOptions<TInput, TOutput, TInitOutput>): Task<TInput, TOutput>;
+declare function task$1<TIdentifier extends string, TInput = void, TOutput = unknown, TInitOutput extends InitOutput = any>(options: TaskOptions<TIdentifier, TInput, TOutput, TInitOutput>): Task<TIdentifier, TInput, TOutput>;
+declare const tasks: {
+    trigger: typeof trigger;
+    triggerAndPoll: typeof triggerAndPoll;
+    batchTrigger: typeof batchTrigger;
+    triggerAndWait: typeof triggerAndWait;
+};
 
 type WaitOptions = {
     seconds: number;
@@ -205,50 +734,220 @@ declare const wait: {
     }) => Promise<void>;
 };
 
-type CacheMetadata = {
-    createdTime: number;
-    ttl?: number | null;
+type ComputeUsage = {
+    costInCents: number;
+    durationMs: number;
 };
-type CacheEntry<Value = unknown> = {
-    metadata: CacheMetadata;
-    value: Value;
+type CurrentUsage = {
+    compute: {
+        attempt: ComputeUsage;
+        total: ComputeUsage;
+    };
+    baseCostInCents: number;
+    totalCostInCents: number;
 };
-type Eventually<Value> = Value | null | undefined | Promise<Value | null | undefined>;
-type CacheStore<Value = any> = {
-    name?: string;
-    get: (key: string) => Eventually<CacheEntry<Value>>;
-    set: (key: string, value: CacheEntry<Value>) => unknown | Promise<unknown>;
-    delete: (key: string) => unknown | Promise<unknown>;
+declare const usage: {
+    /**
+     * Get the current running usage of this task run.
+     *
+     * @example
+     *
+     * ```typescript
+     * import { usage, task } from "@trigger.dev/sdk/v3";
+     *
+     * export const myTask = task({
+     *  id: "my-task",
+     *  run: async (payload, { ctx }) => {
+     *   // ... Do a bunch of work
+     *
+     *   const currentUsage = usage.getCurrent();
+     *
+     *   // You have access to the current compute cost and duration up to this point
+     *   console.log("Current attempt compute cost and duration", {
+     *     cost: currentUsage.compute.attempt.costInCents,
+     *     duration: currentUsage.compute.attempt.durationMs,
+     *   });
+     *
+     *   // You also can see the total compute cost and duration up to this point in the run, across all attempts
+     *   console.log("Current total compute cost and duration", {
+     *     cost: currentUsage.compute.total.costInCents,
+     *     duration: currentUsage.compute.total.durationMs,
+     *   });
+     *
+     *   // You can see the base cost of the run, which is the cost of the run before any compute costs
+     *   console.log("Total cost", {
+     *     cost: currentUsage.totalCostInCents,
+     *     baseCost: currentUsage.baseCostInCents,
+     *   });
+     *  },
+     * });
+     * ```
+     */
+    getCurrent: () => CurrentUsage;
+    /**
+     * Measure the cost and duration of a function.
+     *
+     * @example
+     *
+     * ```typescript
+     * import { usage } from "@trigger.dev/sdk/v3";
+     *
+     * export const myTask = task({
+     *  id: "my-task",
+     *  run: async (payload, { ctx }) => {
+     *    const { result, compute } = await usage.measure(async () => {
+     *      // Do some work
+     *      return "result";
+     *    });
+     *
+     *    console.log("Result", result);
+     *    console.log("Cost and duration", { cost: compute.costInCents, duration: compute.durationMs });
+     *  },
+     * });
+     * ```
+     */
+    measure: <T>(cb: () => Promise<T>) => Promise<{
+        result: T;
+        compute: ComputeUsage;
+    }>;
 };
-type CacheFunction = <Value>(cacheKey: string, fn: () => Promise<Value> | Value) => Promise<Value> | Value;
-declare class InMemoryCache<Value = any> {
-    private _cache;
-    get(key: string): Eventually<CacheEntry<Value>>;
-    set(key: string, value: CacheEntry<Value>): unknown;
-    delete(key: string): unknown;
-}
+
+type ScheduleOptions<TIdentifier extends string, TOutput, TInitOutput extends InitOutput> = TaskOptions<TIdentifier, ScheduledTaskPayload, TOutput, TInitOutput> & {
+    /** You can optionally specify a CRON schedule on your task. You can also dynamically add a schedule in the dashboard or using the SDK functions.
+     *
+     * 1. Pass a CRON pattern string
+     * ```ts
+     * "0 0 * * *"
+     * ```
+     *
+     * 2. Or an object with a pattern and an optional timezone (default is "UTC")
+     * ```ts
+     * {
+     *   pattern: "0 0 * * *",
+     *   timezone: "America/Los_Angeles"
+     * }
+     * ```
+     *
+     * @link https://trigger.dev/docs/v3/tasks-scheduled
+     */
+    cron?: string | {
+        pattern: string;
+        timezone?: string;
+    };
+};
+declare function task<TIdentifier extends string, TOutput, TInitOutput extends InitOutput>(params: ScheduleOptions<TIdentifier, TOutput, TInitOutput>): Task<TIdentifier, ScheduledTaskPayload, TOutput>;
 /**
- * Create a cache function that uses the provided store to cache values. Using InMemoryCache is safe because each task run is isolated.
- * @param store
- * @returns
+ * Creates a new schedule
+ * @param options
+ * @param options.task - The identifier of the task to be scheduled (Must already exist and be a scheduled task)
+ * @param options.cron - The cron expression for the schedule (e.g. `0 0 * * *`)
+ * @param options.timezone - An optional timezone for the schedule in the IANA format (e.g. `America/Los_Angeles`). Defaults to "UTC".
+ * @param options.externalId - An optional external identifier for the schedule
+ * @param options.deduplicationKey - An optional deduplication key for the schedule
+ * @returns The created schedule
  */
-declare function createCache(store: CacheStore): CacheFunction;
+declare function create$1(options: CreateScheduleOptions, requestOptions?: ApiRequestOptions): ApiPromise<ScheduleObject>;
+/**
+ * Retrieves a schedule
+ * @param scheduleId - The ID of the schedule to retrieve
+ * @returns The retrieved schedule
+ */
+declare function retrieve$1(scheduleId: string, requestOptions?: ApiRequestOptions): ApiPromise<ScheduleObject>;
+/**
+ * Updates a schedule
+ * @param scheduleId - The ID of the schedule to update
+ * @param options - The updated schedule options
+ * @param options.task - The identifier of the task to be scheduled (Must already exist and be a scheduled task)
+ * @param options.cron - The cron expression for the schedule (e.g. `0 0 * * *`)
+ * @param options.timezone - An optional timezone for the schedule in the IANA format (e.g. `America/Los_Angeles`). Defaults to "UTC".
+ * @param options.externalId - An optional external identifier for the schedule
+ * @returns The updated schedule
+ */
+declare function update$1(scheduleId: string, options: UpdateScheduleOptions, requestOptions?: ApiRequestOptions): ApiPromise<ScheduleObject>;
+/**
+ * Deletes a schedule
+ * @param scheduleId - The ID of the schedule to delete
+ */
+declare function del$1(scheduleId: string, requestOptions?: ApiRequestOptions): ApiPromise<DeletedScheduleObject>;
+/**
+ * Deactivates a schedule
+ * @param scheduleId - The ID of the schedule to deactivate
+ */
+declare function deactivate(scheduleId: string, requestOptions?: ApiRequestOptions): ApiPromise<ScheduleObject>;
+/**
+ * Activates a schedule
+ * @param scheduleId - The ID of the schedule to activate
+ */
+declare function activate(scheduleId: string, requestOptions?: ApiRequestOptions): ApiPromise<ScheduleObject>;
+/**
+ * Lists schedules
+ * @param options - The list options
+ * @param options.page - The page number
+ * @param options.perPage - The number of schedules per page
+ * @returns The list of schedules
+ */
+declare function list$1(options?: ListScheduleOptions, requestOptions?: ApiRequestOptions): OffsetLimitPagePromise<typeof ScheduleObject>;
+/**
+ * Lists the possible timezones we support
+ * @param excludeUtc - By default "UTC" is included and is first. If true, "UTC" will be excluded.
+ */
+declare function timezones(options?: {
+    excludeUtc?: boolean;
+}): ApiPromise<{
+    timezones: string[];
+}>;
 
-declare function onThrow<T>(fn: (options: {
-    attempt: number;
-    maxAttempts: number;
-}) => Promise<T>, options: RetryOptions): Promise<T>;
-interface RetryFetchRequestInit extends RequestInit {
-    retry?: FetchRetryOptions;
-    timeoutInMs?: number;
+type index_ScheduleOptions<TIdentifier extends string, TOutput, TInitOutput extends InitOutput> = ScheduleOptions<TIdentifier, TOutput, TInitOutput>;
+declare const index_activate: typeof activate;
+declare const index_deactivate: typeof deactivate;
+declare const index_task: typeof task;
+declare const index_timezones: typeof timezones;
+declare namespace index {
+  export { type index_ScheduleOptions as ScheduleOptions, index_activate as activate, create$1 as create, index_deactivate as deactivate, del$1 as del, list$1 as list, retrieve$1 as retrieve, index_task as task, index_timezones as timezones, update$1 as update };
 }
-declare function retryFetch(input: RequestInfo | URL, init?: RetryFetchRequestInit | undefined): Promise<Response>;
-declare const retry: {
-    onThrow: typeof onThrow;
-    fetch: typeof retryFetch;
-    interceptFetch: (...handlers: Array<HttpHandler>) => {
-        run: <T>(fn: (...args: any[]) => Promise<T>) => Promise<T>;
-    };
-};
 
-export { type CacheEntry, type CacheFunction, type CacheMetadata, type CacheStore, type Context, type Eventually, InMemoryCache, type WaitOptions, createCache, retry, task, wait };
+declare function upload(projectRef: string, slug: string, params: ImportEnvironmentVariablesParams, requestOptions?: ApiRequestOptions): ApiPromise<EnvironmentVariableResponseBody>;
+declare function upload(params: ImportEnvironmentVariablesParams, requestOptions?: ApiRequestOptions): ApiPromise<EnvironmentVariableResponseBody>;
+declare function list(projectRef: string, slug: string, requestOptions?: ApiRequestOptions): ApiPromise<EnvironmentVariables>;
+declare function list(requestOptions?: ApiRequestOptions): ApiPromise<EnvironmentVariables>;
+declare function create(projectRef: string, slug: string, params: CreateEnvironmentVariableParams, requestOptions?: ApiRequestOptions): ApiPromise<EnvironmentVariableResponseBody>;
+declare function create(params: CreateEnvironmentVariableParams, requestOptions?: ApiRequestOptions): ApiPromise<EnvironmentVariableResponseBody>;
+declare function retrieve(projectRef: string, slug: string, name: string, requestOptions?: ApiRequestOptions): ApiPromise<EnvironmentVariableValue>;
+declare function retrieve(name: string, requestOptions?: ApiRequestOptions): ApiPromise<EnvironmentVariableValue>;
+declare function del(projectRef: string, slug: string, name: string, requestOptions?: ApiRequestOptions): ApiPromise<EnvironmentVariableResponseBody>;
+declare function del(name: string, requestOptions?: ApiRequestOptions): ApiPromise<EnvironmentVariableResponseBody>;
+declare function update(projectRef: string, slug: string, name: string, params: UpdateEnvironmentVariableParams, requestOptions?: ApiRequestOptions): ApiPromise<EnvironmentVariableResponseBody>;
+declare function update(name: string, params: UpdateEnvironmentVariableParams, requestOptions?: ApiRequestOptions): ApiPromise<EnvironmentVariableResponseBody>;
+
+declare const envvars_CreateEnvironmentVariableParams: typeof CreateEnvironmentVariableParams;
+declare const envvars_ImportEnvironmentVariablesParams: typeof ImportEnvironmentVariablesParams;
+declare const envvars_create: typeof create;
+declare const envvars_del: typeof del;
+declare const envvars_list: typeof list;
+declare const envvars_retrieve: typeof retrieve;
+declare const envvars_update: typeof update;
+declare const envvars_upload: typeof upload;
+declare namespace envvars {
+  export { envvars_CreateEnvironmentVariableParams as CreateEnvironmentVariableParams, envvars_ImportEnvironmentVariablesParams as ImportEnvironmentVariablesParams, envvars_create as create, envvars_del as del, envvars_list as list, envvars_retrieve as retrieve, envvars_update as update, envvars_upload as upload };
+}
+
+/**
+ * Register the global API client configuration. Alternatively, you can set the `TRIGGER_SECRET_KEY` and `TRIGGER_API_URL` environment variables.
+ * @param options The API client configuration.
+ * @param options.baseURL The base URL of the Trigger API. (default: `https://api.trigger.dev`)
+ * @param options.secretKey The secret key to authenticate with the Trigger API. (default: `process.env.TRIGGER_SECRET_KEY`) This can be found in your Trigger.dev project "API Keys" settings.
+ *
+ * @example
+ *
+ * ```typescript
+ * import { configure } from "@trigger.dev/sdk/v3";
+ *
+ * configure({
+ *  baseURL: "https://api.trigger.dev",
+ *  secretKey: "tr_dev_1234567890"
+ * });
+ * ```
+ */
+declare function configure(options: ApiClientConfiguration): void;
+
+export { type BatchItem, type BatchResult, type BatchRunHandle, type CacheEntry, type CacheFunction, type CacheMetadata, type CacheStore, type ComputeUsage, type Context, type CurrentUsage, type Eventually, type IdempotencyKey, InMemoryCache, type Queue, type RunHandle, type Task, type TaskIdentifier, type TaskOptions, type TaskOutput, type TaskPayload, type TaskRunOptions, type TaskRunResult, type WaitOptions, configure, createCache, envvars, idempotencyKeys, isIdempotencyKey, queue, retry, runs, index as schedules, task$1 as task, tasks, usage, wait };