v3: Adding SDK functions for triggering tasks in a typesafe way (#1177)

* v3: Adding SDK functions for triggering tasks in a typesafe way, without importing task file

* Add type usages

.changeset/sweet-ducks-remember.md

@@ -0,0 +1,5 @@
+---
+"@trigger.dev/sdk": patch
+---
+
+v3: Adding SDK functions for triggering tasks in a typesafe way, without importing task file

apps/webapp/app/v3/tracer.server.ts

@@ -117,7 +117,7 @@ function getTracer() {
   const samplingRate = 1.0 / Math.max(parseInt(env.INTERNAL_OTEL_TRACE_SAMPLING_RATE, 10), 1);
 
   const provider = new NodeTracerProvider({
-    forceFlushTimeoutMillis: 500,
+    forceFlushTimeoutMillis: 5000,
     resource: new Resource({
       [SEMRESATTRS_SERVICE_NAME]: env.SERVICE_NAME,
     }),

docs/v3/triggering.mdx

@@ -3,7 +3,7 @@ title: "Triggering"
 description: "Tasks need to be triggered to run."
 ---
 
-There are currently four ways you can trigger any task from your own code:
+There are currently six ways you can trigger tasks:
 
 | Function                         | Where does this work? | What it does                                                                                                                       |
 | -------------------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
@@ -11,6 +11,8 @@ There are currently four ways you can trigger any task from your own code:
 | `yourTask.batchTrigger()`        | Anywhere              | Triggers a task multiple times and gets a handle you can use to monitor and manage the runs. It does not wait for the results.     |
 | `yourTask.triggerAndWait()`      | Inside a task         | Triggers a task and then waits until it's complete. You get the result data to continue with.                                      |
 | `yourTask.batchTriggerAndWait()` | Inside a task         | Triggers a task multiple times in parallel and then waits until they're all complete. You get the resulting data to continue with. |
+| `tasks.trigger()`                | Outside of a task     | Triggers a task and gets a handle you can use to fetch and manage the run.                                                         |
+| `tasks.batchTrigger()`           | Outside of a task     | Triggers a task multiple times and gets a handle you can use to fetch and manage the runs.                                         |
 
 Additionally, [scheduled tasks](/v3/tasks-scheduled) get automatically triggered on their schedule and [webhooks](/v3/tasks-webhooks) when receiving a webhook.
 
@@ -18,25 +20,20 @@ Additionally, [scheduled tasks](/v3/tasks-scheduled) get automatically triggered
 
 You should attach one or more schedules to your `schedules.task()` to trigger it on a recurring schedule. [Read the scheduled tasks docs](/v3/tasks-scheduled).
 
-## From outside of a task
-
-You can trigger any task from your backend code, using either `trigger()` or `batchTrigger()`.
-
-<Note>
-  Do not trigger tasks directly from your frontend. If you do, you will leak your private
-  Trigger.dev API key to the world.
-</Note>
-
-You can use Next.js Server Actions but [you need to be careful with bundling](#next-js-server-actions).
-
-### Authentication
+## Authentication
 
 When you trigger a task from your backend code, you need to set the `TRIGGER_SECRET_KEY` environment variable. You can find the value on the API keys page in the Trigger.dev dashboard. [More info on API keys](/v3/apikeys).
 
-### trigger()
+## Task instance methods
+
+Task instance methods are available on the `Task` object you receive when you define a task. They can be called from your backend code or from inside another task.
+
+### Task.trigger()
 
 Triggers a single run of a task with the payload you pass in, and any options you specify. It does NOT wait for the result, you cannot do that from outside a task.
 
+If called from within a task, you can use the `AndWait` version to pause execution until the triggered run is complete.
+
 <CodeGroup>
 
 ```ts Next.js API route
@@ -74,11 +71,24 @@ export async function action({ request, params }: ActionFunctionArgs) {
 }
 ```
 
+```ts /trigger/my-task.ts
+import { myOtherTask } from "~/trigger/my-other-task";
+
+export const myTask = task({
+  id: "my-task",
+  run: async (payload: string) => {
+    const handle = await myOtherTask.trigger("some data");
+
+    //...do other stuff
+  },
+});
+```
+
 </CodeGroup>
 
-### batchTrigger()
+### Task.batchTrigger()
 
-Triggers multiples runs of a task with the payloads you pass in, and any options you specify. It does NOT wait for the results, you cannot do that from outside a task.
+Triggers multiples runs of a task with the payloads you pass in, and any options you specify.
 
 <CodeGroup>
 
@@ -121,33 +131,6 @@ export async function action({ request, params }: ActionFunctionArgs) {
 }
 ```
 
-</CodeGroup>
-
-## From inside a task
-
-You can trigger tasks from other tasks using `trigger()` or `batchTrigger()`. You can also trigger and wait for the result of triggered tasks using `triggerAndWait()` and `batchTriggerAndWait()`. This is a powerful way to build complex tasks.
-
-### trigger()
-
-This works the same as from outside a task. You call it and you get a handle back, but it does not wait for the result.
-
-```ts /trigger/my-task.ts
-import { myOtherTask } from "~/trigger/my-other-task";
-
-export const myTask = task({
-  id: "my-task",
-  run: async (payload: string) => {
-    const handle = await myOtherTask.trigger("some data");
-
-    //...do other stuff
-  },
-});
-```
-
-### batchTrigger()
-
-This works the same as from outside a task. You call it and you get a handle back, but it does not wait for the results.
-
 ```ts /trigger/my-task.ts
 import { myOtherTask } from "~/trigger/my-other-task";
 
@@ -161,7 +144,9 @@ export const myTask = task({
 });
 ```
 
-### triggerAndWait()
+</CodeGroup>
+
+### Task.triggerAndWait()
 
 This is where it gets interesting. You can trigger a task and then wait for the result. This is useful when you need to call a different task and then use the result to continue with your task.
 
@@ -219,7 +204,7 @@ export const parentTask = task({
 });
 ```
 
-### batchTriggerAndWait()
+### Task.batchTriggerAndWait()
 
 You can batch trigger a task and wait for all the results. This is useful for the fan-out pattern, where you need to call a task multiple times and then wait for all the results to continue with your task.
 
@@ -284,11 +269,213 @@ export const batchParentTask = task({
 });
 ```
 
+## SDK functions
+
+You can trigger any task from your backend code using the `tasks.trigger()` or `tasks.batchTrigger()` SDK functions.
+
+<Note>
+  Do not trigger tasks directly from your frontend. If you do, you will leak your private
+  Trigger.dev API key.
+</Note>
+
+You can use Next.js Server Actions but [you need to be careful with bundling](#next-js-server-actions).
+
+### tasks.trigger()
+
+Triggers a single run of a task with the payload you pass in, and any options you specify, without needing to import the task.
+
+<Note>
+  Why would you use this instead of the `Task.trigger()` instance method? Tasks can import
+  dependencies/modules that you might not want included in your application code or cause problems
+  with building.
+</Note>
+
+<CodeGroup>
+
+```ts Next.js API route
+import { tasks } from "@trigger.dev/sdk/v3";
+import type { emailSequence } from "~/trigger/emails";
+//     👆 **type-only** import
+
+//app/email/route.ts
+export async function POST(request: Request) {
+  //get the JSON from the request
+  const data = await request.json();
+
+  // Pass the task type to `trigger()` as a generic argument, giving you full type checking
+  const handle = await tasks.trigger<typeof emailSequence>("email-sequence", {
+    to: data.email,
+    name: data.name,
+  });
+
+  //return a success response with the handle
+  return Response.json(handle);
+}
+```
+
+```ts Remix
+import { tasks } from "@trigger.dev/sdk/v3";
+
+export async function action({ request, params }: ActionFunctionArgs) {
+  if (request.method.toUpperCase() !== "POST") {
+    return json("Method Not Allowed", { status: 405 });
+  }
+
+  //get the JSON from the request
+  const data = await request.json();
+
+  // The generic argument is optional, but recommended for full type checking
+  const handle = await tasks.trigger("email-sequence", {
+    to: data.email,
+    name: data.name,
+  });
+
+  //return a success response with the handle
+  return json(handle);
+}
+```
+
+</CodeGroup>
+
+<Tip>
+  By importing the task with the type modifier, the import of `"~/trigger/emails"` is a type-only
+  import. This means that the task code is not included in your application at build time.
+</Tip>
+
+### tasks.batchTrigger()
+
+Triggers multiples runs of a task with the payloads you pass in, and any options you specify, without needing to import the task.
+
+<CodeGroup>
+
+```ts Next.js API route
+import { tasks } from "@trigger.dev/sdk/v3";
+import type { emailSequence } from "~/trigger/emails";
+//     👆 **type-only** import
+
+//app/email/route.ts
+export async function POST(request: Request) {
+  //get the JSON from the request
+  const data = await request.json();
+
+  // Pass the task type to `batchTrigger()` as a generic argument, giving you full type checking
+  const batchHandle = await tasks.batchTrigger<typeof emailSequence>(
+    "email-sequence",
+    data.users.map((u) => ({ payload: { to: u.email, name: u.name } }))
+  );
+
+  //return a success response with the handle
+  return Response.json(batchHandle);
+}
+```
+
+</CodeGroup>
+
+### tasks.triggerAndPoll()
+
+Triggers a single run of a task with the payload you pass in, and any options you specify, and then polls the run until it's complete.
+
+<CodeGroup>
+
+```ts Next.js API route
+import { tasks } from "@trigger.dev/sdk/v3";
+import type { emailSequence } from "~/trigger/emails";
+
+//app/email/route.ts
+export async function POST(request: Request) {
+  //get the JSON from the request
+  const data = await request.json();
+
+  // Pass the task type to `triggerAndPoll()` as a generic argument, giving you full type checking
+  const result = await tasks.triggerAndPoll<typeof emailSequence>(
+    "email-sequence",
+    {
+      to: data.email,
+      name: data.name,
+    },
+    { pollIntervalMs: 5000 }
+  );
+
+  //return a success response with the result
+  return Response.json(result);
+}
+```
+
+</CodeGroup>
+
+<Note>
+  The above code is just a demonstration of the API and is not recommended to use in an API route
+  this way as it will block the request until the task is complete.
+</Note>
+
+### runs.retrieve()
+
+You can retrieve a run by its handle using the `runs.retrieve()` function.
+
+<CodeGroup>
+
+```ts Next.js API route
+import { tasks, runs } from "@trigger.dev/sdk/v3";
+import type { emailSequence } from "~/trigger/emails";
+//     👆 **type-only** import
+
+//app/email/route.ts
+export async function POST(request: Request) {
+  //get the JSON from the request
+  const data = await request.json();
+
+  // Pass the task type to `trigger()` as a generic argument, giving you full type checking
+  const handle = await tasks.trigger<typeof emailSequence>("email-sequence", {
+    to: data.email,
+    name: data.name,
+  });
+
+  const run = await runs.retrieve(handle);
+
+  // run.output will be correctly typed as the return value of the task
+  return Response.json(run.output);
+}
+```
+
+</CodeGroup>
+
+### runs.poll()
+
+You can poll a run by its handle using the `runs.poll()` function.
+
+<CodeGroup>
+
+```ts Next.js API route
+import { tasks, runs } from "@trigger.dev/sdk/v3";
+import type { emailSequence } from "~/trigger/emails";
+//     👆 **type-only** import
+
+//app/email/route.ts
+export async function POST(request: Request) {
+  //get the JSON from the request
+  const data = await request.json();
+
+  // Pass the task type to `trigger()` as a generic argument, giving you full type checking
+  const handle = await tasks.trigger<typeof emailSequence>("email-sequence", {
+    to: data.email,
+    name: data.name,
+  });
+
+  // Poll the run until it's complete
+  const run = await runs.poll(handle, { pollIntervalMs: 5000 });
+
+  // run.output will be correctly typed as the return value of the task
+  return Response.json(run.output);
+}
+```
+
+</CodeGroup>
+
 ## Next.js Server Actions
 
 Server Actions allow you to call your backend code without creating API routes. This is very useful for triggering tasks but you need to be careful you don't accidentally bundle the Trigger.dev SDK into your frontend code.
 
-If you see an error like this then you've bundled `@trigger.dev/sdk` into your frontend code:
+If you see an error like this then you've bundled `@trigger.dev/sdk/v3` into your frontend code:
 
 ```bash
 Module build failed: UnhandledSchemeError: Reading from "node:crypto" is not handled by plugins (Unhandled scheme).
@@ -297,7 +484,7 @@ Webpack supports "data:" and "file:" URIs by default.
 You may need an additional plugin to handle "node:" URIs.
 ```
 
-When you use server actions that use `@trigger.dev/sdk`:
+When you use server actions that use `@trigger.dev/sdk/v3`:
 
 - The file can't have any React components in it.
 - The file should have `"use server"` on the first line.

packages/trigger-sdk/src/v3/runs.ts

@@ -1,22 +1,28 @@
+import type { ListProjectRunsQueryParams, ListRunsQueryParams } from "@trigger.dev/core/v3";
 import {
   ApiPromise,
   CanceledRunResponse,
+  CursorPagePromise,
   ListRunResponseItem,
   ReplayRunResponse,
   RetrieveRunResponse,
   apiClientManager,
-  CursorPagePromise,
 } from "@trigger.dev/core/v3";
-import type { ListProjectRunsQueryParams, ListRunsQueryParams } from "@trigger.dev/core/v3";
-import { apiClientMissingError } from "./shared";
+import { setTimeout } from "timers/promises";
+import { Prettify, RunHandle, apiClientMissingError } from "./shared";
 
-export type RetrieveRunResult = RetrieveRunResponse;
+export type RetrieveRunResult<TOutput> = Prettify<
+  TOutput extends RunHandle<infer THandleOutput>
+    ? Omit<RetrieveRunResponse, "output"> & { output?: THandleOutput }
+    : Omit<RetrieveRunResponse, "output"> & { output?: TOutput }
+>;
 
 export const runs = {
   replay: replayRun,
   cancel: cancelRun,
   retrieve: retrieveRun,
   list: listRuns,
+  poll,
 };
 
 export type ListRunsItem = ListRunResponseItem;
@@ -43,14 +49,20 @@ function listRuns(
   return apiClient.listRuns(params);
 }
 
-function retrieveRun(runId: string): ApiPromise<RetrieveRunResult> {
+function retrieveRun<TRunId extends RunHandle<any> | string>(
+  runId: TRunId
+): ApiPromise<RetrieveRunResult<TRunId>> {
   const apiClient = apiClientManager.client;
 
   if (!apiClient) {
     throw apiClientMissingError();
   }
 
-  return apiClient.retrieveRun(runId);
+  if (typeof runId === "string") {
+    return apiClient.retrieveRun(runId) as ApiPromise<RetrieveRunResult<TRunId>>;
+  } else {
+    return apiClient.retrieveRun(runId.id) as ApiPromise<RetrieveRunResult<TRunId>>;
+  }
 }
 
 function replayRun(runId: string): ApiPromise<ReplayRunResponse> {
@@ -72,3 +84,20 @@ function cancelRun(runId: string): ApiPromise<CanceledRunResponse> {
 
   return apiClient.cancelRun(runId);
 }
+
+export type PollOptions = { pollIntervalMs?: number };
+
+async function poll<TRunHandle extends RunHandle<any> | string>(
+  handle: TRunHandle,
+  options?: { pollIntervalMs?: number }
+) {
+  while (true) {
+    const run = await runs.retrieve(handle);
+
+    if (run.isCompleted) {
+      return run;
+    }
+
+    await setTimeout(Math.max(options?.pollIntervalMs ?? 5000, 1000));
+  }
+}

packages/trigger-sdk/src/v3/schedules/index.ts

@@ -12,9 +12,9 @@ import { zodfetch } from "@trigger.dev/core/v3/zodfetch";
 import { Task, TaskOptions, apiClientMissingError, createTask } from "../shared";
 import * as SchedulesAPI from "./api";
 
-export function task<TOutput, TInitOutput extends InitOutput>(
-  params: TaskOptions<SchedulesAPI.ScheduledTaskPayload, TOutput, TInitOutput>
-): Task<SchedulesAPI.ScheduledTaskPayload, TOutput> {
+export function task<TIdentifier extends string, TOutput, TInitOutput extends InitOutput>(
+  params: TaskOptions<TIdentifier, SchedulesAPI.ScheduledTaskPayload, TOutput, TInitOutput>
+): Task<TIdentifier, SchedulesAPI.ScheduledTaskPayload, TOutput> {
   const task = createTask(params);
 
   taskCatalog.updateTaskMetadata(task.id, {

packages/trigger-sdk/src/v3/shared.ts

@@ -5,6 +5,7 @@ import {
   SEMATTRS_MESSAGING_SYSTEM,
 } from "@opentelemetry/semantic-conventions";
 import {
+  ApiPromise,
   BatchTaskRunExecutionResult,
   FailureFnParams,
   HandleErrorFnParams,
@@ -36,6 +37,7 @@ import {
 } from "@trigger.dev/core/v3";
 import * as packageJson from "../../package.json";
 import { tracer } from "./tracer";
+import { PollOptions, RetrieveRunResult, runs } from "./runs";
 
 export type Context = TaskRunContext;
 
@@ -52,12 +54,13 @@ export function queue(options: { name: string } & QueueOptions): Queue {
 }
 
 export type TaskOptions<
+  TIdentifier extends string,
   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;
+  id: TIdentifier;
   /** The retry settings when an uncaught error is thrown.
    *
    * If omitted it will use the values in your `trigger.config.ts` file.
@@ -220,14 +223,31 @@ export type TaskOptions<
   ) => Promise<void>;
 };
 
-type InvokeHandle = {
-  id: string;
-};
+declare const __output: unique symbol;
+type BrandOutput<B> = { [__output]: B };
+export type BrandedOutput<T, B> = T & BrandOutput<B>;
 
-type InvokeBatchHandle = {
-  batchId: string;
-  runs: string[];
-};
+export type RunHandle<TOutput> = BrandedOutput<
+  {
+    id: string;
+  },
+  TOutput
+>;
+
+/**
+ * A BatchRunHandle can be used to retrieve the runs of a batch trigger in a typesafe manner.
+ */
+export type BatchRunHandle<TOutput> = BrandedOutput<
+  {
+    batchId: string;
+    runs: Array<RunHandle<TOutput>>;
+  },
+  TOutput
+>;
+
+export type RunHandleOutput<TRunHandle> = TRunHandle extends RunHandle<infer TOutput>
+  ? TOutput
+  : never;
 
 export type TaskRunResult<TOutput = any> =
   | {
@@ -246,23 +266,23 @@ export type BatchResult<TOutput = any> = {
   runs: TaskRunResult<TOutput>[];
 };
 
-type BatchItem<TInput> = TInput extends void
+export type BatchItem<TInput> = TInput extends void
   ? { payload?: TInput; options?: TaskRunOptions }
   : { payload: TInput; options?: TaskRunOptions };
 
-export interface Task<TInput = void, TOutput = any> {
+export interface Task<TIdentifier extends string, TInput = void, TOutput = any> {
   /**
    * The id of the task.
    */
-  id: string;
+  id: TIdentifier;
   /**
    * 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
+   * @returns RunHandle
    * - `id` - The id of the triggered task run.
    */
-  trigger: (payload: TInput, options?: TaskRunOptions) => Promise<InvokeHandle>;
+  trigger: (payload: TInput, options?: TaskRunOptions) => Promise<RunHandle<TOutput>>;
 
   /**
    * 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.
@@ -271,7 +291,7 @@ export interface Task<TInput = void, TOutput = any> {
    * - `batchId` - The id of the triggered batch.
    * - `runs` - The ids of the triggered task runs.
    */
-  batchTrigger: (items: Array<BatchItem<TInput>>) => Promise<InvokeBatchHandle>;
+  batchTrigger: (items: Array<BatchItem<TInput>>) => Promise<BatchRunHandle<TOutput>>;
 
   /**
    * Trigger a task with the given payload, and wait for the result. Returns the result of the task run
@@ -314,15 +334,33 @@ export interface Task<TInput = void, TOutput = any> {
   batchTriggerAndWait: (items: Array<BatchItem<TInput>>) => Promise<BatchResult<TOutput>>;
 }
 
-export type TaskPayload<TTask extends Task> = TTask extends Task<infer TInput, any>
+type AnyTask = Task<string, any, any>;
+
+export type TaskPayload<TTask extends AnyTask> = TTask extends Task<string, infer TInput, any>
   ? TInput
   : never;
 
-export type TaskOutput<TTask extends Task> = TTask extends Task<any, infer TOutput>
+export type TaskOutput<TTask extends AnyTask> = TTask extends Task<string, any, infer TOutput>
   ? TOutput
   : never;
 
-type TaskRunOptions = {
+export type TaskOutputHandle<TTask extends AnyTask> = TTask extends Task<string, any, infer TOutput>
+  ? RunHandle<TOutput>
+  : never;
+
+export type TaskBatchOutputHandle<TTask extends AnyTask> = TTask extends Task<
+  string,
+  any,
+  infer TOutput
+>
+  ? BatchRunHandle<TOutput>
+  : never;
+
+export type TaskIdentifier<TTask extends AnyTask> = TTask extends Task<infer TIdentifier, any, any>
+  ? TIdentifier
+  : never;
+
+export type TaskRunOptions = {
   idempotencyKey?: string;
   maxAttempts?: number;
   startAt?: Date;
@@ -341,10 +379,15 @@ export type DynamicBaseOptions = {
   id: string;
 };
 
-export function createTask<TInput = void, TOutput = unknown, TInitOutput extends InitOutput = any>(
-  params: TaskOptions<TInput, TOutput, TInitOutput>
-): Task<TInput, TOutput> {
-  const task: Task<TInput, TOutput> = {
+export function createTask<
+  TIdentifier extends string,
+  TInput = void,
+  TOutput = unknown,
+  TInitOutput extends InitOutput = any,
+>(
+  params: TaskOptions<TIdentifier, TInput, TOutput, TInitOutput>
+): Task<TIdentifier, TInput, TOutput> {
+  const task: Task<TIdentifier, TInput, TOutput> = {
     id: params.id,
     trigger: async (payload, options) => {
       const apiClient = apiClientManager.client;
@@ -402,7 +445,7 @@ export function createTask<TInput = void, TOutput = unknown, TInitOutput extends
         }
       );
 
-      return handle;
+      return handle as RunHandle<TOutput>;
     },
     batchTrigger: async (items) => {
       const apiClient = apiClientManager.client;
@@ -441,7 +484,12 @@ export function createTask<TInput = void, TOutput = unknown, TInitOutput extends
 
           span.setAttribute("messaging.message.id", response.batchId);
 
-          return response;
+          const handle = {
+            batchId: response.batchId,
+            runs: response.runs.map((id) => ({ id })),
+          };
+
+          return handle as BatchRunHandle<TOutput>;
         },
         {
           kind: SpanKind.PRODUCER,
@@ -707,6 +755,111 @@ export function createTask<TInput = void, TOutput = unknown, TInitOutput extends
   return task;
 }
 
+/**
+ * Trigger a task by its identifier with the given payload. Returns a typesafe `RunHandle`.
+ *
+ * @example
+ *
+ * ```ts
+ * import { tasks, runs } from "@trigger.dev/sdk/v3";
+ * import type { myTask } from "./myTasks"; // Import just the type of the task
+ *
+ * const handle = await tasks.trigger<typeof myTask>("my-task", { foo: "bar" }); // The id and payload are fully typesafe
+ * const run = await runs.retrieve(handle);
+ * console.log(run.output) // The output is also fully typed
+ * ```
+ *
+ * @returns {RunHandle} An object with the `id` of the run. Can be used to retrieve the completed run output in a typesafe manner.
+ */
+export async function trigger<TTask extends AnyTask>(
+  id: TaskIdentifier<TTask>,
+  payload: TaskPayload<TTask>,
+  options?: TaskRunOptions
+): Promise<TaskOutputHandle<TTask>> {
+  const apiClient = apiClientManager.client;
+
+  if (!apiClient) {
+    throw apiClientMissingError();
+  }
+
+  const payloadPacket = await stringifyIO(payload);
+
+  const handle = await apiClient.triggerTask(id, {
+    payload: payloadPacket.data,
+    options: {
+      queue: options?.queue,
+      concurrencyKey: options?.concurrencyKey,
+      test: taskContext.ctx?.run.isTest,
+      payloadType: payloadPacket.dataType,
+      idempotencyKey: options?.idempotencyKey,
+    },
+  });
+
+  return handle as TaskOutputHandle<TTask>;
+}
+
+/**
+ * Trigger a task by its identifier with the given payload and poll until the run is completed.
+ *
+ * @example
+ *
+ * ```ts
+ * import { tasks, runs } from "@trigger.dev/sdk/v3";
+ * import type { myTask } from "./myTasks"; // Import just the type of the task
+ *
+ * const run = await tasks.triggerAndPoll<typeof myTask>("my-task", { foo: "bar" }); // The id and payload are fully typesafe
+ * console.log(run.output) // The output is also fully typed
+ * ```
+ *
+ * @returns {Run} The completed run, either successful or failed.
+ */
+export async function triggerAndPoll<TTask extends AnyTask>(
+  id: TaskIdentifier<TTask>,
+  payload: TaskPayload<TTask>,
+  options?: TaskRunOptions & PollOptions
+): Promise<RetrieveRunResult<TaskOutputHandle<TTask>>> {
+  const handle = await trigger(id, payload, options);
+
+  return runs.poll(handle);
+}
+
+export async function batchTrigger<TTask extends AnyTask>(
+  id: TaskIdentifier<TTask>,
+  items: Array<BatchItem<TaskPayload<TTask>>>
+): Promise<TaskBatchOutputHandle<TTask>> {
+  const apiClient = apiClientManager.client;
+
+  if (!apiClient) {
+    throw apiClientMissingError();
+  }
+
+  const response = await apiClient.batchTriggerTask(id, {
+    items: await Promise.all(
+      items.map(async (item) => {
+        const payloadPacket = await stringifyIO(item.payload);
+
+        return {
+          payload: payloadPacket.data,
+          options: {
+            queue: item.options?.queue,
+            concurrencyKey: item.options?.concurrencyKey,
+            test: taskContext.ctx?.run.isTest,
+            payloadType: payloadPacket.dataType,
+            idempotencyKey: item.options?.idempotencyKey,
+          },
+        };
+      })
+    ),
+  });
+
+  const handle = {
+    batchId: response.batchId,
+    runs: response.runs.map((id) => ({ id })),
+  };
+
+  return handle as TaskBatchOutputHandle<TTask>;
+}
+
 async function handleBatchTaskRunExecutionResult<TOutput>(
   items: Array<TaskRunExecutionResult>
 ): Promise<Array<TaskRunResult<TOutput>>> {

packages/trigger-sdk/src/v3/tasks.ts

@@ -1,5 +1,35 @@
 import { InitOutput } from "@trigger.dev/core/v3";
-import { TaskOptions, Task, createTask } from "./shared";
+import { batchTrigger, createTask, trigger, triggerAndPoll } from "./shared";
+
+import type {
+  TaskOptions,
+  Task,
+  Queue,
+  RunHandle,
+  BatchRunHandle,
+  TaskRunResult,
+  BatchResult,
+  BatchItem,
+  TaskPayload,
+  TaskOutput,
+  TaskIdentifier,
+  TaskRunOptions,
+} from "./shared";
+
+export type {
+  TaskOptions,
+  Task,
+  Queue,
+  RunHandle,
+  BatchRunHandle,
+  TaskRunResult,
+  BatchResult,
+  BatchItem,
+  TaskPayload,
+  TaskOutput,
+  TaskIdentifier,
+  TaskRunOptions,
+};
 
 /** Creates a task that can be triggered
  * @param options - Task options
@@ -19,10 +49,19 @@ import { TaskOptions, Task, createTask } from "./shared";
  * 
  * @returns A task that can be triggered
  */
-export function task<TInput = void, TOutput = unknown, TInitOutput extends InitOutput = any>(
-  options: TaskOptions<TInput, TOutput, TInitOutput>
-): Task<TInput, TOutput> {
-  return createTask<TInput, TOutput, TInitOutput>(options);
+export function task<
+  TIdentifier extends string,
+  TInput = void,
+  TOutput = unknown,
+  TInitOutput extends InitOutput = any,
+>(
+  options: TaskOptions<TIdentifier, TInput, TOutput, TInitOutput>
+): Task<TIdentifier, TInput, TOutput> {
+  return createTask<TIdentifier, TInput, TOutput, TInitOutput>(options);
 }
 
-export type { TaskOptions, Task };
+export const tasks = {
+  trigger,
+  triggerAndPoll,
+  batchTrigger,
+};

pnpm-lock.yaml

@@ -2157,7 +2157,7 @@ importers:
         version: 1.167.3
       tsup:
         specifier: ^8.0.1
-        version: 8.0.1(patch_hash=a5ztaafw5l4qfghy2hjjuynb34)(postcss@8.4.27)(typescript@5.3.3)
+        version: 8.0.1(patch_hash=a5ztaafw5l4qfghy2hjjuynb34)(postcss@8.4.27)(ts-node@10.9.2)(typescript@5.3.3)
       typescript:
         specifier: ^5.3.0
         version: 5.3.3
@@ -3190,6 +3190,9 @@ importers:
       '@types/react':
         specifier: ^18.3.1
         version: 18.3.1
+      esbuild:
+        specifier: ^0.19.11
+        version: 0.19.11
       trigger.dev:
         specifier: workspace:*
         version: link:../../packages/cli-v3
@@ -3199,6 +3202,9 @@ importers:
       tsconfig-paths:
         specifier: ^4.2.0
         version: 4.2.0
+      tsup:
+        specifier: ^8.0.1
+        version: 8.0.1(patch_hash=a5ztaafw5l4qfghy2hjjuynb34)(postcss@8.4.27)(ts-node@10.9.2)(typescript@5.3.3)
       typescript:
         specifier: ^5.3.0
         version: 5.3.3
@@ -14141,7 +14147,6 @@ packages:
     cpu: [arm]
     os: [android]
     requiresBuild: true
-    dev: true
     optional: true
 
   /@rollup/rollup-android-arm-eabi@4.6.1:
@@ -14149,6 +14154,7 @@ packages:
     cpu: [arm]
     os: [android]
     requiresBuild: true
+    dev: true
     optional: true
 
   /@rollup/rollup-android-arm64@4.13.2:
@@ -14156,7 +14162,6 @@ packages:
     cpu: [arm64]
     os: [android]
     requiresBuild: true
-    dev: true
     optional: true
 
   /@rollup/rollup-android-arm64@4.6.1:
@@ -14164,6 +14169,7 @@ packages:
     cpu: [arm64]
     os: [android]
     requiresBuild: true
+    dev: true
     optional: true
 
   /@rollup/rollup-darwin-arm64@4.13.2:
@@ -14171,7 +14177,6 @@ packages:
     cpu: [arm64]
     os: [darwin]
     requiresBuild: true
-    dev: true
     optional: true
 
   /@rollup/rollup-darwin-arm64@4.6.1:
@@ -14179,6 +14184,7 @@ packages:
     cpu: [arm64]
     os: [darwin]
     requiresBuild: true
+    dev: true
     optional: true
 
   /@rollup/rollup-darwin-x64@4.13.2:
@@ -14186,7 +14192,6 @@ packages:
     cpu: [x64]
     os: [darwin]
     requiresBuild: true
-    dev: true
     optional: true
 
   /@rollup/rollup-darwin-x64@4.6.1:
@@ -14194,6 +14199,7 @@ packages:
     cpu: [x64]
     os: [darwin]
     requiresBuild: true
+    dev: true
     optional: true
 
   /@rollup/rollup-linux-arm-gnueabihf@4.13.2:
@@ -14201,7 +14207,6 @@ packages:
     cpu: [arm]
     os: [linux]
     requiresBuild: true
-    dev: true
     optional: true
 
   /@rollup/rollup-linux-arm-gnueabihf@4.6.1:
@@ -14209,6 +14214,7 @@ packages:
     cpu: [arm]
     os: [linux]
     requiresBuild: true
+    dev: true
     optional: true
 
   /@rollup/rollup-linux-arm64-gnu@4.13.2:
@@ -14216,7 +14222,6 @@ packages:
     cpu: [arm64]
     os: [linux]
     requiresBuild: true
-    dev: true
     optional: true
 
   /@rollup/rollup-linux-arm64-gnu@4.6.1:
@@ -14224,6 +14229,7 @@ packages:
     cpu: [arm64]
     os: [linux]
     requiresBuild: true
+    dev: true
     optional: true
 
   /@rollup/rollup-linux-arm64-musl@4.13.2:
@@ -14231,7 +14237,6 @@ packages:
     cpu: [arm64]
     os: [linux]
     requiresBuild: true
-    dev: true
     optional: true
 
   /@rollup/rollup-linux-arm64-musl@4.6.1:
@@ -14239,6 +14244,7 @@ packages:
     cpu: [arm64]
     os: [linux]
     requiresBuild: true
+    dev: true
     optional: true
 
   /@rollup/rollup-linux-powerpc64le-gnu@4.13.2:
@@ -14246,7 +14252,6 @@ packages:
     cpu: [ppc64le]
     os: [linux]
     requiresBuild: true
-    dev: true
     optional: true
 
   /@rollup/rollup-linux-riscv64-gnu@4.13.2:
@@ -14254,7 +14259,6 @@ packages:
     cpu: [riscv64]
     os: [linux]
     requiresBuild: true
-    dev: true
     optional: true
 
   /@rollup/rollup-linux-s390x-gnu@4.13.2:
@@ -14262,7 +14266,6 @@ packages:
     cpu: [s390x]
     os: [linux]
     requiresBuild: true
-    dev: true
     optional: true
 
   /@rollup/rollup-linux-x64-gnu@4.13.2:
@@ -14270,7 +14273,6 @@ packages:
     cpu: [x64]
     os: [linux]
     requiresBuild: true
-    dev: true
     optional: true
 
   /@rollup/rollup-linux-x64-gnu@4.6.1:
@@ -14278,6 +14280,7 @@ packages:
     cpu: [x64]
     os: [linux]
     requiresBuild: true
+    dev: true
     optional: true
 
   /@rollup/rollup-linux-x64-musl@4.13.2:
@@ -14285,7 +14288,6 @@ packages:
     cpu: [x64]
     os: [linux]
     requiresBuild: true
-    dev: true
     optional: true
 
   /@rollup/rollup-linux-x64-musl@4.6.1:
@@ -14293,6 +14295,7 @@ packages:
     cpu: [x64]
     os: [linux]
     requiresBuild: true
+    dev: true
     optional: true
 
   /@rollup/rollup-win32-arm64-msvc@4.13.2:
@@ -14300,7 +14303,6 @@ packages:
     cpu: [arm64]
     os: [win32]
     requiresBuild: true
-    dev: true
     optional: true
 
   /@rollup/rollup-win32-arm64-msvc@4.6.1:
@@ -14308,6 +14310,7 @@ packages:
     cpu: [arm64]
     os: [win32]
     requiresBuild: true
+    dev: true
     optional: true
 
   /@rollup/rollup-win32-ia32-msvc@4.13.2:
@@ -14315,7 +14318,6 @@ packages:
     cpu: [ia32]
     os: [win32]
     requiresBuild: true
-    dev: true
     optional: true
 
   /@rollup/rollup-win32-ia32-msvc@4.6.1:
@@ -14323,6 +14325,7 @@ packages:
     cpu: [ia32]
     os: [win32]
     requiresBuild: true
+    dev: true
     optional: true
 
   /@rollup/rollup-win32-x64-msvc@4.13.2:
@@ -14330,7 +14333,6 @@ packages:
     cpu: [x64]
     os: [win32]
     requiresBuild: true
-    dev: true
     optional: true
 
   /@rollup/rollup-win32-x64-msvc@4.6.1:
@@ -14338,6 +14340,7 @@ packages:
     cpu: [x64]
     os: [win32]
     requiresBuild: true
+    dev: true
     optional: true
 
   /@rushstack/eslint-patch@1.2.0:
@@ -15539,7 +15542,7 @@ packages:
   /@types/acorn@4.0.6:
     resolution: {integrity: sha512-veQTnWP+1D/xbxVrPC3zHnCZRjSrKfhbMUlEA43iMZLu7EsnTtkJklIuwrCPbOi8YkvDQAiW05VQQFvvz9oieQ==}
     dependencies:
-      '@types/estree': 1.0.2
+      '@types/estree': 1.0.5
     dev: true
 
   /@types/aria-query@5.0.1:
@@ -15718,21 +15721,18 @@ packages:
   /@types/estree-jsx@0.0.1:
     resolution: {integrity: sha512-gcLAYiMfQklDCPjQegGn0TBAn9it05ISEsEhlKQUddIk7o2XDokOcTN7HBO8tznM0D9dGezvHEfRZBfZf6me0A==}
     dependencies:
-      '@types/estree': 1.0.2
+      '@types/estree': 1.0.5
     dev: true
 
   /@types/estree-jsx@1.0.0:
     resolution: {integrity: sha512-3qvGd0z8F2ENTGr/GG1yViqfiKmRfrXVx5sJyHGFu3z7m5g5utCQtGp/g29JnjflhtQJBv1WDQukHiT58xPcYQ==}
     dependencies:
-      '@types/estree': 1.0.2
+      '@types/estree': 1.0.5
     dev: true
 
   /@types/estree@1.0.0:
     resolution: {integrity: sha512-WulqXMDUTYAXCjZnk6JtIHPigp55cVtDgDrO2gHRwhyJto21+1zbVCtOYB2L1F9w4qCQ0rOGWBnBe0FNTiEJIQ==}
 
-  /@types/estree@1.0.2:
-    resolution: {integrity: sha512-VeiPZ9MMwXjO32/Xu7+OwflfmeoRwkE/qzndw42gGtgJwZopBnzy2gD//NN1+go1mADzkDcqf/KnFRSjTJ8xJA==}
-
   /@types/estree@1.0.5:
     resolution: {integrity: sha512-/kYRxGDLWzHOB7q+wtSUQlFrtcdUccpfy+X+9iMBpHK8QLLhx2wIPYuS5DYtR9Wa/YlZAbIovy7qVdB1Aq6Lyw==}
 
@@ -19121,7 +19121,7 @@ packages:
     resolution: {integrity: sha512-7qJWqItLA8/VPVlKJlFXU+NBlo/qyfs39aJcuMT/2ere32ZqvF5OSxgdM5xOfJJ7O429gg2HM47y8v9P+9wrNw==}
     dependencies:
       '@jridgewell/sourcemap-codec': 1.4.15
-      '@types/estree': 1.0.2
+      '@types/estree': 1.0.5
       acorn: 8.10.0
       estree-walker: 3.0.3
       periscopic: 3.1.0
@@ -22252,7 +22252,7 @@ packages:
   /estree-util-attach-comments@2.1.0:
     resolution: {integrity: sha512-rJz6I4L0GaXYtHpoMScgDIwM0/Vwbu5shbMeER596rB2D1EWF6+Gj0e0UKzJPZrpoOc87+Q2kgVFHfjAymIqmw==}
     dependencies:
-      '@types/estree': 1.0.2
+      '@types/estree': 1.0.5
     dev: true
 
   /estree-util-build-jsx@2.2.2:
@@ -23825,7 +23825,7 @@ packages:
   /hast-util-to-estree@2.1.0:
     resolution: {integrity: sha512-Vwch1etMRmm89xGgz+voWXvVHba2iiMdGMKmaMfYt35rbVtFDq8JNwwAIvi8zHMkO6Gvqo9oTMwJTmzVRfXh4g==}
     dependencies:
-      '@types/estree': 1.0.2
+      '@types/estree': 1.0.5
       '@types/estree-jsx': 1.0.0
       '@types/hast': 2.3.4
       '@types/unist': 2.0.6
@@ -24763,7 +24763,7 @@ packages:
   /is-reference@3.0.1:
     resolution: {integrity: sha512-baJJdQLiYaJdvFbJqXrcGv3WU3QCzBlUcI5QhbesIm6/xPsvmO+2CDoi/GMOFBQEQm+PXkwOPrp9KK5ozZsp2w==}
     dependencies:
-      '@types/estree': 1.0.0
+      '@types/estree': 1.0.5
     dev: true
 
   /is-regex@1.1.4:
@@ -26953,7 +26953,7 @@ packages:
     resolution: {integrity: sha512-WWp3bf7xT9MppNuw3yPjpnOxa8cj5ACivEzXJKu0WwnjBYfzaBvIAT9KfeyI0Qkll+bfQtfftSwdgTH6QhTOKw==}
     dependencies:
       '@types/acorn': 4.0.6
-      '@types/estree': 1.0.2
+      '@types/estree': 1.0.5
       estree-util-visit: 1.2.0
       micromark-util-types: 1.0.2
       uvu: 0.5.6
@@ -29048,7 +29048,7 @@ packages:
   /periscopic@3.1.0:
     resolution: {integrity: sha512-vKiQ8RRtkl9P+r/+oefh25C3fhybptkHKCZSPlcXiJux2tJF55GnEj3BVn4A5gKfq9NWWXXrxkHBwVPUfH0opw==}
     dependencies:
-      '@types/estree': 1.0.2
+      '@types/estree': 1.0.5
       estree-walker: 3.0.3
       is-reference: 3.0.1
     dev: true
@@ -29375,7 +29375,7 @@ packages:
       yaml: 1.10.2
     dev: true
 
-  /postcss-load-config@4.0.1(postcss@8.4.27):
+  /postcss-load-config@4.0.1(postcss@8.4.27)(ts-node@10.9.2):
     resolution: {integrity: sha512-vEJIc8RdiBRu3oRAI0ymerOn+7rPuMvRXslTvZUKZonDHFIczxztIyJ1urxM1x9JXEikvpWWTUUqal5j/8QgvA==}
     engines: {node: '>= 14'}
     peerDependencies:
@@ -29389,6 +29389,7 @@ packages:
     dependencies:
       lilconfig: 2.1.0
       postcss: 8.4.27
+      ts-node: 10.9.2(@types/node@20.4.2)(typescript@5.3.3)
       yaml: 2.3.1
 
   /postcss-load-config@4.0.1(postcss@8.4.29)(ts-node@10.9.1):
@@ -31604,7 +31605,6 @@ packages:
       '@rollup/rollup-win32-ia32-msvc': 4.13.2
       '@rollup/rollup-win32-x64-msvc': 4.13.2
       fsevents: 2.3.3
-    dev: true
 
   /rollup@4.6.1:
     resolution: {integrity: sha512-jZHaZotEHQaHLgKr8JnQiDT1rmatjgKlMekyksz+yk9jt/8z9quNjnKNRoaM0wd9DC2QKXjmWWuDYtM3jfF8pQ==}
@@ -31624,6 +31624,7 @@ packages:
       '@rollup/rollup-win32-ia32-msvc': 4.6.1
       '@rollup/rollup-win32-x64-msvc': 4.6.1
       fsevents: 2.3.3
+    dev: true
 
   /rtl-css-js@1.16.1:
     resolution: {integrity: sha512-lRQgou1mu19e+Ya0LsTvKrVJ5TYUbqCVPAiImX3UfLTenarvPUl1QFdvu5Z3PYmHT9RCcwIfbjRQBntExyj3Zg==}
@@ -33183,7 +33184,7 @@ packages:
       postcss: 8.4.27
       postcss-import: 15.1.0(postcss@8.4.27)
       postcss-js: 4.0.1(postcss@8.4.27)
-      postcss-load-config: 4.0.1(postcss@8.4.27)
+      postcss-load-config: 4.0.1(postcss@8.4.27)(ts-node@10.9.2)
       postcss-nested: 6.0.1(postcss@8.4.27)
       postcss-selector-parser: 6.0.11
       resolve: 1.22.4
@@ -34003,7 +34004,7 @@ packages:
       globby: 11.1.0
       joycon: 3.1.1
       postcss: 8.4.27
-      postcss-load-config: 4.0.1(postcss@8.4.27)
+      postcss-load-config: 4.0.1(postcss@8.4.27)(ts-node@10.9.2)
       resolve-from: 5.0.0
       rollup: 3.29.1
       source-map: 0.8.0-beta.0
@@ -34015,6 +34016,47 @@ packages:
       - ts-node
     dev: true
 
+  /tsup@8.0.1(patch_hash=a5ztaafw5l4qfghy2hjjuynb34)(postcss@8.4.27)(ts-node@10.9.2)(typescript@5.3.3):
+    resolution: {integrity: sha512-hvW7gUSG96j53ZTSlT4j/KL0q1Q2l6TqGBFc6/mu/L46IoNWqLLUzLRLP1R8Q7xrJTmkDxxDoojV5uCVs1sVOg==}
+    engines: {node: '>=18'}
+    hasBin: true
+    peerDependencies:
+      '@microsoft/api-extractor': ^7.36.0
+      '@swc/core': ^1
+      postcss: ^8.4.12
+      typescript: '>=4.5.0'
+    peerDependenciesMeta:
+      '@microsoft/api-extractor':
+        optional: true
+      '@swc/core':
+        optional: true
+      postcss:
+        optional: true
+      typescript:
+        optional: true
+    dependencies:
+      bundle-require: 4.0.1(esbuild@0.19.11)
+      cac: 6.7.14
+      chokidar: 3.5.3
+      debug: 4.3.4(supports-color@8.1.1)
+      esbuild: 0.19.11
+      execa: 5.1.1
+      globby: 11.1.0
+      joycon: 3.1.1
+      postcss: 8.4.27
+      postcss-load-config: 4.0.1(postcss@8.4.27)(ts-node@10.9.2)
+      resolve-from: 5.0.0
+      rollup: 4.13.2
+      source-map: 0.8.0-beta.0
+      sucrase: 3.32.0
+      tree-kill: 1.2.2
+      typescript: 5.3.3
+    transitivePeerDependencies:
+      - supports-color
+      - ts-node
+    dev: true
+    patched: true
+
   /tsup@8.0.1(patch_hash=a5ztaafw5l4qfghy2hjjuynb34)(postcss@8.4.27)(typescript@5.3.2):
     resolution: {integrity: sha512-hvW7gUSG96j53ZTSlT4j/KL0q1Q2l6TqGBFc6/mu/L46IoNWqLLUzLRLP1R8Q7xrJTmkDxxDoojV5uCVs1sVOg==}
     engines: {node: '>=18'}
@@ -34043,9 +34085,9 @@ packages:
       globby: 11.1.0
       joycon: 3.1.1
       postcss: 8.4.27
-      postcss-load-config: 4.0.1(postcss@8.4.27)
+      postcss-load-config: 4.0.1(postcss@8.4.27)(ts-node@10.9.2)
       resolve-from: 5.0.0
-      rollup: 4.6.1
+      rollup: 4.13.2
       source-map: 0.8.0-beta.0
       sucrase: 3.32.0
       tree-kill: 1.2.2
@@ -34055,47 +34097,6 @@ packages:
       - ts-node
     patched: true
 
-  /tsup@8.0.1(patch_hash=a5ztaafw5l4qfghy2hjjuynb34)(postcss@8.4.27)(typescript@5.3.3):
-    resolution: {integrity: sha512-hvW7gUSG96j53ZTSlT4j/KL0q1Q2l6TqGBFc6/mu/L46IoNWqLLUzLRLP1R8Q7xrJTmkDxxDoojV5uCVs1sVOg==}
-    engines: {node: '>=18'}
-    hasBin: true
-    peerDependencies:
-      '@microsoft/api-extractor': ^7.36.0
-      '@swc/core': ^1
-      postcss: ^8.4.12
-      typescript: '>=4.5.0'
-    peerDependenciesMeta:
-      '@microsoft/api-extractor':
-        optional: true
-      '@swc/core':
-        optional: true
-      postcss:
-        optional: true
-      typescript:
-        optional: true
-    dependencies:
-      bundle-require: 4.0.1(esbuild@0.19.11)
-      cac: 6.7.14
-      chokidar: 3.5.3
-      debug: 4.3.4(supports-color@8.1.1)
-      esbuild: 0.19.11
-      execa: 5.1.1
-      globby: 11.1.0
-      joycon: 3.1.1
-      postcss: 8.4.27
-      postcss-load-config: 4.0.1(postcss@8.4.27)
-      resolve-from: 5.0.0
-      rollup: 4.6.1
-      source-map: 0.8.0-beta.0
-      sucrase: 3.32.0
-      tree-kill: 1.2.2
-      typescript: 5.3.3
-    transitivePeerDependencies:
-      - supports-color
-      - ts-node
-    dev: true
-    patched: true
-
   /tsup@8.0.1(patch_hash=a5ztaafw5l4qfghy2hjjuynb34)(postcss@8.4.27)(typescript@5.4.5):
     resolution: {integrity: sha512-hvW7gUSG96j53ZTSlT4j/KL0q1Q2l6TqGBFc6/mu/L46IoNWqLLUzLRLP1R8Q7xrJTmkDxxDoojV5uCVs1sVOg==}
     engines: {node: '>=18'}
@@ -34124,9 +34125,9 @@ packages:
       globby: 11.1.0
       joycon: 3.1.1
       postcss: 8.4.27
-      postcss-load-config: 4.0.1(postcss@8.4.27)
+      postcss-load-config: 4.0.1(postcss@8.4.27)(ts-node@10.9.2)
       resolve-from: 5.0.0
-      rollup: 4.6.1
+      rollup: 4.13.2
       source-map: 0.8.0-beta.0
       sucrase: 3.32.0
       tree-kill: 1.2.2
@@ -34165,7 +34166,7 @@ packages:
       globby: 11.1.0
       joycon: 3.1.1
       postcss: 8.4.27
-      postcss-load-config: 4.0.1(postcss@8.4.27)
+      postcss-load-config: 4.0.1(postcss@8.4.27)(ts-node@10.9.2)
       resolve-from: 5.0.0
       rollup: 4.6.1
       source-map: 0.8.0-beta.0
@@ -35883,7 +35884,7 @@ packages:
         optional: true
     dependencies:
       '@types/eslint-scope': 3.7.4
-      '@types/estree': 1.0.2
+      '@types/estree': 1.0.5
       '@webassemblyjs/ast': 1.11.5
       '@webassemblyjs/wasm-edit': 1.11.5
       '@webassemblyjs/wasm-parser': 1.11.5
@@ -35922,7 +35923,7 @@ packages:
         optional: true
     dependencies:
       '@types/eslint-scope': 3.7.4
-      '@types/estree': 1.0.2
+      '@types/estree': 1.0.5
       '@webassemblyjs/ast': 1.11.5
       '@webassemblyjs/wasm-edit': 1.11.5
       '@webassemblyjs/wasm-parser': 1.11.5

references/v3-catalog/package.json

@@ -5,7 +5,9 @@
   "scripts": {
     "dev:trigger": "triggerdev dev",
     "management": "ts-node -r tsconfig-paths/register ./src/management.ts",
-    "queues": "ts-node -r tsconfig-paths/register ./src/queues.ts"
+    "queues": "ts-node -r tsconfig-paths/register ./src/queues.ts",
+    "build:client": "tsup-node ./src/clientUsage.ts --format esm,cjs",
+    "client": "ts-node -r dotenv/config -r tsconfig-paths/register ./src/clientUsage.ts"
   },
   "dependencies": {
     "@ffmpeg-installer/ffmpeg": "^1.1.0",
@@ -53,6 +55,8 @@
     "trigger.dev": "workspace:*",
     "ts-node": "^10.9.2",
     "tsconfig-paths": "^4.2.0",
-    "typescript": "^5.3.0"
+    "typescript": "^5.3.0",
+    "esbuild": "^0.19.11",
+    "tsup": "^8.0.1"
   }
-}
+}

references/v3-catalog/src/clientUsage.ts

@@ -0,0 +1,66 @@
+import { tasks, runs, TaskOutput, TaskPayload, TaskIdentifier } from "@trigger.dev/sdk/v3";
+import { createJsonHeroDoc } from "./trigger/simple";
+import { TaskOutputHandle } from "@trigger.dev/sdk/v3/shared";
+
+type createJsonHeroDocPayload = TaskPayload<typeof createJsonHeroDoc>; // retrieves the payload type of the task
+type createJsonHeroDocOutput = TaskOutput<typeof createJsonHeroDoc>; // retrieves the output type of the task
+type createJsonHeroDocIdentifier = TaskIdentifier<typeof createJsonHeroDoc>; // retrieves the identifier of the task
+type createJsonHeroDocHandle = TaskOutputHandle<typeof createJsonHeroDoc>; // retrieves the handle of the task
+
+async function main() {
+  const anyHandle = await tasks.trigger("create-jsonhero-doc", {
+    title: "Hello World",
+    content: {
+      message: "Hello, World!",
+    },
+  });
+
+  const anyRun = await runs.retrieve(anyHandle);
+
+  console.log(`Run ${anyHandle.id} completed with output:`, anyRun.output);
+
+  const handle = await tasks.trigger<typeof createJsonHeroDoc>("create-jsonhero-doc", {
+    title: "Hello World",
+    content: {
+      message: "Hello, World!",
+    },
+  });
+
+  console.log(handle);
+
+  const completedRun = await runs.poll(handle, { pollIntervalMs: 100 });
+
+  console.log(`Run ${handle.id} completed with output:`, completedRun.output);
+
+  const run = await tasks.triggerAndPoll<typeof createJsonHeroDoc>("create-jsonhero-doc", {
+    title: "Hello World",
+    content: {
+      message: "Hello, World!",
+    },
+  });
+
+  console.log(`Run ${run.id} completed with output: `, run.output);
+
+  const batchHandle = await tasks.batchTrigger<typeof createJsonHeroDoc>("create-jsonhero-doc", [
+    {
+      payload: {
+        title: "Hello World",
+        content: {
+          message: "Hello, World!",
+        },
+      },
+    },
+    {
+      payload: {
+        title: "Hello World 2",
+        content: {
+          message: "Hello, World 2!",
+        },
+      },
+    },
+  ]);
+
+  const run2 = await runs.retrieve(batchHandle.runs[0]);
+}
+
+main().catch(console.error);

references/v3-catalog/src/trigger/simple.ts

@@ -54,7 +54,7 @@ export const createJsonHeroDoc = task({
 
     const json: any = await response.json();
 
-    return json;
+    return json as { id: string; title: string; location: string };
   },
 });
 

references/v3-catalog/src/trigger/subtasks.ts

@@ -1,4 +1,4 @@
-import { logger, task, wait } from "@trigger.dev/sdk/v3";
+import { logger, task, wait, tasks } from "@trigger.dev/sdk/v3";
 import { taskWithRetries } from "./retries";
 
 export const simpleParentTask = task({
@@ -114,7 +114,7 @@ export const triggerAndWaitLoops = task({
       ]);
     }
 
-    await taskWithNoPayload.trigger();
+    const handle = await taskWithNoPayload.trigger();
     await taskWithNoPayload.triggerAndWait();
     await taskWithNoPayload.batchTrigger([{}]);
     await taskWithNoPayload.batchTriggerAndWait([{}]);