@trigger.dev/sdk 3.0.0-beta.3 → 3.0.0-beta.30

package/dist/v3/index.d.mts

@@ -1,7 +1,53 @@
-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, TaskRunContext, QueueOptions, InitOutput, MachineCpu, MachineMemory, RunFnParams, InitFnParams, HandleErrorFnParams, HandleErrorResult, MiddlewareFnParams, StartFnParams, SuccessFnParams, FailureFnParams, RetrieveRunResponse, ReplayRunResponse, CanceledRunResponse, ScheduledTaskPayload, CreateScheduleOptions, ScheduleObject, UpdateScheduleOptions, DeletedScheduleObject, ListScheduleOptions, ListSchedulesResult, ApiClientConfiguration } from '@trigger.dev/core/v3';
+export { APIError, ApiClientConfiguration, AuthenticationError, BadRequestError, ConflictError, HandleErrorArgs, HandleErrorFunction, InternalServerError, LogLevel, NotFoundError, PermissionDeniedError, RateLimitError, 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 Context = TaskRunContext;
 type RequireOne<T, K extends keyof T> = {
     [X in Exclude<keyof T, K>]?: T[X];
@@ -9,7 +55,10 @@ 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<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;
     /** The retry settings when an uncaught error is thrown.
@@ -99,11 +148,48 @@ 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;
@@ -119,36 +205,79 @@ 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<TInput = void, TOutput = any> {
+    /**
+     * The id of the task.
+     */
+    id: string;
+    /**
+     * 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 InvokeHandle
+     * - `id` - The id of the triggered task run.
+     */
+    trigger: (payload: TInput, options?: TaskRunOptions) => Promise<InvokeHandle>;
+    /**
+     * 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<InvokeBatchHandle>;
+    /**
+     * 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 TaskRunOptions = {
     idempotencyKey?: string;
     maxAttempts?: number;
@@ -158,9 +287,6 @@ type TaskRunOptions = {
     concurrencyKey?: string;
 };
 type TaskRunConcurrencyOptions = Queue;
-type BatchRunOptions = TaskRunOptions & {
-    maxConcurrency?: number;
-};
 
 /** Creates a task that can be triggered
  * @param options - Task options
@@ -180,7 +306,7 @@ 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<TInput = void, TOutput = unknown, TInitOutput extends InitOutput = any>(options: TaskOptions<TInput, TOutput, TInitOutput>): Task<TInput, TOutput>;
 
 type WaitOptions = {
     seconds: number;
@@ -205,50 +331,95 @@ declare const wait: {
     }) => Promise<void>;
 };
 
-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>;
+declare const runs: {
+    replay: typeof replayRun;
+    cancel: typeof cancelRun;
+    retrieve: typeof retrieveRun;
 };
-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;
-}
+declare function retrieveRun(runId: string): Promise<RetrieveRunResponse>;
+declare function replayRun(runId: string): Promise<ReplayRunResponse>;
+declare function cancelRun(runId: string): Promise<CanceledRunResponse>;
+
+declare function task<TOutput, TInitOutput extends InitOutput>(params: TaskOptions<ScheduledTaskPayload, TOutput, TInitOutput>): Task<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.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(options: CreateScheduleOptions): Promise<ScheduleObject>;
+/**
+ * Retrieves a schedule
+ * @param scheduleId - The ID of the schedule to retrieve
+ * @returns The retrieved schedule
+ */
+declare function retrieve(scheduleId: string): Promise<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.externalId - An optional external identifier for the schedule
+ * @returns The updated schedule
+ */
+declare function update(scheduleId: string, options: UpdateScheduleOptions): Promise<ScheduleObject>;
+/**
+ * Deletes a schedule
+ * @param scheduleId - The ID of the schedule to delete
+ */
+declare function del(scheduleId: string): Promise<DeletedScheduleObject>;
+/**
+ * Deactivates a schedule
+ * @param scheduleId - The ID of the schedule to deactivate
+ */
+declare function deactivate(scheduleId: string): Promise<ScheduleObject>;
+/**
+ * Activates a schedule
+ * @param scheduleId - The ID of the schedule to activate
+ */
+declare function activate(scheduleId: string): Promise<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(options?: ListScheduleOptions): Promise<ListSchedulesResult>;
 
-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 const index_activate: typeof activate;
+declare const index_create: typeof create;
+declare const index_deactivate: typeof deactivate;
+declare const index_del: typeof del;
+declare const index_list: typeof list;
+declare const index_retrieve: typeof retrieve;
+declare const index_task: typeof task;
+declare const index_update: typeof update;
+declare namespace index {
+  export { index_activate as activate, index_create as create, index_deactivate as deactivate, index_del as del, index_list as list, index_retrieve as retrieve, index_task as task, index_update 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 };
+/**
+ * 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 CacheEntry, type CacheFunction, type CacheMetadata, type CacheStore, type Context, type Eventually, InMemoryCache, type Task, type TaskOptions, type WaitOptions, configure, createCache, queue, retry, runs, index as schedules, task$1 as task, wait };