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

package/docs/queues.mdx

@@ -0,0 +1,271 @@
+---
+title: "Queues"
+description: "Control the order your runs execute in."
+---
+
+import Priority from "/snippets/priority.mdx";
+
+When you trigger a task, it isn't executed immediately. Instead, the task [run](/runs) is placed into a queue for execution. Runs in a queue are started in the order they were triggered, first in, first out, unless you give a run a [priority](#priority) at trigger time.
+
+By default, each task gets its own queue, so triggering the same task ten times executes those runs in trigger order. How many of them execute *at once* is a separate question, governed by [concurrency](/concurrency) — your environment's concurrency limit, plus any limits you set on the task.
+
+## Sharing a queue between tasks
+
+Declare a queue with `queue()` and set it on several tasks to interleave their runs in one queue. Runs from every task on the queue start in the order they were triggered, whichever task they belong to:
+
+```ts /trigger/emails.ts
+import { queue, task } from "@trigger.dev/sdk";
+
+const emailQueue = queue({ name: "emails" });
+
+export const sendWelcomeEmail = task({
+  id: "send-welcome-email",
+  queue: emailQueue,
+  run: async (payload) => {
+    //...
+  },
+});
+
+export const sendDigestEmail = task({
+  id: "send-digest-email",
+  queue: emailQueue,
+  run: async (payload) => {
+    //...
+  },
+});
+```
+
+<Note>
+  If what you want to share is a concurrency cap rather than ordering, you don't need a shared
+  queue: declare a named limit with `concurrencyLimit()` and each task keeps its own queue while
+  drawing from the shared limit. See [sharing a limit between
+  tasks](/concurrency#sharing-a-limit-between-tasks).
+</Note>
+
+Queue names can use letters, numbers, underscores, hyphens and slashes, up to 128 characters. Names starting with `limit/` are reserved for [concurrency limits](/concurrency) and are rejected at deploy time.
+
+## Setting the queue when you trigger a run
+
+When you trigger a task you can override its queue by name. This is really useful if you sometimes have high priority runs:
+
+```ts /trigger/override-queue.ts
+import { queue, task } from "@trigger.dev/sdk";
+
+const paidQueue = queue({ name: "paid-users" });
+
+export const generatePullRequest = task({
+  id: "generate-pull-request",
+  // normally this task is limited to 1 run at a time
+  concurrency: { total: 1 },
+  run: async (payload) => {
+    //todo generate a PR using OpenAI
+  },
+});
+```
+
+Triggering from your backend and overriding the queue:
+
+```ts app/api/push/route.ts
+import { generatePullRequest } from "~/trigger/override-queue";
+
+export async function POST(request: Request) {
+  const data = await request.json();
+
+  if (data.branch === "main") {
+    //trigger the task, with the paid users queue
+    const handle = await generatePullRequest.trigger(data, {
+      // Set the paid users queue
+      queue: "paid-users",
+    });
+
+    return Response.json(handle);
+  } else {
+    //triggered with the default queue
+    const handle = await generatePullRequest.trigger(data);
+    return Response.json(handle);
+  }
+}
+```
+
+## Priority
+
+You can re-order runs within a queue at trigger time by giving them a priority:
+
+<Priority />
+
+## Archiving queues
+
+Queues are created when you deploy, so renaming a queue or deleting a task leaves its old queue behind. To tidy up the list, open the queue's menu on the Concurrency page in the dashboard and choose **Archive**.
+
+Archiving only hides the queue in the dashboard, and it doesn't affect runs. Archived queues don't count towards the **Allocated** total, even if they have runs. To see them, turn on the **Show archived** toggle; to bring one back, choose **Unarchive** from its menu.
+
+- You can only archive a queue that your current deployment no longer declares.
+- You can't archive a queue while it has runs waiting or in progress, or while it's paused or its concurrency limit or [`total` limit](/concurrency) is 0.
+- If an archived queue gets new runs, it stays hidden, but a warning above the list names it until it's empty.
+- Pausing an archived queue, or setting its concurrency limit or `total` limit to 0 (including by resetting an override), unarchives it.
+- If a later deploy declares the queue again, it's unarchived automatically.
+- The SDK and API still list archived queues.
+
+<Note>
+  Some runs belong to a queue without currently sitting in it, so they don't count as activity:
+  delayed runs that haven't reached their start time yet, runs waiting for a deploy of their
+  version, runs that are waiting (for example on `wait.for` or a child task) or have been
+  checkpointed, and, depending on how the engine is configured, runs with a concurrency key that
+  have been handed to a worker but not picked up yet. A queue with only runs like these can be
+  archived, and the warning won't name it until one of them is back in the queue or running. These
+  runs still execute normally and always show on the Runs page.
+</Note>
+
+## Managing queues with the SDK
+
+The SDK provides a `queues` namespace that allows you to manage queues programmatically. You can list, retrieve, pause, resume, and modify concurrency limits for queues.
+
+<Note>
+  Import from `@trigger.dev/sdk`:
+  ```ts
+  import { queues } from "@trigger.dev/sdk";
+  ```
+</Note>
+
+### Listing queues
+
+You can list all queues in your environment with pagination support:
+
+```ts
+import { queues } from "@trigger.dev/sdk";
+
+// List all queues (returns paginated results)
+const allQueues = await queues.list();
+
+// With pagination options
+const pagedQueues = await queues.list({
+  page: 1,
+  perPage: 20,
+});
+```
+
+### Retrieving a queue
+
+You can retrieve a specific queue by its ID, or by its type and name:
+
+```ts
+import { queues } from "@trigger.dev/sdk";
+
+// Using queue ID (starts with "queue_")
+const queueById = await queues.retrieve("queue_1234");
+
+// Using type and name for a task's default queue
+const taskQueue = await queues.retrieve({
+  type: "task",
+  name: "my-task-id",
+});
+
+// Using type and name for a custom queue
+const customQueue = await queues.retrieve({
+  type: "custom",
+  name: "my-custom-queue",
+});
+```
+
+The queue object contains useful information about the queue state, and its `version` discriminates the shape:
+
+```ts
+// V1: the queue carries its own concurrency limit and override state
+{
+  id: "queue_1234",       // Queue ID
+  name: "my-task-id",     // Queue name
+  type: "task",           // "task" or "custom"
+  version: "V1",
+  running: 5,             // Currently executing runs
+  queued: 10,             // Runs waiting to execute
+  paused: false,          // Whether the queue is paused
+  concurrencyLimit: 10,   // The queue's own limit
+  concurrency: {
+    current: 10,          // Effective limit
+    base: 10,             // Default limit from code
+    override: null,       // Override value (if set)
+    overriddenAt: null,   // When override was applied
+    overriddenBy: null,   // Who applied the override
+  }
+}
+
+// V2: the queue is only the line runs wait in. Concurrency is declared with
+// the task `concurrency` option and managed through `concurrencyLimits`.
+{
+  id: "queue_5678",
+  name: "my-v2-task-id",
+  type: "task",
+  version: "V2",
+  running: 3,
+  queued: 12,
+  paused: false,
+  concurrencyLimit: null,
+}
+```
+
+### Pausing and resuming queues
+
+You can pause a queue to prevent new runs from starting. Runs that are currently executing will continue to completion.
+
+```ts
+import { queues } from "@trigger.dev/sdk";
+
+// Pause a queue using its ID
+await queues.pause("queue_1234");
+
+// Or using type and name
+await queues.pause({ type: "task", name: "my-task-id" });
+await queues.pause({ type: "custom", name: "my-custom-queue" });
+```
+
+To resume a paused queue and allow new runs to start:
+
+```ts
+import { queues } from "@trigger.dev/sdk";
+
+// Resume a queue using its ID
+await queues.resume("queue_1234");
+
+// Or using type and name
+await queues.resume({ type: "task", name: "my-task-id" });
+await queues.resume({ type: "custom", name: "my-custom-queue" });
+```
+
+### Overriding concurrency limits
+
+<Warning>
+  `queues.overrideConcurrencyLimit` and `queues.resetConcurrencyLimit` are deprecated and only work
+  for queues on the legacy model, where the queue carried its own concurrency limit. On the current
+  model, declare concurrency with the task `concurrency` option and manage it through
+  [`concurrencyLimits`](/concurrency), e.g. `concurrencyLimits.override("task/my-task", { total: 10 })`
+  and `concurrencyLimits.reset("task/my-task")`. A legacy limit on a queue used with
+  `concurrencyKey` maps to `perKey` rather than `total`, and a limit on a custom queue shared by
+  several tasks maps to a named limit declared with `concurrencyLimit()`, again using `perKey`
+  when the queue receives keyed runs.
+</Warning>
+
+You can temporarily override a queue's concurrency limit. This is useful for scaling up or down based on demand:
+
+```ts
+import { queues } from "@trigger.dev/sdk";
+
+// Set concurrency limit to 5
+await queues.overrideConcurrencyLimit("queue_1234", 5);
+
+// Or using type and name
+await queues.overrideConcurrencyLimit({ type: "task", name: "my-task-id" }, 20);
+```
+
+To reset the concurrency limit back to the base value defined in your code:
+
+```ts
+import { queues } from "@trigger.dev/sdk";
+
+// Reset concurrency limit to the base value
+await queues.resetConcurrencyLimit("queue_1234");
+
+// Or using type and name
+await queues.resetConcurrencyLimit({ type: "task", name: "my-task-id" });
+```
+
+Overrides survive deploys: redeploying your code keeps an active override until you reset it.

package/docs/quick-start.mdx

@@ -0,0 +1,60 @@
+---
+title: "Quick start: add Trigger.dev to your project"
+sidebarTitle: "Quick start"
+description: "Set up Trigger.dev in your existing project in under 3 minutes. Install the SDK, create your first background task, and trigger it from your code."
+---
+
+import CliInitStep from "/snippets/step-cli-init.mdx";
+import CliDevStep from "/snippets/step-cli-dev.mdx";
+import CliRunTestStep from "/snippets/step-run-test.mdx";
+import CliViewRunStep from "/snippets/step-view-run.mdx";
+import AgentSetupPrompt from "/snippets/agent-setup-prompt.mdx";
+
+## Copy the setup prompt
+
+<AgentSetupPrompt />
+
+## Manual setup
+
+<Steps titleSize="h3">
+
+<Step title="Create a Trigger.dev account">
+
+Sign up at [Trigger.dev Cloud](https://cloud.trigger.dev) (or [self-host](/self-hosting/overview)). The onboarding flow will guide you through creating your first organization and project.
+
+</Step>
+
+<CliInitStep />
+<CliDevStep />
+<CliRunTestStep />
+<CliViewRunStep />
+
+</Steps>
+
+## Triggering tasks from your app
+
+The test page in the dashboard verifies that your task works. To trigger tasks from your own code, open the API Keys page for your Development environment and create a named key with **Trigger only** access. Set the key as `TRIGGER_SECRET_KEY` in your `.env` file.
+
+```bash .env
+TRIGGER_SECRET_KEY=tr_dev_sk_...
+```
+
+See [Triggering](/triggering) for the full guide, or jump straight to framework-specific setup for [Next.js](/guides/frameworks/nextjs), [Remix](/guides/frameworks/remix), or [Node.js](/guides/frameworks/nodejs).
+
+## Next steps
+
+<CardGroup cols={2}>
+<Card title="Building with AI" icon="brain" href="/building-with-ai">
+  Build Trigger.dev projects using AI coding assistants
+</Card>
+  <Card title="How to trigger your tasks" icon="bolt" href="/triggering">
+    Trigger tasks from your backend code
+  </Card>
+  <Card title="Writing tasks" icon="wand-magic-sparkles" href="/tasks/overview">
+    Task options, lifecycle hooks, retries, and queues
+  </Card>
+  <Card title="Guides and example projects" icon="books" href="/guides/introduction">
+  Framework guides and working example repos
+</Card>
+
+</CardGroup>

package/docs/realtime/auth.mdx

@@ -0,0 +1,228 @@
+---
+title: Realtime authentication
+sidebarTitle: Realtime auth
+description: Authenticating real-time API requests with Public Access Tokens or Trigger Tokens
+---
+
+To use the Realtime API, you need to authenticate your requests with Public Access Tokens or Trigger Tokens. These tokens provide secure, scoped access to your runs and can be used in both frontend and backend applications.
+
+## Token Types
+
+There are two types of tokens you can use with the Realtime API:
+
+- **[Public Access Tokens](#public-access-tokens-for-subscribing-to-runs)** - Used to read and subscribe to run data. Can be used in both the frontend and backend.
+- **[Trigger Tokens](#trigger-tokens-for-frontend-triggering-only)** - Used to trigger tasks from your frontend. These are more secure, single-use tokens that can only be used in the frontend.
+
+## Public Access Tokens (for subscribing to runs)
+
+Use Public Access Tokens to subscribe to runs and receive real-time updates in your frontend or backend.
+
+### Creating Public Access Tokens
+
+You can create a Public Access Token using the `auth.createPublicToken` function in your **backend** code:
+
+```tsx
+// Somewhere in your backend code
+import { auth } from "@trigger.dev/sdk";
+
+const publicToken = await auth.createPublicToken(); // 👈 this public access token has no permissions, so is pretty useless!
+```
+
+### Scopes
+
+By default a Public Access Token has no permissions. You must specify the scopes you need when creating a Public Access Token:
+
+```ts
+import { auth } from "@trigger.dev/sdk";
+
+const publicToken = await auth.createPublicToken({
+  scopes: {
+    read: {
+      runs: true, // ❌ this token can read all runs, possibly useful for debugging/testing
+    },
+  },
+});
+```
+
+This will allow the token to read all runs, which is probably not what you want. You can specify only certain runs by passing an array of run IDs:
+
+```ts
+import { auth } from "@trigger.dev/sdk";
+
+const publicToken = await auth.createPublicToken({
+  scopes: {
+    read: {
+      runs: ["run_1234", "run_5678"], // ✅ this token can read only these runs
+    },
+  },
+});
+```
+
+You can scope the token to only read certain tasks:
+
+```ts
+import { auth } from "@trigger.dev/sdk";
+
+const publicToken = await auth.createPublicToken({
+  scopes: {
+    read: {
+      tasks: ["my-task-1", "my-task-2"], // 👈 this token can read all runs of these tasks
+    },
+  },
+});
+```
+
+Or tags:
+
+```ts
+import { auth } from "@trigger.dev/sdk";
+
+const publicToken = await auth.createPublicToken({
+  scopes: {
+    read: {
+      tags: ["my-tag-1", "my-tag-2"], // 👈 this token can read all runs with these tags
+    },
+  },
+});
+```
+
+Or a specific batch of runs:
+
+```ts
+import { auth } from "@trigger.dev/sdk";
+
+const publicToken = await auth.createPublicToken({
+  scopes: {
+    read: {
+      batch: "batch_1234", // 👈 this token can read all runs in this batch
+    },
+  },
+});
+```
+
+You can also combine scopes. For example, to read runs with specific tags and for specific tasks:
+
+```ts
+import { auth } from "@trigger.dev/sdk";
+
+const publicToken = await auth.createPublicToken({
+  scopes: {
+    read: {
+      tasks: ["my-task-1", "my-task-2"],
+      tags: ["my-tag-1", "my-tag-2"],
+    },
+  },
+});
+```
+
+### Expiration
+
+By default, Public Access Token's expire after 15 minutes. You can specify a different expiration time when creating a Public Access Token:
+
+```ts
+import { auth } from "@trigger.dev/sdk";
+
+const publicToken = await auth.createPublicToken({
+  expirationTime: "1hr",
+});
+```
+
+- If `expirationTime` is a string, it will be treated as a time span
+- If `expirationTime` is a number, it will be treated as a Unix timestamp in **seconds**
+- If `expirationTime` is a `Date`, it will be treated as a date
+
+Public Access Tokens cannot expire more than 30 days in the future.
+
+The format used for a time span is the same as the [jose package](https://github.com/panva/jose), which is a number followed by a unit. Valid units are: "sec", "secs", "second", "seconds", "s", "minute", "minutes", "min", "mins", "m", "hour", "hours", "hr", "hrs", "h", "day", "days", "d", "week", "weeks", "w", "year", "years", "yr", "yrs", and "y". It is not possible to specify months. 365.25 days is used as an alias for a year. If the string is suffixed with "ago", or prefixed with a "-", the resulting time span gets subtracted from the current unix timestamp. A "from now" suffix can also be used for readability when adding to the current unix timestamp.
+
+### Refreshing an expired token
+
+A realtime stream subscription can outlive its token. Pass a `refreshAccessToken` callback and a subscription rejected with a 401/403 re-mints once and reconnects, instead of failing. With no refresher, auth errors stay terminal. Mint the fresh token from your backend, where your secret key lives:
+
+```tsx
+import { useRealtimeStream } from "@trigger.dev/react-hooks";
+
+const { parts } = useRealtimeStream<{ url: string }>(runId, "frames", {
+  accessToken,
+  refreshAccessToken: async () => {
+    const res = await fetch("/api/realtime-token"); // your backend calls auth.createPublicToken
+    return (await res.json()).token;
+  },
+});
+```
+
+`refreshAccessToken` is available on every realtime hook, and on `useApiClient` and `TriggerAuthContext` so hooks under a provider share one refresher.
+
+### Auto-generated tokens
+
+When you [trigger tasks](/triggering) from your backend, the `handle` received includes a `publicAccessToken` field. This token can be used to authenticate real-time requests in your frontend application.
+
+Auto-generated tokens expire after 1 hour and have a read scope for the specific run(s) that were triggered. For a different expiration or scopes, create a token yourself with [`auth.createPublicToken`](#creating-public-access-tokens).
+
+See our [triggering documentation](/triggering) for detailed examples of how to trigger tasks and get auto-generated tokens.
+
+<Note>
+**Where should I create tokens?** The standard pattern is to create tokens in your backend code (API route, server action) after triggering a task, then pass the token to your frontend. The `handle.publicAccessToken` returned by `tasks.trigger()` already does this for you. You rarely need to create tokens inside a task itself.
+</Note>
+
+### Subscribing to runs with Public Access Tokens
+
+Once you have a Public Access Token, you can use it to authenticate requests to the Realtime API in both backend and frontend applications.
+
+**Backend usage:** See our [backend documentation](/realtime/backend) for examples of what you can do with Realtime in your backend once you have authenticated with a token.
+
+**Frontend usage:** See our [React hooks documentation](/realtime/react-hooks) for examples of using tokens with frontend components.
+
+## Trigger Tokens (for frontend triggering only)
+
+For triggering tasks from your frontend, you need special "trigger" tokens. These tokens can only be used once to trigger a task and are more secure than regular Public Access Tokens.
+
+### Creating Trigger Tokens
+
+```ts
+import { auth } from "@trigger.dev/sdk";
+
+// Somewhere in your backend code
+const triggerToken = await auth.createTriggerPublicToken("my-task");
+```
+
+### Multiple tasks
+
+You can pass multiple tasks to create a token that can trigger multiple tasks:
+
+```ts
+import { auth } from "@trigger.dev/sdk";
+
+// Somewhere in your backend code
+const triggerToken = await auth.createTriggerPublicToken(["my-task-1", "my-task-2"]);
+```
+
+### Multiple use
+
+You can also create tokens that can be used multiple times:
+
+```ts
+import { auth } from "@trigger.dev/sdk";
+
+// Somewhere in your backend code
+const triggerToken = await auth.createTriggerPublicToken("my-task", {
+  multipleUse: true, // ❌ Use this with caution!
+});
+```
+
+### Expiration
+
+These tokens also expire, with the default expiration time being 15 minutes. You can specify a custom expiration time:
+
+```ts
+import { auth } from "@trigger.dev/sdk";
+
+// Somewhere in your backend code
+const triggerToken = await auth.createTriggerPublicToken("my-task", {
+  expirationTime: "24hr",
+});
+```
+
+### Triggering tasks from the frontend with Trigger Tokens
+
+Check out our [React hooks documentation](/realtime/react-hooks) for examples of how to use Trigger Tokens in your frontend applications.