@trigger.dev/sdk 3.0.0-beta.4 → 3.0.0-beta.40

package/dist/v3/index.d.ts

@@ -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, ListProjectRunsQueryParams, CursorPagePromise, ListRunResponseItem, ListRunsQueryParams, ApiPromise, ReplayRunResponse, CanceledRunResponse, RetrieveRunResponse, ScheduledTaskPayload, CreateScheduleOptions, ScheduleObject, UpdateScheduleOptions, DeletedScheduleObject, ListScheduleOptions, OffsetLimitPagePromise, ImportEnvironmentVariablesParams, EnvironmentVariableResponseBody, EnvironmentVariables, CreateEnvironmentVariableParams, EnvironmentVariableValue, UpdateEnvironmentVariableParams, ApiClientConfiguration } from '@trigger.dev/core/v3';
+export { 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 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.
@@ -79,6 +128,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 +140,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,11 +152,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 +209,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 +291,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 +310,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 +335,209 @@ 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 RetrieveRunResult = RetrieveRunResponse;
+declare const runs: {
+    replay: typeof replayRun;
+    cancel: typeof cancelRun;
+    retrieve: typeof retrieveRun;
+    list: typeof listRuns;
+};
+declare function listRuns(projectRef: string, params?: ListProjectRunsQueryParams): CursorPagePromise<typeof ListRunResponseItem>;
+declare function listRuns(params?: ListRunsQueryParams): CursorPagePromise<typeof ListRunResponseItem>;
+declare function retrieveRun(runId: string): ApiPromise<RetrieveRunResult>;
+declare function replayRun(runId: string): ApiPromise<ReplayRunResponse>;
+declare function cancelRun(runId: string): ApiPromise<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.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): ApiPromise<ScheduleObject>;
+/**
+ * Retrieves a schedule
+ * @param scheduleId - The ID of the schedule to retrieve
+ * @returns The retrieved schedule
+ */
+declare function retrieve$1(scheduleId: string): 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): ApiPromise<ScheduleObject>;
+/**
+ * Deletes a schedule
+ * @param scheduleId - The ID of the schedule to delete
+ */
+declare function del$1(scheduleId: string): ApiPromise<DeletedScheduleObject>;
+/**
+ * Deactivates a schedule
+ * @param scheduleId - The ID of the schedule to deactivate
+ */
+declare function deactivate(scheduleId: string): ApiPromise<ScheduleObject>;
+/**
+ * Activates a schedule
+ * @param scheduleId - The ID of the schedule to activate
+ */
+declare function activate(scheduleId: string): 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): 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;
+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 { 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): ApiPromise<EnvironmentVariableResponseBody>;
+declare function upload(params: ImportEnvironmentVariablesParams): ApiPromise<EnvironmentVariableResponseBody>;
+declare function list(projectRef: string, slug: string): ApiPromise<EnvironmentVariables>;
+declare function list(): ApiPromise<EnvironmentVariables>;
+declare function create(projectRef: string, slug: string, params: CreateEnvironmentVariableParams): ApiPromise<EnvironmentVariableResponseBody>;
+declare function create(params: CreateEnvironmentVariableParams): ApiPromise<EnvironmentVariableResponseBody>;
+declare function retrieve(projectRef: string, slug: string, name: string): ApiPromise<EnvironmentVariableValue>;
+declare function retrieve(name: string): ApiPromise<EnvironmentVariableValue>;
+declare function del(projectRef: string, slug: string, name: string): ApiPromise<EnvironmentVariableResponseBody>;
+declare function del(name: string): ApiPromise<EnvironmentVariableResponseBody>;
+declare function update(projectRef: string, slug: string, name: string, params: UpdateEnvironmentVariableParams): ApiPromise<EnvironmentVariableResponseBody>;
+declare function update(name: string, params: UpdateEnvironmentVariableParams): 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 CacheEntry, type CacheFunction, type CacheMetadata, type CacheStore, type ComputeUsage, type Context, type CurrentUsage, type Eventually, InMemoryCache, type Task, type TaskOptions, type WaitOptions, configure, createCache, envvars, queue, retry, runs, index as schedules, task$1 as task, usage, wait };