io.runTask and io.registerTrigger jsdocs

.changeset/healthy-rockets-cry.md

@@ -0,0 +1,5 @@
+---
+"@trigger.dev/sdk": patch
+---
+
+io.runTask jsdocs

.changeset/quiet-dryers-collect.md

@@ -0,0 +1,5 @@
+---
+"@trigger.dev/sdk": patch
+---
+
+registerTrigger jsdocs

examples/nextjs-example/src/jobs/general.ts

@@ -603,3 +603,51 @@ new Job(client, {
     return response;
   },
 });
+
+//1. create a DynamicTrigger
+const dynamicOnIssueaOpenedTrigger = new DynamicTrigger(client, {
+  id: "github-issue-opened",
+  event: events.onIssueOpened,
+  source: github.sources.repo,
+});
+
+//2. create a Job that is attached to the dynamic trigger
+new Job(client, {
+  id: "listen-for-dynamic-trigger",
+  name: "Listen for dynamic trigger",
+  version: "0.1.1",
+  trigger: dynamicOnIssueOpenedTrigger,
+  integrations: {
+    slack,
+  },
+  run: async (payload, io, ctx) => {
+    await io.slack.postMessage("Slack 📝", {
+      text: `New Issue opened on repo: ${
+        payload.issue.html_url
+      }. \n\n${JSON.stringify(ctx)}`,
+      channel: "C04GWUTDC3W",
+    });
+  },
+});
+
+new Job(client, {
+  id: "new-repo",
+  name: "New repo",
+  version: "0.1.1",
+  trigger: github.triggers.org({
+    event: events.onNewRepository,
+    org: "triggerdotdev",
+  }),
+  run: async (payload, io, ctx) => {
+    //3. Register the dynamic trigger so you get notified when an issue is opened
+    return await io.registerTrigger(
+      "register-repo",
+      dynamicOnIssueOpenedTrigger,
+      payload.repository.name,
+      {
+        owner: payload.repository.owner.login,
+        repo: payload.repository.name,
+      }
+    );
+  },
+});

packages/internal/src/schemas/api.ts

@@ -462,20 +462,34 @@ export const RetryOptionsSchema = z.object({
 export type RetryOptions = z.infer<typeof RetryOptionsSchema>;
 
 export const RunTaskOptionsSchema = z.object({
+  /** The name of the Task is required. This is displayed on the Task in the logs. */
   name: z.string(),
-  icon: z.string().optional(),
-  displayKey: z.string().optional(),
-  noop: z.boolean().default(false),
-  operation: z.enum(["fetch"]).optional(),
+  /** The Task will wait and only start at the specified Date  */
   delayUntil: z.coerce.date().optional(),
-  description: z.string().optional(),
-  properties: z.array(DisplayPropertySchema).optional(),
-  params: z.any(),
-  trigger: TriggerMetadataSchema.optional(),
-  redact: RedactSchema.optional(),
-  connectionKey: z.string().optional(),
-  style: StyleSchema.optional(),
+  /** Retry options */
   retry: RetryOptionsSchema.optional(),
+  /** The icon for the Task, it will appear in the logs.
+   *  You can use the name of a company in lowercase, e.g. "github".
+   *  Or any icon name that [Font Awesome](https://fontawesome.com/icons) supports. */
+  icon: z.string().optional(),
+  /** The key for the Task that you want to appear in the logs */
+  displayKey: z.string().optional(),
+  /** A description of the Task */
+  description: z.string().optional(),
+  /** Properties that are displayed in the logs */
+  properties: z.array(DisplayPropertySchema).optional(),
+  /** The input params to the Task, will be displayed in the logs  */
+  params: z.any(),
+  /** The style of the log entry. */
+  style: StyleSchema.optional(),
+  /** Allows you to link the Integration connection in the logs. This is handled automatically in integrations.  */
+  connectionKey: z.string().optional(),
+  /** An operation you want to perform on the Trigger.dev platform, current only "fetch" is supported. If you wish to `fetch` use [`io.backgroundFetch()`](https://trigger.dev/docs/sdk/io/backgroundfetch) instead. */
+  operation: z.enum(["fetch"]).optional(),
+  /** A No Operation means that the code won't be executed. This is used internally to implement features like [io.wait()](https://trigger.dev/docs/sdk/io/wait).  */
+  noop: z.boolean().default(false),
+  redact: RedactSchema.optional(),
+  trigger: TriggerMetadataSchema.optional(),
 });
 
 export type RunTaskOptions = z.input<typeof RunTaskOptionsSchema>;

packages/internal/src/schemas/properties.ts

@@ -1,8 +1,12 @@
 import { z } from "zod";
 
+/** A property that is displayed in the logs */
 export const DisplayPropertySchema = z.object({
+  /** The label for the property */
   label: z.string(),
+  /** The value of the property */
   text: z.string(),
+  /** The URL to link to when the property is clicked */
   url: z.string().optional(),
 });
 
@@ -11,7 +15,9 @@ export const DisplayPropertiesSchema = z.array(DisplayPropertySchema);
 export type DisplayProperty = z.infer<typeof DisplayPropertySchema>;
 
 export const StyleSchema = z.object({
+  /** The style, `normal` or `minimal` */
   style: z.enum(["normal", "minimal"]),
+  /** A variant of the style. */
   variant: z.string().optional(),
 });
 

packages/trigger-sdk/src/io.ts

@@ -371,6 +371,12 @@ export class IO {
     );
   }
 
+  /** `io.registerTrigger()` allows you to register a [DynamicTrigger](https://trigger.dev/docs/sdk/dynamictrigger) with the specified trigger params.
+   * @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 trigger The [DynamicTrigger](https://trigger.dev/docs/sdk/dynamictrigger) to register.
+   * @param id A unique id for the trigger. This is used to identify and unregister the trigger later.
+   * @param params The params for the trigger.
+   */
   async registerTrigger<
     TTrigger extends DynamicTrigger<
       EventSpecification<any>,
@@ -452,6 +458,14 @@ export class IO {
     });
   }
 
+  /** `io.runTask()` allows you to run a [Task](https://trigger.dev/docs/documentation/concepts/tasks) from inside a Job run. A Task is a resumable unit of a Run that can be retried, resumed and is logged. [Integrations](https://trigger.dev/docs/integrations) use Tasks internally to perform their actions.
+   *
+   * @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 options The options of how you'd like to run and log the Task. Name is required.
+   * @param callback The callback that will be called when the Task is run. The callback receives the Task and the IO as parameters.
+=   * @param onError The callback that will be called when the Task fails. The callback receives the error, the Task and the IO as parameters. If you wish to retry then return an object with a `retryAt` property.
+   * @returns A Promise that resolves with the returned value of the callback.
+   */
   async runTask<TResult extends SerializableJson | void = void>(
     key: string | any[],
     options: RunTaskOptions,