@trigger.dev/sdk 2.0.0-next.5 → 2.0.0-next.7

package/dist/index.d.ts

@@ -1,11 +1,20 @@
 import * as zod from 'zod';
 import { z } from 'zod';
 
+/**
+ * Represents different log levels.
+ * - `"log"`: Only essential messages.
+ * - `"error"`: Errors and essential messages.
+ * - `"warn"`: Warnings, Errors and essential messages.
+ * - `"info"`: Info, Warnings, Errors and essential messages.
+ * - `"debug"`: Everything.
+ */
 type LogLevel = "log" | "error" | "warn" | "info" | "debug";
 declare class Logger {
     #private;
     constructor(name: string, level?: LogLevel, filteredKeys?: string[], jsonReplacer?: (key: string, value: unknown) => unknown);
     filter(...keys: string[]): Logger;
+    static satisfiesLogLevel(logLevel: LogLevel, setLevel: LogLevel): boolean;
     log(...args: any[]): void;
     error(...args: any[]): void;
     warn(...args: any[]): void;
@@ -733,17 +742,34 @@ declare const JobMetadataSchema: z.ZodObject<{
 }>;
 type JobMetadata = z.infer<typeof JobMetadataSchema>;
 declare const RawEventSchema: z.ZodObject<{
-    id: z.ZodDefault<z.ZodString>;
+    /** The `name` property must exactly match any subscriptions you want to
+        trigger. */
     name: z.ZodString;
-    source: z.ZodOptional<z.ZodString>;
+    /** The `payload` property will be sent to any matching Jobs and will appear
+        as the `payload` param of the `run()` function. You can leave this
+        parameter out if you just want to trigger a Job without any input data. */
     payload: z.ZodAny;
+    /** The optional `context` property will be sent to any matching Jobs and will
+        be passed through as the `context.event.context` param of the `run()`
+        function. This is optional but can be useful if you want to pass through
+        some additional context to the Job. */
     context: z.ZodOptional<z.ZodAny>;
-    timestamp: z.ZodOptional<z.ZodString>;
+    /** The `id` property uniquely identify this particular event. If unset it
+        will be set automatically using `ulid`. */
+    id: z.ZodDefault<z.ZodString>;
+    /** This is optional, it defaults to the current timestamp. Usually you would
+        only set this if you have a timestamp that you wish to pass through, e.g.
+        you receive a timestamp from a service and you want the same timestamp to
+        be used in your Job. */
+    timestamp: z.ZodOptional<z.ZodDate>;
+    /** This is optional, it defaults to "trigger.dev". It can be useful to set
+        this as you can filter events using this in the `eventTrigger()`. */
+    source: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     source?: string | undefined;
     payload?: any;
     context?: any;
-    timestamp?: string | undefined;
+    timestamp?: Date | undefined;
     id: string;
     name: string;
 }, {
@@ -751,20 +777,30 @@ declare const RawEventSchema: z.ZodObject<{
     source?: string | undefined;
     payload?: any;
     context?: any;
-    timestamp?: string | undefined;
+    timestamp?: Date | undefined;
     name: string;
 }>;
+/** The event you wish to send to Trigger a Job */
 type SendEvent = z.input<typeof RawEventSchema>;
+/** Options to control the delivery of the event */
 declare const SendEventOptionsSchema: z.ZodObject<{
-    deliverAt: z.ZodOptional<z.ZodString>;
+    /** An optional Date when you want the event to trigger Jobs. The event will
+        be sent to the platform immediately but won't be acted upon until the
+        specified time. */
+    deliverAt: z.ZodOptional<z.ZodDate>;
+    /** An optional number of seconds you want to wait for the event to trigger
+        any relevant Jobs. The event will be sent to the platform immediately but
+        won't be delivered until after the elapsed number of seconds. */
     deliverAfter: z.ZodOptional<z.ZodNumber>;
+    /** This optional param will be used by Trigger.dev Connect, which
+        is coming soon. */
     accountId: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
-    deliverAt?: string | undefined;
+    deliverAt?: Date | undefined;
     deliverAfter?: number | undefined;
     accountId?: string | undefined;
 }, {
-    deliverAt?: string | undefined;
+    deliverAt?: Date | undefined;
     deliverAfter?: number | undefined;
     accountId?: string | undefined;
 }>;
@@ -1192,12 +1228,24 @@ declare const CreateRunBodySchema: z.ZodObject<{
         preprocessRuns: boolean;
     }>;
     event: z.ZodObject<{
+        /** The `id` of the event that was sent.
+         */
         id: z.ZodString;
+        /** The `name` of the event that was sent. */
         name: z.ZodString;
+        /** The `payload` of the event that was sent */
         payload: z.ZodType<DeserializedJson, z.ZodTypeDef, DeserializedJson>;
+        /** The `context` of the event that was sent. Is `undefined` if no context was
+            set when sending the event. */
         context: z.ZodNullable<z.ZodOptional<z.ZodType<DeserializedJson, z.ZodTypeDef, DeserializedJson>>>;
+        /** The `timestamp` of the event that was sent */
         timestamp: z.ZodDate;
+        /** The timestamp when the event will be delivered to any matching Jobs. Is
+            `undefined` if `deliverAt` or `deliverAfter` wasn't set when sending the
+            event. */
         deliverAt: z.ZodNullable<z.ZodOptional<z.ZodDate>>;
+        /** The timestamp when the event was delivered. Is `undefined` if `deliverAt`
+            or `deliverAfter` were set when sending the event. */
         deliveredAt: z.ZodNullable<z.ZodOptional<z.ZodDate>>;
     }, "strip", z.ZodTypeAny, {
         context?: DeserializedJson | undefined;
@@ -1614,10 +1662,15 @@ declare const RunTaskOptionsSchema: z.ZodObject<{
         style: "normal" | "minimal";
     }>>;
     retry: z.ZodOptional<z.ZodObject<{
+        /** The maximum number of times to retry the request. */
         limit: z.ZodOptional<z.ZodNumber>;
+        /** The exponential factor to use when calculating the next retry time. */
         factor: z.ZodOptional<z.ZodNumber>;
+        /** The minimum amount of time to wait before retrying the request. */
         minTimeoutInMs: z.ZodOptional<z.ZodNumber>;
+        /** The maximum amount of time to wait before retrying the request. */
         maxTimeoutInMs: z.ZodOptional<z.ZodNumber>;
+        /** Whether to randomize the retry time. */
         randomize: z.ZodOptional<z.ZodBoolean>;
     }, "strip", z.ZodTypeAny, {
         limit?: number | undefined;
@@ -1946,10 +1999,15 @@ declare const RunTaskBodyInputSchema: z.ZodObject<z.extendShape<{
         style: "normal" | "minimal";
     }>>;
     retry: z.ZodOptional<z.ZodObject<{
+        /** The maximum number of times to retry the request. */
         limit: z.ZodOptional<z.ZodNumber>;
+        /** The exponential factor to use when calculating the next retry time. */
         factor: z.ZodOptional<z.ZodNumber>;
+        /** The minimum amount of time to wait before retrying the request. */
         minTimeoutInMs: z.ZodOptional<z.ZodNumber>;
+        /** The maximum amount of time to wait before retrying the request. */
         maxTimeoutInMs: z.ZodOptional<z.ZodNumber>;
+        /** Whether to randomize the retry time. */
         randomize: z.ZodOptional<z.ZodBoolean>;
     }, "strip", z.ZodTypeAny, {
         limit?: number | undefined;
@@ -2285,10 +2343,15 @@ declare const CompleteTaskBodyInputSchema: z.ZodObject<z.extendShape<Pick<z.exte
         style: "normal" | "minimal";
     }>>;
     retry: z.ZodOptional<z.ZodObject<{
+        /** The maximum number of times to retry the request. */
         limit: z.ZodOptional<z.ZodNumber>;
+        /** The exponential factor to use when calculating the next retry time. */
         factor: z.ZodOptional<z.ZodNumber>;
+        /** The minimum amount of time to wait before retrying the request. */
         minTimeoutInMs: z.ZodOptional<z.ZodNumber>;
+        /** The maximum amount of time to wait before retrying the request. */
         maxTimeoutInMs: z.ZodOptional<z.ZodNumber>;
+        /** Whether to randomize the retry time. */
         randomize: z.ZodOptional<z.ZodBoolean>;
     }, "strip", z.ZodTypeAny, {
         limit?: number | undefined;
@@ -3089,8 +3152,11 @@ declare const MissingConnectionResolvedNotificationPayloadSchema: z.ZodDiscrimin
 }>]>;
 type MissingConnectionResolvedNotificationPayload = z.infer<typeof MissingConnectionResolvedNotificationPayloadSchema>;
 
+/** The options for a fetch request */
 declare const FetchRequestInitSchema: z.ZodObject<{
+    /** The HTTP method to use for the request. */
     method: z.ZodOptional<z.ZodString>;
+    /** Any headers to send with the request. Note that you can use [redactString](https://trigger.dev/docs/sdk/redactString) to prevent sensitive information from being stored (e.g. in the logs), like API keys and tokens. */
     headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodObject<{
         __redactedString: z.ZodLiteral<true>;
         strings: z.ZodArray<z.ZodString, "many">;
@@ -3104,6 +3170,7 @@ declare const FetchRequestInitSchema: z.ZodObject<{
         strings: string[];
         interpolations: string[];
     }>]>>>;
+    /** The body of the request. */
     body: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodType<ArrayBuffer, z.ZodTypeDef, ArrayBuffer>]>>;
 }, "strip", z.ZodTypeAny, {
     method?: string | undefined;
@@ -3122,11 +3189,16 @@ declare const FetchRequestInitSchema: z.ZodObject<{
     }> | undefined;
     body?: string | ArrayBuffer | undefined;
 }>;
+/** The options for a fetch request */
 type FetchRequestInit = z.infer<typeof FetchRequestInitSchema>;
 declare const FetchRetryOptionsSchema: z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<"strategy", [z.ZodObject<{
+    /** The `headers` strategy retries the request using info from the response headers. */
     strategy: z.ZodLiteral<"headers">;
+    /** The header to use to determine the maximum number of times to retry the request. */
     limitHeader: z.ZodString;
+    /** The header to use to determine the number of remaining retries. */
     remainingHeader: z.ZodString;
+    /** The header to use to determine the time when the number of remaining retries will be reset. */
     resetHeader: z.ZodString;
 }, "strip", z.ZodTypeAny, {
     strategy: "headers";
@@ -3145,6 +3217,7 @@ declare const FetchRetryOptionsSchema: z.ZodRecord<z.ZodString, z.ZodDiscriminat
     maxTimeoutInMs: z.ZodOptional<z.ZodNumber>;
     randomize: z.ZodOptional<z.ZodBoolean>;
 }, {
+    /** The `backoff` strategy retries the request with an exponential backoff. */
     strategy: z.ZodLiteral<"backoff">;
 }>, "strip", z.ZodTypeAny, {
     limit?: number | undefined;
@@ -3161,8 +3234,17 @@ declare const FetchRetryOptionsSchema: z.ZodRecord<z.ZodString, z.ZodDiscriminat
     randomize?: boolean | undefined;
     strategy: "backoff";
 }>]>>;
+/** An object where the key is a status code pattern and the value is a retrying strategy. Supported patterns are:
+  - Specific status codes: 429
+  - Ranges: 500-599
+  - Wildcards: 2xx, 3xx, 4xx, 5xx
+  */
 type FetchRetryOptions = z.infer<typeof FetchRetryOptionsSchema>;
 
+type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+
 type ApiClientOptions = {
     apiKey?: string;
     apiUrl?: string;
@@ -3491,7 +3573,7 @@ declare class ExternalSource<TIntegration extends TriggerIntegration<Integration
             source?: string | undefined;
             payload?: any;
             context?: any;
-            timestamp?: string | undefined;
+            timestamp?: Date | undefined;
             name: string;
         }[];
         response?: {
@@ -3558,15 +3640,29 @@ declare class DynamicTrigger<TEventSpec extends EventSpecification<any>, TExtern
 }
 
 type TriggerClientOptions = {
+    /** The `id` property is used to uniquely identify the client.
+     */
     id: string;
+    /** The `apiKey` property is the API Key for your Trigger.dev environment. We
+        recommend using an environment variable to store your API Key. */
     apiKey?: string;
+    /** The `apiUrl` property is an optional property that specifies the API URL. You
+        only need to specify this if you are not using Trigger.dev Cloud and are
+        running your own Trigger.dev instance. */
     apiUrl?: string;
+    /** The `logLevel` property is an optional property that specifies the level of
+        logging for the TriggerClient. The level is inherited by all Jobs that use this Client, unless they also specify a `logLevel`. */
     logLevel?: LogLevel;
+    /** Very verbose log messages, defaults to false. */
+    verbose?: boolean;
+    /** Default is unset and off. If set to true it will log to the server's console as well as the Trigger.dev platform */
+    ioLogLocalEnabled?: boolean;
 };
+/** A [TriggerClient](https://trigger.dev/docs/documentation/concepts/client-adaptors) is used to connect to a specific [Project](https://trigger.dev/docs/documentation/concepts/projects) by using an [API Key](https://trigger.dev/docs/documentation/concepts/environments-apikeys). */
 declare class TriggerClient {
     #private;
     id: string;
-    constructor(options: TriggerClientOptions);
+    constructor(options: Prettify<TriggerClientOptions>);
     handleRequest(request: Request): Promise<NormalizedResponse>;
     attach(job: Job<Trigger<any>, any>): void;
     attachDynamicTrigger(trigger: DynamicTrigger<any, any>): void;
@@ -3607,6 +3703,8 @@ declare class TriggerClient {
         type: "oauth2";
         accessToken: string;
     } | undefined>;
+    /** You can call this function from anywhere in your code to send an event. The other way to send an event is by using `io.sendEvent()` from inside a `run()` function.
+     */
     sendEvent(event: SendEvent, options?: SendEventOptions): Promise<{
         context?: DeserializedJson | undefined;
         deliverAt?: Date | null | undefined;
@@ -3765,6 +3863,8 @@ type IOOptions = {
     context: TriggerContext;
     logger?: Logger;
     logLevel?: LogLevel;
+    jobLogger?: Logger;
+    jobLogLevel: LogLevel;
     cachedTasks?: Array<CachedTask>;
 };
 declare class IO {
@@ -3773,13 +3873,36 @@ declare class IO {
     private _apiClient;
     private _triggerClient;
     private _logger;
+    private _jobLogger?;
+    private _jobLogLevel;
     private _cachedTasks;
     private _taskStorage;
     private _context;
     constructor(options: IOOptions);
+    /** Used to send log messages to the [Run log](https://trigger.dev/docs/documentation/guides/viewing-runs). */
     get logger(): IOLogger;
+    /** `io.wait()` waits for the specified amount of time before continuing the Job. Delays work even if you're on a serverless platform with timeouts, or if your server goes down. They utilize [resumability](https://trigger.dev/docs/documentation/concepts/resumability) to ensure that the Run can be resumed after the delay.
+     * @param key Should be a stable and unique key inside the `run()`. See [resumability](https://trigger.dev/docs/documentation/concepts/resumability) for more information.
+     * @param seconds The number of seconds to wait. This can be very long, serverless timeouts are not an issue.
+     */
     wait(key: string | any[], seconds: number): Promise<void>;
+    /** `io.backgroundFetch()` fetches data from a URL that can take longer that the serverless timeout. The actual `fetch` request is performed on the Trigger.dev platform, and the response is sent back to you.
+     * @param key Should be a stable and unique key inside the `run()`. See [resumability](https://trigger.dev/docs/documentation/concepts/resumability) for more information.
+     * @param url The URL to fetch from.
+     * @param requestInit The options for the request
+     * @param retry The options for retrying the request if it fails
+     * An object where the key is a status code pattern and the value is a retrying strategy.
+     * Supported patterns are:
+     * - Specific status codes: 429
+     * - Ranges: 500-599
+     * - Wildcards: 2xx, 3xx, 4xx, 5xx
+     */
     backgroundFetch<TResponseData>(key: string | any[], url: string, requestInit?: FetchRequestInit, retry?: FetchRetryOptions): Promise<TResponseData>;
+    /** `io.sendEvent()` allows you to send an event from inside a Job run. The sent even will trigger any Jobs that are listening for that event (based on the name).
+     * @param key Should be a stable and unique key inside the `run()`. See [resumability](https://trigger.dev/docs/documentation/concepts/resumability) for more information.
+     * @param event The event to send. The event name must match the name of the event that your Jobs are listening for.
+     * @param options Options for sending the event.
+     */
     sendEvent(key: string | any[], event: SendEvent, options?: SendEventOptions): Promise<{
         context?: DeserializedJson | undefined;
         deliverAt?: Date | null | undefined;
@@ -3849,13 +3972,19 @@ declare class IO {
     } | undefined | void): Promise<TResult>;
     try<TResult, TCatchResult>(tryCallback: () => Promise<TResult>, catchCallback: (error: unknown) => Promise<TCatchResult>): Promise<TResult | TCatchResult>;
 }
-type CallbackFunction = (level: "DEBUG" | "INFO" | "WARN" | "ERROR", message: string, properties?: Record<string, any>) => Promise<void>;
+type CallbackFunction = (level: "DEBUG" | "INFO" | "WARN" | "ERROR" | "LOG", message: string, properties?: Record<string, any>) => Promise<void>;
 declare class IOLogger implements TaskLogger {
     private callback;
     constructor(callback: CallbackFunction);
+    /** Log: essential messages */
+    log(message: string, properties?: Record<string, any>): Promise<void>;
+    /** For debugging: the least important log level */
     debug(message: string, properties?: Record<string, any>): Promise<void>;
+    /** Info: the second least important log level */
     info(message: string, properties?: Record<string, any>): Promise<void>;
+    /** Warnings: the third most important log level  */
     warn(message: string, properties?: Record<string, any>): Promise<void>;
+    /** Error: The second most important log level */
     error(message: string, properties?: Record<string, any>): Promise<void>;
 }
 
@@ -3909,28 +4038,69 @@ type ExtractIntegrations<TIntegrations extends Record<string, TriggerIntegration
 type IOWithIntegrations<TIntegrations extends Record<string, TriggerIntegration<IntegrationClient<any, any>>>> = IO & ExtractIntegrations<TIntegrations>;
 
 type JobOptions<TTrigger extends Trigger<EventSpecification<any>>, TIntegrations extends Record<string, TriggerIntegration<IntegrationClient<any, any>>> = {}> = {
+    /** The `id` property is used to uniquely identify the Job. Only change this if you want to create a new Job. */
     id: string;
+    /** The `name` of the Job that you want to appear in the dashboard and logs. You can change this without creating a new Job. */
     name: string;
+    /** The `version` property is used to version your Job. A new version will be created if you change this property. We recommend using [semantic versioning](https://www.baeldung.com/cs/semantic-versioning), e.g. `1.0.3`. */
     version: string;
+    /** The `trigger` property is used to define when the Job should run. There are currently the following Trigger types:
+        - [cronTrigger](https://trigger.dev/docs/sdk/crontrigger)
+        - [intervalTrigger](https://trigger.dev/docs/sdk/intervaltrigger)
+        - [eventTrigger](https://trigger.dev/docs/sdk/eventtrigger)
+        - [DynamicTrigger](https://trigger.dev/docs/sdk/dynamictrigger)
+        - [DynamicSchedule](https://trigger.dev/docs/sdk/dynamicschedule)
+        - integration Triggers, like webhooks. See the [integrations](https://trigger.dev/docs/integrations) page for more information. */
     trigger: TTrigger;
+    /** The `logLevel` property is an optional property that specifies the level of
+        logging for the Job. The level is inherited from the client if you omit this property. */
     logLevel?: LogLevel;
+    /** Imports the specified integrations into the Job. The integrations will be available on the `io` object in the `run()` function with the same name as the key. For example:
+        ```ts
+        new Job(client, {
+          //... other options
+          integrations: {
+            slack,
+            gh: github,
+          },
+          run: async (payload, io, ctx) => {
+            //slack is available on io.slack
+            io.slack.postMessage(...);
+            //github is available on io.gh
+            io.gh.addIssueLabels(...);
+          }
+        });
+        ``` */
     integrations?: TIntegrations;
+    /** The `queue` property is used to specify a custom queue. If you use an Object and specify the `maxConcurrent` option, you can control how many simulataneous runs can happen. */
     queue?: QueueOptions | string;
     startPosition?: "initial" | "latest";
+    /** The `enabled` property is used to enable or disable the Job. If you disable a Job, it will not run. */
     enabled?: boolean;
-    run: (event: TriggerEventType<TTrigger>, io: IOWithIntegrations<TIntegrations>, ctx: TriggerContext) => Promise<any>;
+    /** This function gets called automatically when a Run is Triggered.
+     * This is where you put the code you want to run for a Job. You can use normal code in here and you can also use Tasks. You can return a value from this function and it will be sent back to the Trigger API.
+     * @param payload The payload of the event
+     * @param io An object that contains the integrations that you specified in the `integrations` property and other useful functions like delays and running Tasks.
+     * @param context An object that contains information about the Organization, Job, Run and more.
+     */
+    run: (payload: TriggerEventType<TTrigger>, io: IOWithIntegrations<TIntegrations>, context: TriggerContext) => Promise<any>;
 };
+/** A [Job](https://trigger.dev/docs/documentation/concepts/jobs) is used to define the [Trigger](https://trigger.dev/docs/documentation/concepts/triggers), metadata, and what happens when it runs. */
 declare class Job<TTrigger extends Trigger<EventSpecification<any>>, TIntegrations extends Record<string, TriggerIntegration<IntegrationClient<any, any>>> = {}> {
     #private;
     readonly options: JobOptions<TTrigger, TIntegrations>;
     client: TriggerClient;
-    constructor(client: TriggerClient, options: JobOptions<TTrigger, TIntegrations>);
+    constructor(
+    /** An instance of [TriggerClient](/sdk/triggerclient) that is used to send events
+  to the Trigger API. */
+    client: TriggerClient, options: JobOptions<TTrigger, TIntegrations>);
     get id(): string;
     get enabled(): boolean;
     get name(): string;
     get trigger(): TTrigger;
     get version(): string;
     get integrations(): Record<string, IntegrationConfig>;
+    get logLevel(): LogLevel | undefined;
     toJSON(): JobMetadata;
 }