Re-ordered runTask params in docs, and example Jobs in the app.

Author: matt-aitken

apps/webapp/app/components/integrations/CustomHelp.tsx

@@ -25,16 +25,16 @@ client.defineJob({
     //wrap an SDK call in io.runTask so it's resumable and displays in logs
     const repo = await io.runTask(
       "Get repo",
-      //you can add metadata to the task to improve the display in the logs
-      { name: "Get repo", icon: "github" },
       async () => {
         //this is the regular GitHub SDK
         const response = await octokit.rest.repos.get({
           owner: "triggerdotdev",
           repo: "trigger.dev",
         });
         return response.data;
-      }
+      },
+      //you can add metadata to the task to improve the display in the logs
+      { name: "Get repo", icon: "github" }
     );
   },
 });
@@ -60,13 +60,13 @@ client.defineJob({
     //wrap anything in io.runTask so it's resumable and displays in logs
     const repo = await io.runTask(
       "Get org",
-      //you can add metadata to the task to improve the display in the logs
-      { name: "Get org", icon: "github" },
       async () => {
         //you can use fetch, axios, or any other library to make requests
         const response = await fetch('https://api.github.com/orgs/nodejs');
         return response.json();
-      }
+      },
+      //you can add metadata to the task to improve the display in the logs
+      { name: "Get org", icon: "github" }
     );
   },
 });

apps/webapp/app/services/externalApis/integrations/github.ts

@@ -43,14 +43,14 @@ const usageSample: HelpSample = {
       //wrap the SDK call in runTask
       const { data } = await io.runTask(
         "create-card",
-        { name: "Create card" },
         async () => {
           //create a project card using the underlying client
           return io.github.client.rest.projects.createCard({
             column_id: 123,
             note: "test",
           });
-        }
+        },
+        { name: "Create card" }
       );
   
       //log the url of the created card

docs/documentation/concepts/tasks.mdx

@@ -44,9 +44,13 @@ client.defineJob({
     await io.wait("wait", 60 * 60 * 3); // wait for 3 hours
 
     // You can wrap your own code in a Task, for retrying, resumability and logging
-    const response = await io.runTask("my-task", { name: "My Task" }, async () => {
-      return await longRunningCode(payload.userId);
-    });
+    const response = await io.runTask(
+      "my-task",
+      async () => {
+        return await longRunningCode(payload.userId);
+      },
+      { name: "My Task" }
+    );
 
     return response;
   },

docs/documentation/guides/create-a-job.mdx

@@ -32,10 +32,9 @@ client.defineJob({
 The `id` and `name` are important because they are used to create and identify your Job in the app.
 
 <Note>
-  This Job must be imported in the `trigger` file in order to be registered when
-  the CLI dev command is run. This can be found in either the
-  `app/api/trigger/route.ts` file if you're using the Next.js App Router, or
-  `pages/api/trigger.ts` if you're using the Next.js Pages Router.
+  This Job must be imported in the `trigger` file in order to be registered when the CLI dev command
+  is run. This can be found in either the `app/api/trigger/route.ts` file if you're using the
+  Next.js App Router, or `pages/api/trigger.ts` if you're using the Next.js Pages Router.
 </Note>
 
 ### 2. Choose a Trigger
@@ -112,30 +111,30 @@ This is what kicks-off a Job. There are a few different types of Triggers you ca
 > A Task is a resumable unit of a Run that can be retried, resumed and is logged.
 
 <Info>
-  You can use just regular code in your Jobs. But you don't get the benefits of
-  retrying, logging and resumability. More info on [Tasks vs regular
+  You can use just regular code in your Jobs. But you don't get the benefits of retrying, logging
+  and resumability. More info on [Tasks vs regular
   code](/documentation/concepts/tasks#tasks-vs-regular-code).
 </Info>
 
 You can string together multiple Tasks and regular code in any order you want.
 
 **Useful built-in Tasks:**
 
-| Task                                        | Description                                                             | Task code                                                                                  |
-| ------------------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
-| [Delay](/documentation/concepts/delays)     | Wait for a period of time                                               | `await io.wait("wait", 60);`                                                               |
-| [Log](/sdk/io/logger)                       | Log a message                                                           | `await io.logger.log("Hello");`                                                            |
-| [Send Event](/sdk/io/sendevent)             | Send an event (for eventTrigger)                                        | `await io.sendEvent("my-event", { name: "my.event", payload: { hello: "world" } });`       |
-| [Run task](/sdk/io/runtask)                 | Wrap your own code in this to create a Task                             | `await io.runTask("My Task", { name: "My Task" }, async () => { console.log("Hello"); });` |
-| [Background fetch](/sdk/io/backgroundfetch) | Fetch data from a URL that can take longer that the serverless timeout. | `await io.backgroundFetch("fetch-some-data", { url: "https://example.com" });`             |
+| Task                                        | Description                                                             | Task code                                                                            |
+| ------------------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| [Delay](/documentation/concepts/delays)     | Wait for a period of time                                               | `await io.wait("wait", 60);`                                                         |
+| [Log](/sdk/io/logger)                       | Log a message                                                           | `await io.logger.log("Hello");`                                                      |
+| [Send Event](/sdk/io/sendevent)             | Send an event (for eventTrigger)                                        | `await io.sendEvent("my-event", { name: "my.event", payload: { hello: "world" } });` |
+| [Run task](/sdk/io/runtask)                 | Wrap your own code in this to create a Task                             | `await io.runTask("My Task", async () => { console.log("Hello"); });`                |
+| [Background fetch](/sdk/io/backgroundfetch) | Fetch data from a URL that can take longer that the serverless timeout. | `await io.backgroundFetch("fetch-some-data", { url: "https://example.com" });`       |
 
 For a full list of built-in Tasks, see the [io SDK reference](/sdk/io).
 
 **Integration Task examples:**
 
 <Info>
-  To use our integrations you will need to set them up in the app first. Our
-  guide is [here](/documentation/guides/using-integrations).
+  To use our integrations you will need to set them up in the app first. Our guide is
+  [here](/documentation/guides/using-integrations).
 </Info>
 
 <AccordionGroup>
@@ -229,10 +228,9 @@ yarn dlx @trigger.dev/cli@latest dev
 This will register all of your Jobs, they should appear in your dashboard.
 
 <Note>
-  Not seeing your Job in the web app? It might be because you forgot to import
-  it. This will need to be either in `app/api/trigger/route.ts` file if you're
-  using the Next,js App Router, or `pages/api/trigger.ts` if you're using the
-  Next,js Pages Router.
+  Not seeing your Job in the web app? It might be because you forgot to import it. This will need to
+  be either in `app/api/trigger/route.ts` file if you're using the Next,js App Router, or
+  `pages/api/trigger.ts` if you're using the Next,js Pages Router.
 </Note>
 
 If you are having trouble getting your job running, please reach out to us and we will help you fix any issues:

docs/integrations/apis/github.mdx

@@ -82,14 +82,17 @@ client.defineJob({
     github,
   },
   run: async (payload, io, ctx) => {
-    //wrap the SDK call in runTask
-    const { data } = await io.runTask("create-card", { name: "Create card" }, async () => {
-      //create a project card using the underlying client
-      return io.github.client.rest.projects.createCard({
-        column_id: 123,
-        note: "test",
-      });
-    });
+    //io.github.runTask allows you to use the underlying SDK client
+    const { data } = await io.github.runTask(
+      "create-card",
+      async (client) => {
+        return client.rest.projects.createCard({
+          column_id: 123,
+          note: "test",
+        });
+      },
+      { name: "Create card" }
+    );
 
     //log the url of the created card
     await io.logger.info(data.url);

docs/integrations/apis/plain.mdx

@@ -131,7 +131,7 @@ client.defineJob({
 
 ## Using the underlying client
 
-You can use the underlying client to do anything [@team-plain/typescript-sdk](https://github.com/team-plain/typescript-sdk) supports, but make sure to wrap it in a task:
+You can use the underlying client to do anything [@team-plain/typescript-sdk](https://github.com/team-plain/typescript-sdk) supports by using runTask:
 
 ```ts
 import { Plain } from "@trigger.dev/plain";
@@ -151,21 +151,14 @@ client.defineJob({
     name: "plain.client",
   }),
   run: async (payload, io, ctx) => {
-    const issue = await io.runTask(
+    const result = await io.plain.runTask(
       "create-issue",
-      { name: "Create issue", icon: "plain" },
-      async () => {
-        const result = await io.plain.client.createIssue({
+      async (client) =>
+        client.createIssue({
           customerId: "abcdefghij",
           issueTypeId: "123456",
-        });
-
-        if (result.error) {
-          throw result.error;
-        }
-
-        return result.data;
-      }
+        }),
+      { name: "Create issue" }
     );
   },
 });

docs/integrations/apis/stripe.mdx

@@ -215,7 +215,7 @@ If there are any tasks missing that you'd like to see added, please [open a new
 
 ## Using the underlying Stripe client
 
-You can use the underlying client to do anything the [stripe-node](https://github.com/stripe/stripe-node) client supports by using the `client` property on the integration:
+You can use the underlying client to do anything the [stripe-node](https://github.com/stripe/stripe-node) client supports by using `runTask` on the integration:
 
 ```ts
 const stripe = new Stripe({
@@ -234,20 +234,25 @@ client.defineJob({
     stripe,
   },
   run: async (payload, io, ctx) => {
-    await io.runTask("create-price", { name: "Create Price" }, async (task) => {
-      return stripe.client.prices.create(
-        {
-          unit_amount: 2000,
-          currency: "usd",
-          product_data: {
-            name: "T-shirt",
+    const price = await io.stripe.runTask(
+      "create-price",
+      async (client, task) => {
+        return client.prices.create(
+          {
+            unit_amount: 2000,
+            currency: "usd",
+            product_data: {
+              name: "T-shirt",
+            },
           },
-        },
-        {
-          idempotencyKey: task.idempotencyKey,
-        }
-      );
-    });
+          {
+            idempotencyKey: task.idempotencyKey,
+          }
+        );
+      },
+      //this is optional, it will appear on the Run page
+      { name: "Create Price" }
+    );
   },
 });
 ```

docs/integrations/apis/typeform.mdx

@@ -119,7 +119,7 @@ client.defineJob({
 
 ## Using the underlying client
 
-You can use the underlying client to do anything [@typeform/api-client](https://www.npmjs.com/package/@typeform/api-client) supports, but make sure to wrap it in a task:
+You can use the underlying client to do anything [@typeform/api-client](https://www.npmjs.com/package/@typeform/api-client) supports:
 
 ```ts
 import { Typeform } from "@trigger.dev/typeform";
@@ -139,14 +139,28 @@ client.defineJob({
     name: "typeform.client",
   }),
   run: async (payload, io, ctx) => {
-    const form = await io.runTask(
+    const form = await io.typeform.runTask(
       "create-form",
-      { name: "Create Form", icon: "typeform" },
-      async () => {
-        return io.typeform.client.forms.create({
-          data: { ... }
-        })
-      }
+      async (client) => {
+        return client.forms.create({
+          data: {
+            title: "My Form",
+            fields: [
+              {
+                title: "What is your name?",
+                type: "short_text",
+                ref: "name",
+              },
+              {
+                title: "What is your email?",
+                type: "email",
+                ref: "email",
+              },
+            ],
+          },
+        });
+      },
+      { name: "Create Form" }
     );
   },
 });

docs/integrations/create-tasks.mdx

@@ -374,10 +374,10 @@ const createIssueCommentWithReaction: GithubAuthenticatedTask<
   run: async (params, client, task, io, auth) => {
     const comment = await io.runTask(
       `Comment on Issue #${params.issueNumber}`,
-      createIssueComment.init(params),
       async (t) => {
         return createIssueComment.run(params, client, t, io, auth);
-      }
+      },
+      createIssueComment.init(params)
     );
 
     await io.runTask(

docs/sdk/io/runtask.mdx

@@ -10,12 +10,26 @@ A Task is a resumable unit of a Run that can be retried, resumed and is logged.
 
 <Snippet file="stable-key-param.mdx" />
 
-<ResponseField name="options" type="object" required>
-  The options of how you'd like to run and log the Task. `name` is the only required field.
+<ResponseField name="callback" type="function" required>
+  The callback that will be called when the Task is run, this is where your logic should go. The callback receives
+  the Task and the IO as parameters.
+
+  <Expandable title="arguments">
+    <ResponseField name="task" type="Task">
+      The Task that is running. It has some useful properties like `idempotencyKey` and `attempts`.
+    </ResponseField>
+    <ResponseField name="io" type="IO">
+      [IO](/sdk/io/overview) holds Integrations and useful actions you can perform.
+    </ResponseField>
+  </Expandable>
+</ResponseField>
+
+<ResponseField name="options" type="object">
+  The options of how you'd like to run and log the Task.
 
 <Expandable title="options">
-  <ResponseField name="name" type="string" required>
-    The name of the Task is required. This is displayed on the Task in the logs.
+  <ResponseField name="name" type="string">
+    This is displayed on the Task in the logs.
   </ResponseField>
   <ResponseField name="delayUntil" type="date">
     The Task will wait and only start at the specified Date.
@@ -87,20 +101,6 @@ A Task is a resumable unit of a Run that can be retried, resumed and is logged.
 </Expandable>
 </ResponseField>
 
-<ResponseField name="callback" type="function" required>
-  The callback that will be called when the Task is run, this is where your logic should go. The callback receives
-  the Task and the IO as parameters.
-
-  <Expandable title="arguments">
-    <ResponseField name="task" type="Task">
-      The Task that is running. It has some useful properties like `idempotencyKey` and `attempts`.
-    </ResponseField>
-    <ResponseField name="io" type="IO">
-      [IO](/sdk/io/overview) holds Integrations and useful actions you can perform.
-    </ResponseField>
-  </Expandable>
-</ResponseField>
-
 <ResponseField name="onError" type="function">
   An optional callback that will be called when the Task fails. You can perform
   logic in here and optionally return a custom error object. Returning an object with `{ retryAt: Date, error?: Error }` will retry the Task at the specified Date. You can also just return a new `Error` object to throw a new error. Return nothing to rethrow the original error.