@trigger.dev/sdk 4.5.0-rc.5 → 4.5.0-rc.7

package/docs/realtime/react-hooks/swr.mdx

@@ -0,0 +1,87 @@
+---
+title: SWR hooks
+sidebarTitle: SWR
+description: Fetch and cache data using SWR-based hooks
+---
+
+SWR hooks use the [swr](https://swr.vercel.app/) library to fetch data once and cache it. These hooks are useful when you need to fetch data without real-time updates.
+
+<Note>
+  While SWR can be configured to poll for updates, we recommend using our other [Realtime
+  hooks](/realtime/react-hooks/) for most use-cases due to rate-limits and the way the Trigger.dev
+  API works.
+</Note>
+
+## useRun
+
+The `useRun` hook allows you to fetch a run by its ID.
+
+```tsx
+"use client"; // This is needed for Next.js App Router or other RSC frameworks
+
+import { useRun } from "@trigger.dev/react-hooks";
+
+export function MyComponent({ runId }: { runId: string }) {
+  const { run, error, isLoading } = useRun(runId);
+
+  if (isLoading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+
+  return <div>Run: {run.id}</div>;
+}
+```
+
+The `run` object returned is the same as the [run object](/management/runs/retrieve) returned by the Trigger.dev API. To correctly type the run's payload and output, you can provide the type of your task to the `useRun` hook:
+
+```tsx
+import { useRun } from "@trigger.dev/react-hooks";
+import type { myTask } from "@/trigger/myTask";
+
+export function MyComponent({ runId }: { runId: string }) {
+  const { run, error, isLoading } = useRun<typeof myTask>(runId, {
+    refreshInterval: 0, // Disable polling
+  });
+
+  if (isLoading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+
+  // Now run.payload and run.output are correctly typed
+
+  return <div>Run: {run.id}</div>;
+}
+```
+
+## Common SWR options
+
+You can pass the following options to the all SWR hooks:
+
+<ParamField path="revalidateOnFocus" type="boolean">
+  Revalidate the data when the window regains focus.
+</ParamField>
+
+<ParamField path="revalidateOnReconnect" type="boolean">
+  Revalidate the data when the browser regains a network connection.
+</ParamField>
+
+<ParamField path="refreshInterval" type="number">
+  Poll for updates at the specified interval (in milliseconds). Polling is not recommended for most
+  use-cases. Use the Realtime hooks instead.
+</ParamField>
+
+## Common SWR return values
+
+<ResponseField name="error" type="Error">
+  An error object if an error occurred while fetching the data.
+</ResponseField>
+
+<ResponseField name="isLoading" type="boolean">
+  A boolean indicating if the data is currently being fetched.
+</ResponseField>
+
+<ResponseField name="isValidating" type="boolean">
+  A boolean indicating if the data is currently being revalidated.
+</ResponseField>
+
+<ResponseField name="isError" type="boolean">
+  A boolean indicating if an error occurred while fetching the data.
+</ResponseField>{" "}

package/docs/realtime/react-hooks/triggering.mdx

@@ -0,0 +1,194 @@
+---
+title: "Trigger tasks from React"
+sidebarTitle: Triggering
+description: "Trigger background tasks from React components and optionally subscribe to their progress or stream their output."
+---
+
+Trigger tasks directly from your React components. You can fire-and-forget, or trigger and immediately subscribe to the run's progress or streamed output.
+
+<Note>
+  For triggering tasks from your frontend, you need to use “trigger” tokens. These can only be used
+  once to trigger a task and are more secure than regular Public Access Tokens. To learn more about
+  how to create and use these tokens, see our [Trigger
+  Tokens](/realtime/auth#trigger-tokens-for-frontend-triggering-only) documentation.
+</Note>
+
+## Hooks
+
+We provide three hooks for triggering tasks from your frontend application:
+
+- `useTaskTrigger` - Trigger a task from your frontend application.
+- `useRealtimeTaskTrigger` - Trigger a task from your frontend application and subscribe to the run.
+- `useRealtimeTaskTriggerWithStreams` - Trigger a task from your frontend application and subscribe to the run, and also receive any streams that are emitted by the task.
+
+### useTaskTrigger
+
+The `useTaskTrigger` hook allows you to trigger a task from your frontend application.
+
+```tsx
+"use client"; // This is needed for Next.js App Router or other RSC frameworks
+
+import { useTaskTrigger } from "@trigger.dev/react-hooks";
+import type { myTask } from "@/trigger/myTask";
+//     👆 This is the type of your task, include this to get type-safety
+
+export function MyComponent({ publicAccessToken }: { publicAccessToken: string }) {
+  //                         pass the type of your task here 👇
+  const { submit, handle, error, isLoading } = useTaskTrigger<typeof myTask>("my-task", {
+    accessToken: publicAccessToken, // 👈 this is the "trigger" token
+  });
+
+  if (error) {
+    return <div>Error: {error.message}</div>;
+  }
+
+  if (handle) {
+    return <div>Run ID: {handle.id}</div>;
+  }
+
+  return (
+    <button onClick={() => submit({ foo: "bar" })} disabled={isLoading}>
+      {isLoading ? "Loading..." : "Trigger Task"}
+    </button>
+  );
+}
+```
+
+`useTaskTrigger` returns an object with the following properties:
+
+- `submit`: A function that triggers the task. It takes the payload of the task as an argument.
+- `handle`: The run handle object. This object contains the ID of the run that was triggered, along with a Public Access Token that can be used to access the run.
+- `isLoading`: A boolean that indicates whether the task is currently being triggered.
+- `error`: An error object that contains any errors that occurred while triggering the task.
+
+The `submit` function triggers the task with the specified payload. You can additionally pass an optional [options](/triggering#options) argument to the `submit` function:
+
+```tsx
+submit({ foo: "bar" }, { tags: ["tag1", "tag2"] });
+```
+
+#### Using the handle object
+
+You can use the `handle` object to initiate a subsequent [Realtime hook](/realtime/react-hooks/subscribe#userealtimerun) to subscribe to the run.
+
+```tsx
+"use client"; // This is needed for Next.js App Router or other RSC frameworks
+
+import { useTaskTrigger, useRealtimeRun } from "@trigger.dev/react-hooks";
+import type { myTask } from "@/trigger/myTask";
+//     👆 This is the type of your task
+
+export function MyComponent({ publicAccessToken }: { publicAccessToken: string }) {
+  //                         pass the type of your task here 👇
+  const { submit, handle, error, isLoading } = useTaskTrigger<typeof myTask>("my-task", {
+    accessToken: publicAccessToken, // 👈 this is the "trigger" token
+  });
+
+  //     use the handle object to preserve type-safety 👇
+  const { run, error: realtimeError } = useRealtimeRun(handle, {
+    accessToken: handle?.publicAccessToken,
+    enabled: !!handle, // Only subscribe to the run if the handle is available
+  });
+
+  if (error) {
+    return <div>Error: {error.message}</div>;
+  }
+
+  if (handle) {
+    return <div>Run ID: {handle.id}</div>;
+  }
+
+  if (realtimeError) {
+    return <div>Error: {realtimeError.message}</div>;
+  }
+
+  if (run) {
+    return <div>Run ID: {run.id}</div>;
+  }
+
+  return (
+    <button onClick={() => submit({ foo: "bar" })} disabled={isLoading}>
+      {isLoading ? "Loading..." : "Trigger Task"}
+    </button>
+  );
+}
+```
+
+We've also created some additional hooks that allow you to trigger tasks and subscribe to the run in one step:
+
+### useRealtimeTaskTrigger
+
+The `useRealtimeTaskTrigger` hook allows you to trigger a task from your frontend application and then subscribe to the run in using Realtime:
+
+```tsx
+"use client"; // This is needed for Next.js App Router or other RSC frameworks
+
+import { useRealtimeTaskTrigger } from "@trigger.dev/react-hooks";
+import type { myTask } from "@/trigger/myTask";
+
+export function MyComponent({ publicAccessToken }: { publicAccessToken: string }) {
+  const { submit, run, error, isLoading } = useRealtimeTaskTrigger<typeof myTask>("my-task", {
+    accessToken: publicAccessToken,
+  });
+
+  if (error) {
+    return <div>Error: {error.message}</div>;
+  }
+
+  // This is the Realtime run object, which will automatically update when the run changes
+  if (run) {
+    return <div>Run ID: {run.id}</div>;
+  }
+
+  return (
+    <button onClick={() => submit({ foo: "bar" })} disabled={isLoading}>
+      {isLoading ? "Loading..." : "Trigger Task"}
+    </button>
+  );
+}
+```
+
+### useRealtimeTaskTriggerWithStreams
+
+The `useRealtimeTaskTriggerWithStreams` hook allows you to trigger a task from your frontend application and then subscribe to the run in using Realtime, and also receive any streams that are emitted by the task.
+
+```tsx
+"use client"; // This is needed for Next.js App Router or other RSC frameworks
+
+import { useRealtimeTaskTriggerWithStreams } from "@trigger.dev/react-hooks";
+import type { myTask } from "@/trigger/myTask";
+
+type STREAMS = {
+  openai: string; // this is the type of each "part" of the stream
+};
+
+export function MyComponent({ publicAccessToken }: { publicAccessToken: string }) {
+  const { submit, run, streams, error, isLoading } = useRealtimeTaskTriggerWithStreams<
+    typeof myTask,
+    STREAMS
+  >("my-task", {
+    accessToken: publicAccessToken,
+  });
+
+  if (error) {
+    return <div>Error: {error.message}</div>;
+  }
+
+  if (streams && run) {
+    const text = streams.openai?.map((part) => part).join("");
+
+    return (
+      <div>
+        <div>Run ID: {run.id}</div>
+        <div>{text}</div>
+      </div>
+    );
+  }
+
+  return (
+    <button onClick={() => submit({ foo: "bar" })} disabled={isLoading}>
+      {isLoading ? "Loading..." : "Trigger Task"}
+    </button>
+  );
+}
+```

package/docs/realtime/react-hooks/use-wait-token.mdx

@@ -0,0 +1,34 @@
+---
+title: useWaitToken
+description: Use the useWaitToken hook to complete a wait token from a React component
+---
+
+We've added a new `useWaitToken` react hook that allows you to complete a wait token from a React component, using a Public Access Token.
+
+```ts backend.ts
+import { wait } from "@trigger.dev/sdk";
+
+// Somewhere in your code, you'll need to create the token and then pass the token ID and the public token to the frontend
+const token = await wait.createToken({
+  timeout: "10m",
+});
+
+return {
+  tokenId: token.id,
+  publicToken: token.publicAccessToken, // An automatically generated public access token that expires in 1 hour
+};
+```
+
+Now you can use the `useWaitToken` hook in your frontend code:
+
+```tsx frontend.tsx
+import { useWaitToken } from "@trigger.dev/react-hooks";
+
+export function MyComponent({ publicToken, tokenId }: { publicToken: string; tokenId: string }) {
+  const { complete } = useWaitToken(tokenId, {
+    accessToken: publicToken,
+  });
+
+  return <button onClick={() => complete({ foo: "bar" })}>Complete</button>;
+}
+```

package/docs/realtime/run-object.mdx

@@ -0,0 +1,174 @@
+---
+title: "The run object"
+sidebarTitle: "The run object"
+description: "The run object schema for Realtime subscriptions"
+---
+
+The [run object](/realtime/run-object#the-run-object) is the main object returned by Realtime subscriptions (e.g., `runs.subscribeToRun()`). It contains all the information about the run, including the run ID, task identifier, payload, output, and more.
+
+Type-safety is supported for the run object, so you can infer the types of the run's payload and output. See [type-safety](#type-safety) for more information.
+
+## The run object
+
+### Properties
+
+<ParamField path="id" type="string" required>
+  The run ID.
+</ParamField>
+
+<ParamField path="taskIdentifier" type="string" required>
+  The task identifier.
+</ParamField>
+
+<ParamField path="payload" type="object" required>
+  The input payload for the run.
+</ParamField>
+
+<ParamField path="output" type="object">
+  The output result of the run.
+</ParamField>
+
+<ParamField path="createdAt" type="Date" required>
+  Timestamp when the run was created.
+</ParamField>
+
+<ParamField path="updatedAt" type="Date" required>
+  Timestamp when the run was last updated.
+</ParamField>
+
+<ParamField path="number" type="number" required>
+  Sequential number assigned to the run.
+</ParamField>
+
+<ParamField path="status" type="RunStatus" required>
+  Current status of the run.
+
+  <Accordion title="RunStatus enum">
+
+| Status               | Description                                                                                               |
+| -------------------- | --------------------------------------------------------------------------------------------------------- |
+| `WAITING_FOR_DEPLOY` | Task hasn't been deployed yet but is waiting to be executed                                               |
+| `QUEUED`             | Run is waiting to be executed by a worker                                                                 |
+| `EXECUTING`          | Run is currently being executed by a worker                                                               |
+| `REATTEMPTING`       | Run has failed and is waiting to be retried                                                               |
+| `FROZEN`             | Run has been paused by the system, and will be resumed by the system                                      |
+| `COMPLETED`          | Run has been completed successfully                                                                       |
+| `CANCELED`           | Run has been canceled by the user                                                                         |
+| `FAILED`             | Run has been completed with errors                                                                        |
+| `CRASHED`            | Run has crashed and won't be retried, most likely the worker ran out of resources, e.g. memory or storage |
+| `INTERRUPTED`        | Run was interrupted during execution, mostly this happens in development environments                     |
+| `SYSTEM_FAILURE`     | Run has failed to complete, due to an error in the system                                                 |
+| `DELAYED`            | Run has been scheduled to run at a specific time                                                          |
+| `EXPIRED`            | Run has expired and won't be executed                                                                     |
+| `TIMED_OUT`          | Run has reached it's maxDuration and has been stopped                                                     |
+
+</Accordion>
+</ParamField>
+
+<ParamField path="durationMs" type="number" required>
+  Duration of the run in milliseconds.
+</ParamField>
+
+<ParamField path="costInCents" type="number" required>
+  Total cost of the run in cents.
+</ParamField>
+
+<ParamField path="baseCostInCents" type="number" required>
+  Base cost of the run in cents before any additional charges.
+</ParamField>
+
+<ParamField path="tags" type="string[]" required>
+  Array of tags associated with the run.
+</ParamField>
+
+<ParamField path="idempotencyKey" type="string">
+  Key used to ensure idempotent execution.
+</ParamField>
+
+<ParamField path="expiredAt" type="Date">
+  Timestamp when the run expired.
+</ParamField>
+
+<ParamField path="ttl" type="string">
+  Time-to-live duration for the run.
+</ParamField>
+
+<ParamField path="finishedAt" type="Date">
+  Timestamp when the run finished.
+</ParamField>
+
+<ParamField path="startedAt" type="Date">
+  Timestamp when the run started.
+</ParamField>
+
+<ParamField path="delayedUntil" type="Date">
+  Timestamp until which the run is delayed.
+</ParamField>
+
+<ParamField path="queuedAt" type="Date">
+  Timestamp when the run was queued.
+</ParamField>
+
+<ParamField path="metadata" type="Record<string, DeserializedJson>">
+  Additional metadata associated with the run.
+</ParamField>
+
+<ParamField path="error" type="SerializedError">
+  Error information if the run failed.
+</ParamField>
+
+<ParamField path="isTest" type="boolean" required>
+  Indicates whether this is a test run.
+</ParamField>
+
+## Type-safety
+
+You can infer the types of the run's payload and output by passing the type of the task to the `subscribeToRun` function. This will give you type-safe access to the run's payload and output.
+
+```ts
+import { runs, tasks } from "@trigger.dev/sdk";
+import type { myTask } from "./trigger/my-task";
+
+// Somewhere in your backend code
+async function myBackend() {
+  const handle = await tasks.trigger("my-task", { some: "data" });
+
+  for await (const run of runs.subscribeToRun<typeof myTask>(handle.id)) {
+    // This will log the run every time it changes
+    console.log(run.payload.some);
+
+    if (run.output) {
+      // This will log the output if it exists
+      console.log(run.output.some);
+    }
+  }
+}
+```
+
+When using `subscribeToRunsWithTag`, you can pass a union of task types for all the possible tasks that can have the tag.
+
+```ts
+import { runs } from "@trigger.dev/sdk";
+import type { myTask, myOtherTask } from "./trigger/my-task";
+
+// Somewhere in your backend code
+for await (const run of runs.subscribeToRunsWithTag<typeof myTask | typeof myOtherTask>("my-tag")) {
+  // You can narrow down the type based on the taskIdentifier
+  switch (run.taskIdentifier) {
+    case "my-task": {
+      console.log("Run output:", run.output.foo); // This will be type-safe
+      break;
+    }
+    case "my-other-task": {
+      console.log("Run output:", run.output.bar); // This will be type-safe
+      break;
+    }
+  }
+}
+```
+
+This works with all realtime subscription functions:
+
+- `runs.subscribeToRun<TaskType>()`
+- `runs.subscribeToRunsWithTag<TaskType>()`
+- `runs.subscribeToBatch<TaskType>()`

package/docs/replaying.mdx

@@ -0,0 +1,72 @@
+---
+title: "Replaying"
+description: "A replay is a copy of a run with the same payload but against the latest version in that environment. This is useful if something went wrong and you want to try again with the latest version of your code."
+---
+
+### Replaying from the UI
+
+<Tabs>
+  <Tab title="From a run">
+    <Steps>
+      <Step title="Click the Replay button in the top right">
+        ![Select a task, then in the bottom right
+        click "Replay"](/images/replay-run-action.png)
+      </Step>
+      <Step title="Confirm replay settings">
+        You can edit the payload <Icon icon="circle-1" iconType="solid" size={20} color="F43F47" /> (if available) and choose the environment <Icon icon="circle-2" iconType="solid" size={20} color="F43F47" /> to replay the run in.
+        
+        ![Select a task, then in the bottom right
+        click "Replay"](/images/replay-run-modal.png)
+      </Step>
+    </Steps>
+  </Tab>
+  <Tab title="Runs list">
+    <Steps>
+      <Step title="Click the action button on a run">
+        ![On the runs page, press the triple dot button](/images/replay-runs-list.png)
+      </Step>
+      <Step title="Click replay">![Click replay](/images/replay-runs-list-popover.png)</Step>
+    </Steps>
+  </Tab>
+</Tabs>
+
+### Detecting replays in your task
+
+You can check if a run is a replay using the [context](/context) object:
+
+```ts
+export const myTask = task({
+  id: "my-task",
+  run: async (payload, { ctx }) => {
+    if (ctx.run.isReplay) {
+      // This run is a replay of a previous run
+    }
+  },
+});
+```
+
+### Replaying using the SDK
+
+You can replay a run using the SDK:
+
+```ts
+const replayedRun = await runs.replay(run.id);
+```
+
+When you call `trigger()` or `batchTrigger()` on a task you receive back a run handle which has an `id` property. You can use that `id` to replay the run.
+
+You can also access the run id from inside a run. You could write this to your database and then replay it later.
+
+```ts
+export const simpleChildTask = task({
+  id: "simple-child-task",
+  run: async (payload, { ctx }) => {
+    // the run ID (and other useful info) is in ctx
+    const runId = ctx.run.id;
+  },
+});
+```
+
+### Bulk replaying
+
+See [Bulk actions](/bulk-actions) for more information.

package/docs/request-feature.mdx

@@ -0,0 +1,6 @@
+---
+title: "Request a feature"
+url: "https://feedback.trigger.dev/"
+---
+
+If you have a feature request or idea for Trigger, we'd love to hear it! You can submit your ideas on our [public roadmap](https://feedback.trigger.dev/). We're always looking for feedback on what to build next, so feel free to submit your ideas or vote on existing ones.

package/docs/roadmap.mdx

@@ -0,0 +1,6 @@
+---
+title: "Roadmap"
+url: "https://feedback.trigger.dev/roadmap"
+---
+
+See what's coming up next on our [public roadmap](https://feedback.trigger.dev/roadmap). We're always looking for feedback on what to build next, so feel free to submit your ideas or vote on existing ones. 

package/docs/run-tests.mdx

@@ -0,0 +1,20 @@
+---
+title: "Run tests"
+description: "You can use the dashboard to run a test of your tasks."
+---
+
+From the "Test" page in the side menu of the dashboard you can run a test for any of your tasks from any environment.
+
+![Select an environment](/images/test-dashboard.png)
+
+<Icon icon="circle-1" iconType="solid" color="#FF2D6B" size="20" /> Select a task to test
+
+<Icon icon="circle-2" iconType="solid" color="#FF2D6B" size="20" /> Include a payload or metadata
+
+<Icon icon="circle-3" iconType="solid" color="#FF2D6B" size="20" /> Configure any additional options like the machine size, queue or delay
+
+<Icon icon="circle-4" iconType="solid" color="#FF2D6B" size="20" /> Select from previous test runs
+
+<Icon icon="circle-5" iconType="solid" color="#FF2D6B" size="20" /> Save the current test configuration as a template for later
+
+<Icon icon="circle-6" iconType="solid" color="#FF2D6B" size="20" /> Run the test