@trigger.dev/sdk 0.0.0-python-preview-20250226140121 → 0.0.0-rc-4-8-0-20261021151928

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
+  });
+
+  //     pass the run ID and the task type to preserve type-safety 👇
+  const { run, error: realtimeError } = useRealtimeRun<typeof myTask>(handle?.id, {
+    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 24 hours
+};
+```
+
+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,197 @@
+---
+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="status" type="RunStatus" required>
+  Current status of the run.
+
+  <Accordion title="RunStatus enum">
+
+| Status            | Description                                                                                               |
+| ----------------- | --------------------------------------------------------------------------------------------------------- |
+| `PENDING_VERSION` | Run is waiting for a version update because it cannot execute without additional information              |
+| `QUEUED`          | Run is waiting to be executed by a worker                                                                 |
+| `DEQUEUED`        | Run has been dequeued and is being sent to a worker to start executing                                    |
+| `EXECUTING`       | Run is currently being executed by a worker                                                               |
+| `WAITING`         | 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 |
+| `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="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>
+
+<ParamField path="realtimeStreams" type="string[]" required>
+  Names of the Realtime streams on the run.
+</ParamField>
+
+<ParamField path="isQueued" type="boolean" required>
+  `true` if the run is queued, delayed or waiting for a version update.
+</ParamField>
+
+<ParamField path="isExecuting" type="boolean" required>
+  `true` if the run is dequeued or executing.
+</ParamField>
+
+<ParamField path="isWaiting" type="boolean" required>
+  `true` if the run is waiting.
+</ParamField>
+
+<ParamField path="isCompleted" type="boolean" required>
+  `true` if the run has finished, either successfully or with any failure status.
+</ParamField>
+
+<ParamField path="isFailed" type="boolean" required>
+  `true` if the run failed, crashed, hit a system failure, expired or timed out.
+</ParamField>
+
+<ParamField path="isSuccess" type="boolean" required>
+  `true` if the run completed successfully.
+</ParamField>
+
+<ParamField path="isCancelled" type="boolean" required>
+  `true` if the run was canceled.
+</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,97 @@
+---
+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 Your backend code
+import { runs } from "@trigger.dev/sdk";
+
+const replayedRun = await runs.replay(run.id);
+// { id: "run_cmv6ixfn30008ct9kegazjolu" }
+```
+
+The new run reuses the original run's payload, metadata, tags, queue, concurrency key, and machine. Pass options to override any of them for the new run:
+
+```ts Your backend code
+import { runs } from "@trigger.dev/sdk";
+
+const replayedRun = await runs.replay(run.id, {
+  payload: { userId: "user_456" },
+  metadata: { source: "replay" },
+  tags: ["replayed"],
+  machine: "large-1x",
+  delay: "10m",
+});
+```
+
+The options use the same names as [`trigger()` options](/triggering): `payload`, `metadata`, `tags`, `queue`, `concurrencyKey`, `machine`, `version`, `region`, `delay`, `ttl`, `idempotencyKey`, `idempotencyKeyTTL`, `maxAttempts`, `maxDuration`, and `priority`. If you leave out `payload`, `metadata`, `tags`, `queue`, `concurrencyKey`, or `machine`, the new run uses the original run's value. The other options fall back to the task's current defaults, and without `version` the replay runs on the current version. The replay always runs in the same environment as the original run.
+
+A `queue` must already exist in the environment, and a `version` must be a version deployed to it. Otherwise the replay fails with an error and no run is created.
+
+A replay starts a new run, so the API key or token you replay with needs permission to trigger the task as well as write access to the run.
+
+The SDK serializes a `payload` override the same way `trigger()` does, so values like `Date`, `BigInt`, `Map` and `Set` reach the task with their types.
+
+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.