@trigger.dev/sdk 4.5.10 → 4.5.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (79) hide show
  1. package/dist/commonjs/v3/ai.js +6 -19
  2. package/dist/commonjs/v3/ai.js.map +1 -1
  3. package/dist/commonjs/v3/auth.d.ts +3 -3
  4. package/dist/commonjs/v3/chat-client.d.ts +5 -4
  5. package/dist/commonjs/v3/chat-client.js +2 -6
  6. package/dist/commonjs/v3/chat-client.js.map +1 -1
  7. package/dist/commonjs/v3/chat.d.ts +7 -0
  8. package/dist/commonjs/v3/chat.js +137 -33
  9. package/dist/commonjs/v3/chat.js.map +1 -1
  10. package/dist/commonjs/v3/chat.test.js +637 -2
  11. package/dist/commonjs/v3/chat.test.js.map +1 -1
  12. package/dist/commonjs/v3/retry.d.ts +1 -1
  13. package/dist/commonjs/v3/retry.js +1 -2
  14. package/dist/commonjs/v3/retry.js.map +1 -1
  15. package/dist/commonjs/v3/runs.d.ts +2 -6
  16. package/dist/commonjs/v3/runs.js.map +1 -1
  17. package/dist/commonjs/v3/schedules/api.d.ts +8 -1
  18. package/dist/commonjs/v3/schedules/index.d.ts +11 -6
  19. package/dist/commonjs/v3/schedules/index.js +2 -0
  20. package/dist/commonjs/v3/schedules/index.js.map +1 -1
  21. package/dist/commonjs/v3/schedules/index.test.d.ts +1 -0
  22. package/dist/commonjs/v3/schedules/index.test.js +49 -0
  23. package/dist/commonjs/v3/schedules/index.test.js.map +1 -0
  24. package/dist/commonjs/v3/schedules/index.types.test.d.ts +1 -0
  25. package/dist/commonjs/v3/schedules/index.types.test.js +93 -0
  26. package/dist/commonjs/v3/schedules/index.types.test.js.map +1 -0
  27. package/dist/commonjs/v3/shared.d.ts +2 -3
  28. package/dist/commonjs/v3/shared.js +14 -0
  29. package/dist/commonjs/v3/shared.js.map +1 -1
  30. package/dist/commonjs/v3/test/mock-chat-agent.d.ts +1 -1
  31. package/dist/commonjs/v3/test/mock-chat-agent.js.map +1 -1
  32. package/dist/commonjs/v3/test/test-session-handle.d.ts +1 -31
  33. package/dist/commonjs/v3/test/test-session-handle.js +0 -2
  34. package/dist/commonjs/v3/test/test-session-handle.js.map +1 -1
  35. package/dist/commonjs/version.js +1 -1
  36. package/dist/esm/v3/ai.js +6 -19
  37. package/dist/esm/v3/ai.js.map +1 -1
  38. package/dist/esm/v3/auth.d.ts +3 -3
  39. package/dist/esm/v3/chat-client.d.ts +5 -4
  40. package/dist/esm/v3/chat-client.js +2 -6
  41. package/dist/esm/v3/chat-client.js.map +1 -1
  42. package/dist/esm/v3/chat.d.ts +7 -0
  43. package/dist/esm/v3/chat.js +137 -33
  44. package/dist/esm/v3/chat.js.map +1 -1
  45. package/dist/esm/v3/chat.test.js +637 -2
  46. package/dist/esm/v3/chat.test.js.map +1 -1
  47. package/dist/esm/v3/retry.d.ts +1 -1
  48. package/dist/esm/v3/retry.js +1 -2
  49. package/dist/esm/v3/retry.js.map +1 -1
  50. package/dist/esm/v3/runs.d.ts +2 -6
  51. package/dist/esm/v3/runs.js.map +1 -1
  52. package/dist/esm/v3/schedules/api.d.ts +8 -1
  53. package/dist/esm/v3/schedules/index.d.ts +11 -6
  54. package/dist/esm/v3/schedules/index.js +2 -0
  55. package/dist/esm/v3/schedules/index.js.map +1 -1
  56. package/dist/esm/v3/schedules/index.test.d.ts +1 -0
  57. package/dist/esm/v3/schedules/index.test.js +47 -0
  58. package/dist/esm/v3/schedules/index.test.js.map +1 -0
  59. package/dist/esm/v3/schedules/index.types.test.d.ts +1 -0
  60. package/dist/esm/v3/schedules/index.types.test.js +91 -0
  61. package/dist/esm/v3/schedules/index.types.test.js.map +1 -0
  62. package/dist/esm/v3/shared.d.ts +2 -3
  63. package/dist/esm/v3/shared.js +15 -1
  64. package/dist/esm/v3/shared.js.map +1 -1
  65. package/dist/esm/v3/test/mock-chat-agent.d.ts +1 -1
  66. package/dist/esm/v3/test/mock-chat-agent.js.map +1 -1
  67. package/dist/esm/v3/test/test-session-handle.d.ts +1 -31
  68. package/dist/esm/v3/test/test-session-handle.js +1 -1
  69. package/dist/esm/v3/test/test-session-handle.js.map +1 -1
  70. package/dist/esm/version.js +1 -1
  71. package/docs/ai/observability.mdx +174 -0
  72. package/docs/ai-chat/frontend.mdx +10 -9
  73. package/docs/ai-chat/overview.mdx +1 -1
  74. package/docs/apikeys.mdx +159 -27
  75. package/docs/realtime/auth.mdx +3 -1
  76. package/docs/self-hosting/env/supervisor.mdx +1 -0
  77. package/docs/self-hosting/env/webapp.mdx +7 -0
  78. package/docs/tasks/scheduled.mdx +45 -0
  79. package/package.json +3 -15
@@ -1 +1 @@
1
- {"version":3,"file":"test-session-handle.js","sourceRoot":"","sources":["../../../../src/v3/test/test-session-handle.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"test-session-handle.js","sourceRoot":"","sources":["../../../../src/v3/test/test-session-handle.ts"],"names":[],"mappings":"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"}
@@ -1,2 +1,2 @@
1
- export const VERSION = "4.5.10";
1
+ export const VERSION = "4.5.12";
2
2
  //# sourceMappingURL=version.js.map
@@ -0,0 +1,174 @@
1
+ ---
2
+ title: "LLM observability"
3
+ sidebarTitle: "LLM observability"
4
+ description: "Capture Vercel AI SDK calls in a task as spans in the run trace, with model, token usage, cost, and latency. Opt in per call, link calls to prompt versions, and query usage across runs."
5
+ ---
6
+
7
+ **LLM observability turns a Vercel AI SDK call inside a task into its own span in the run trace, next to your logs and other spans.** Each span carries the model, provider, input, output, and total token counts, cost, and latency, so you can see what each generation did and what it cost without leaving the run.
8
+
9
+ Everything shows up inline in the run trace you already use to debug runs. There is no separate product and no dashboard to set up.
10
+
11
+ <Note>
12
+ Observability is opt-in per call and only covers [Vercel AI SDK](https://ai-sdk.dev) functions (`generateText`, `streamText`, `generateObject`). Calls you make with a raw `fetch`, a provider's own SDK, or any other HTTP client are not captured automatically.
13
+ </Note>
14
+
15
+ ## Turn it on
16
+
17
+ Set `experimental_telemetry: { isEnabled: true }` on the AI SDK call. There is nothing to install for AI SDK 6, and nothing to configure on the Trigger.dev side.
18
+
19
+ ```ts /trigger/summarize.ts
20
+ import { task } from "@trigger.dev/sdk";
21
+ import { generateText } from "ai";
22
+ import { openai } from "@ai-sdk/openai";
23
+
24
+ export const summarize = task({
25
+ id: "summarize",
26
+ run: async (payload: { text: string }) => {
27
+ const result = await generateText({
28
+ model: openai("gpt-4o"),
29
+ prompt: `Summarize the following text:\n\n${payload.text}`,
30
+ experimental_telemetry: { isEnabled: true },
31
+ });
32
+
33
+ return { summary: result.text };
34
+ },
35
+ });
36
+ ```
37
+
38
+ Trigger the task and open the run. The `generateText` call appears as a span in the trace. `streamText` and `generateObject` work the same way: add the same `experimental_telemetry` flag to each call you want captured.
39
+
40
+ <Note>
41
+ **AI SDK 7** moved span emission out of `ai` core into the `@ai-sdk/otel` adapter. In a task, install `@ai-sdk/otel` and register it once yourself, for example at the top of your task file:
42
+
43
+ ```ts /trigger/summarize.ts
44
+ import { registerTelemetry } from "ai";
45
+ import { OpenTelemetry } from "@ai-sdk/otel";
46
+
47
+ registerTelemetry(new OpenTelemetry());
48
+ ```
49
+
50
+ A [`chat.agent()`](/ai-chat/overview) run registers the adapter for you at run start, so chat agents need only the install. On AI SDK 5 and 6, `ai` core emits spans directly and no adapter is needed.
51
+ </Note>
52
+
53
+ ## What each span shows
54
+
55
+ Open an AI generation span in the run trace to get a dedicated inspector with three tabs:
56
+
57
+ - **Overview**: model, provider, token usage, cost, and a preview of the input and output.
58
+ - **Messages**: the full message thread, including the system prompt and any tool results.
59
+ - **Tools**: the tool definitions passed to the model, plus every tool call the model made with its arguments.
60
+
61
+ A fourth **Prompt** tab appears when the call is linked to an [AI Prompt](/ai/prompts) (see below).
62
+
63
+ ## Link a call to its prompt
64
+
65
+ If you manage prompts with [AI Prompts](/ai/prompts), resolve the prompt and spread `toAISDKTelemetry()` into the call. This sets `experimental_telemetry` for you and links the span back to the exact prompt version that produced it.
66
+
67
+ ```ts /trigger/support.ts
68
+ import { task, prompts } from "@trigger.dev/sdk";
69
+ import { generateText } from "ai";
70
+ import { openai } from "@ai-sdk/openai";
71
+ import type { supportPrompt } from "./prompts";
72
+
73
+ export const handleSupport = task({
74
+ id: "handle-support",
75
+ run: async (payload: { name: string; plan: string; issue: string }) => {
76
+ const resolved = await prompts.resolve<typeof supportPrompt>("customer-support", {
77
+ customerName: payload.name,
78
+ plan: payload.plan,
79
+ issue: payload.issue,
80
+ });
81
+
82
+ const result = await generateText({
83
+ model: openai(resolved.model ?? "gpt-4o"),
84
+ system: resolved.text,
85
+ prompt: payload.issue,
86
+ ...resolved.toAISDKTelemetry(),
87
+ });
88
+
89
+ return { response: result.text };
90
+ },
91
+ });
92
+ ```
93
+
94
+ The span's **Prompt** tab now shows the linked template, its version, and the input variables the prompt was resolved with.
95
+
96
+ Pass custom attributes to `toAISDKTelemetry()` to tag the span with your own metadata:
97
+
98
+ ```ts
99
+ const result = await generateText({
100
+ model: openai(resolved.model ?? "gpt-4o"),
101
+ system: resolved.text,
102
+ prompt: payload.issue,
103
+ ...resolved.toAISDKTelemetry({
104
+ "task.type": "summarization",
105
+ "customer.tier": "enterprise",
106
+ }),
107
+ });
108
+ ```
109
+
110
+ Custom attributes are stored on the span's `metadata`, so you can filter or group by them in TRQL, for example `metadata['task.type']`.
111
+
112
+ <Note>
113
+ When you build an agent with `chat.agent()` and store a prompt with `chat.prompt.set()`, `chat.toStreamTextOptions()` sets `experimental_telemetry` for you, so those generations are captured without adding the flag by hand. Without a stored prompt, set `experimental_telemetry` on the call yourself. See [Prompts](/ai/prompts#using-with-chatagent).
114
+ </Note>
115
+
116
+ ## Query usage across runs
117
+
118
+ Every captured generation is also written to the `llm_metrics` table, which you can query with [TRQL](/observability/query). This lets you aggregate token usage, cost, and latency across many runs rather than inspecting one span at a time.
119
+
120
+ Cost and token usage by model:
121
+
122
+ ```sql
123
+ SELECT
124
+ response_model,
125
+ gen_ai_system AS provider,
126
+ count() AS calls,
127
+ sum(total_tokens) AS tokens,
128
+ round(sum(total_cost), 4) AS cost_usd
129
+ FROM llm_metrics
130
+ GROUP BY response_model, gen_ai_system
131
+ ORDER BY cost_usd DESC
132
+ LIMIT 20
133
+ ```
134
+
135
+ Spend per task:
136
+
137
+ ```sql
138
+ SELECT
139
+ task_identifier,
140
+ sum(input_tokens) AS input_tokens,
141
+ sum(output_tokens) AS output_tokens,
142
+ round(sum(total_cost), 4) AS cost_usd
143
+ FROM llm_metrics
144
+ GROUP BY task_identifier
145
+ ORDER BY cost_usd DESC
146
+ LIMIT 20
147
+ ```
148
+
149
+ Cost by prompt version, when calls are linked to an [AI Prompt](/ai/prompts):
150
+
151
+ ```sql
152
+ SELECT
153
+ prompt_slug,
154
+ prompt_version,
155
+ count() AS calls,
156
+ round(sum(total_cost), 4) AS cost_usd
157
+ FROM llm_metrics
158
+ WHERE prompt_slug != ''
159
+ GROUP BY prompt_slug, prompt_version
160
+ ORDER BY prompt_slug, prompt_version
161
+ ```
162
+
163
+ Set the time window with the query's [period filter](/observability/query#time-ranges) rather than in the SQL itself. Run these from the [Query dashboard](/observability/query#using-the-query-dashboard), the SDK with `query.execute()`, or the REST API. `llm_metrics` also exposes `ms_to_first_chunk` and `tokens_per_second` for latency and throughput, plus `finish_reason`, `request_model`, `cached_read_tokens`, `reasoning_tokens`, and per-direction `input_cost` / `output_cost` for finer breakdowns.
164
+
165
+ ## Next steps
166
+
167
+ <CardGroup cols={2}>
168
+ <Card title="Prompts" icon="message-lines" href="/ai/prompts">
169
+ Version prompts as code and link generations to the exact prompt version that produced them.
170
+ </Card>
171
+ <Card title="Query (TRQL)" icon="magnifying-glass-chart" href="/observability/query">
172
+ Write custom queries against your runs, metrics, and LLM usage.
173
+ </Card>
174
+ </CardGroup>
@@ -215,10 +215,12 @@ function ChatClient({ chatId, initialMessages, initialSessions }) {
215
215
  </Info>
216
216
 
217
217
  <Note>
218
- After resuming, `useChat`'s built-in `stop()` won't send the stop signal to the backend because
219
- the AI SDK doesn't pass its abort signal through `reconnectToStream`. Use
220
- `transport.stopGeneration(chatId)` for reliable stop behavior after resume see
221
- [Stop generation](#stop-generation) for the recommended pattern.
218
+ After resuming, `useChat`'s built-in `stop()` won't send the stop signal to the backend. The
219
+ transport accepts an abort signal on `reconnectToStream` but doesn't treat it as owning the turn,
220
+ so aborting a resumed subscription only closes your local stream while the run keeps generating.
221
+ Use `transport.stopGeneration(chatId)` for reliable stop behavior after resume — see
222
+ [Stop generation](#stop-generation) for the recommended pattern. Pass `stopOnAbort: true` to
223
+ `reconnectToStream` only when that subscriber owns the turn.
222
224
  </Note>
223
225
 
224
226
  <Warning>
@@ -340,11 +342,10 @@ const stop = useCallback(() => {
340
342
  </Info>
341
343
 
342
344
  <Tip>
343
- A [PR to the AI SDK](https://github.com/vercel/ai/pull/14350) has been
344
- submitted to pass `abortSignal` through `reconnectToStream`, which would make
345
- `useChat`'s built-in `stop()` work after resume without needing
346
- `stopGeneration`. Until that lands, use the pattern above for reliable stop
347
- behavior after page refresh.
345
+ Aborting a resumed stream never stops the run by itself, so `useChat`'s
346
+ built-in `stop()` isn't enough after a page refresh. Use the pattern above, or
347
+ pass `stopOnAbort: true` to `reconnectToStream` when that subscriber owns the
348
+ turn.
348
349
  </Tip>
349
350
 
350
351
  See [Stop generation](/ai-chat/backend#stop-generation) in the backend docs for how to handle stop signals in your task.
@@ -47,7 +47,7 @@ See [Quick Start](/ai-chat/quick-start) for the matching server actions and a ru
47
47
 
48
48
  ## Why use AI Agents on Trigger.dev
49
49
 
50
- - **Resume across refreshes, deploys, and crashes.** A chat in progress when you redeploy keeps streaming on the new version. Mid-stream refreshes pick up where they left off.
50
+ - **Resume across refreshes, deploys, and crashes.** A chat in progress keeps streaming through a redeploy, pinned to the version it started on. Move it onto new code when you choose with a [version upgrade](/ai-chat/patterns/version-upgrades). Mid-stream refreshes pick up where they left off.
51
51
  - **Native AI SDK support.** Text, tool calls, reasoning, and custom `data-*` parts all flow through `useChat` over a custom `ChatTransport`. No custom protocol to maintain.
52
52
  - **Multi-turn for free.** Each turn is a step inside the same durable task; conversation history accumulates server-side, so clients only ship the new message.
53
53
  - **Fast cold starts.** Opt-in [Head Start](/ai-chat/fast-starts#head-start) runs the first `streamText` step in your warm Next.js / Hono / SvelteKit server while the agent boots in parallel — cuts time-to-first-chunk roughly in half.
package/docs/apikeys.mdx CHANGED
@@ -1,54 +1,186 @@
1
1
  ---
2
2
  title: "API keys"
3
- description: "How to authenticate with Trigger.dev so you can trigger tasks."
3
+ description: "Authenticate backend requests with environment-specific API keys."
4
4
  ---
5
5
 
6
- ### Authentication and your secret keys
6
+ **API keys authenticate backend requests to a specific Trigger.dev project and environment.** Each environment can have multiple keys, with optional scopes and restrictions attached.
7
7
 
8
- When you [trigger a task](/triggering) from your backend code, you need to set the `TRIGGER_SECRET_KEY` environment variable.
8
+ <Warning>
9
+ API keys grant access to your Trigger.dev environment. Store them in a secret manager or backend
10
+ environment variable, never commit them to source control, and never expose them in frontend code.
11
+ </Warning>
9
12
 
10
- Each environment has its own secret key. You can find the value on the API keys page in the Trigger.dev dashboard:
13
+ ## Find your API keys
11
14
 
12
- ![How to find your secret key](/images/api-keys.png)
15
+ Open your project in the dashboard, select an environment, and open the [**API keys**](https://cloud.trigger.dev/_/apikeys) page.
16
+
17
+ API keys belong to one environment. A Development key cannot access Production, and a Production key cannot access Staging.
13
18
 
14
19
  <Note>
15
- For preview branches, you need to also set the `TRIGGER_PREVIEW_BRANCH` environment variable as
16
- well. You can find the value on the API keys page when you're on the preview branch.
20
+ Every team member has their own Development environment and keys. Copy the Development key from
21
+ your own API keys page so local requests run against your machine.
17
22
  </Note>
18
23
 
19
- ### Automatically Configuring the SDK
24
+ ## Configure the SDK
20
25
 
21
- To automatically configure the SDK with your secret key, you can set the `TRIGGER_SECRET_KEY` environment variable. The SDK will automatically use this value when calling API methods (like `trigger`).
26
+ Set `TRIGGER_SECRET_KEY` in your backend environment. The SDK reads it automatically for operations such as triggering tasks and retrieving runs.
22
27
 
23
28
  ```bash .env
24
- TRIGGER_SECRET_KEY="tr_dev_…"
25
- TRIGGER_PREVIEW_BRANCH="my-branch" # Only needed for preview branches
29
+ TRIGGER_SECRET_KEY="tr_prod_sk_…"
30
+ ```
31
+
32
+ To configure the SDK in code, pass the key to `configure`:
33
+
34
+ ```ts Your backend code
35
+ import { configure, tasks } from "@trigger.dev/sdk";
36
+ import type { sendEmail } from "./trigger/send-email";
37
+
38
+ configure({
39
+ secretKey: process.env.TRIGGER_SECRET_KEY,
40
+ previewBranch: "my-branch", // Only needed for preview branches
41
+ baseURL: "https://mytrigger.example.com", // Optional
42
+ });
43
+
44
+ await tasks.trigger<typeof sendEmail>("send-email", {
45
+ to: "user@example.com",
46
+ });
26
47
  ```
27
48
 
28
- You can do the same if you are self-hosting and need to change the default URL by using `TRIGGER_API_URL`.
49
+ If you self-host Trigger.dev, set `TRIGGER_API_URL` or pass `baseURL` to `configure`:
29
50
 
30
51
  ```bash .env
52
+ TRIGGER_SECRET_KEY="tr_prod_…"
31
53
  TRIGGER_API_URL="https://trigger.example.com"
32
- TRIGGER_PREVIEW_BRANCH="my-branch" # Only needed for preview branches
33
54
  ```
34
55
 
35
- The default URL is `https://api.trigger.dev`.
56
+ The default API URL is `https://api.trigger.dev`.
57
+
58
+ ## Create a key
36
59
 
37
- ### Manually Configuring the SDK
60
+ Create a separate key for each service or integration that accesses Trigger.dev.
38
61
 
39
- If you prefer to manually configure the SDK, you can call the `configure` method:
62
+ <Note>
63
+ Creating and revoking keys requires permission to manage API keys for the selected environment.
64
+ The dashboard disables these actions when your role does not have permission.
65
+ </Note>
40
66
 
41
- ```ts
42
- import { configure } from "@trigger.dev/sdk";
43
- import { myTask } from "./trigger/myTasks";
67
+ <Steps titleSize="h3">
68
+ <Step title="Open the API keys page">
69
+ Select the project and environment the integration needs to access, then open [**API keys**](https://cloud.trigger.dev/_/apikeys).
70
+ </Step>
71
+ <Step title="Create the key">
72
+ Click **New API key**, enter a descriptive name, and optionally set an expiration date. Names can
73
+ contain up to 64 characters.
74
+ </Step>
75
+ <Step title="Choose its access">
76
+ Select an access preset. For task-aware presets, choose all tasks or up to 10 task identifiers.
77
+ </Step>
78
+ <Step title="Copy and store the secret">
79
+ Copy the key into your secret manager or backend environment. Trigger.dev shows the complete
80
+ value only once.
81
+ </Step>
82
+ </Steps>
83
+
84
+ ## Access presets
85
+
86
+ Access presets define what a key can do. Some presets require a paid plan. The dashboard shows which presets your organization can use — see [pricing](https://trigger.dev/pricing).
87
+
88
+ | Preset | Access |
89
+ | --- | --- |
90
+ | **Trigger only** | Trigger runs and batches for all or selected tasks. Trigger responses include scoped public access tokens for the runs and batches they create |
91
+ | **Task operator** | Trigger all or selected tasks and inspect or operate on their runs |
92
+ | **Observer** | Read runs, tasks, batches, logs, traces, and queues |
93
+ | **Operator** | Observe and operate on runs and queues, and trigger tasks |
94
+ | **Deploy only** | Deploy versions, sync environment variables, and manage Preview branches |
95
+ | **Variables only** | Read and write environment variables in this environment |
96
+ | **No restrictions** | Full access to the environment |
97
+
98
+ **Trigger only** and **Task operator** can be restricted to selected tasks. Task restrictions use task identifiers, such as `send-email`. A request involving multiple tasks — such as a batch trigger — succeeds only when the key can access every task in the request, so a task-restricted key can batch-trigger only its selected tasks.
99
+
100
+ ## Deploy with an API key
101
+
102
+ Set a key in `TRIGGER_ACCESS_TOKEN` to authenticate `trigger deploy` without logging in.
103
+
104
+ <CodeGroup>
105
+
106
+ ```bash npm
107
+ TRIGGER_ACCESS_TOKEN="tr_prod_sk_…" npx trigger.dev@latest deploy
108
+ ```
109
+ </CodeGroup>
44
110
 
45
- configure({
46
- secretKey: "tr_dev_1234", // WARNING: Never actually hardcode your secret key like this
47
- previewBranch: "my-branch", // Only needed for preview branches
48
- baseURL: "https://mytrigger.example.com", // Optional
49
- });
111
+ The key must belong to the target environment. Use a Production key for the default deployment, a Staging key with `--env staging`, or a key from the Preview environment with `--env preview`. A Preview deployment key can create and archive Preview branches and sync their environment variables.
112
+
113
+ <Note>
114
+ The deploy CLI reads environment API keys from `TRIGGER_ACCESS_TOKEN`, not
115
+ `TRIGGER_SECRET_KEY`. Setting an API key in `TRIGGER_ACCESS_TOKEN` takes precedence over a saved
116
+ CLI login.
117
+ </Note>
118
+
119
+ ## Expire and revoke keys
120
+
121
+ Set an expiration date when creating a key if the integration only needs temporary access. An expired key stops authenticating automatically.
50
122
 
51
- async function triggerTask() {
52
- await myTask.trigger({ userId: "1234" }); // This will use the secret key and base URL you configured
53
- }
123
+ Revoking a key takes effect immediately and cannot be reversed. Requests using the key fail, and the key can no longer create public access tokens. Create a replacement before revoking a key when you need to rotate it without interrupting the integration.
124
+
125
+ Removing a team member does not revoke keys they created. Review and revoke their keys separately when their access changes.
126
+
127
+ ## Root keys
128
+
129
+ <Warning>
130
+ Root keys are legacy, and are likely to be deprecated in the future. We recommend against using them.
131
+ </Warning>
132
+
133
+ Each environment has a single legacy root key. It can be regenerated, which creates a new value immediately. The previous root key remains valid for 24 hours so you can update services without downtime, then stops authenticating.
134
+
135
+ Public access tokens signed with the previous root key remain valid until the earlier of their own expiration and the end of the 24-hour grace period.
136
+
137
+ ## Create public access tokens
138
+
139
+ API keys can be used to create scoped [Public Access Tokens](/realtime/auth) using `auth.createPublicToken()`.
140
+
141
+ To do so with the newer non-root keys, you must use `@trigger.dev/sdk` version 4.5.8 or later. Creating public tokens with non-root keys has the following restrictions:
142
+
143
+ - The token must request at least one scope.
144
+ - Its scopes cannot exceed the key's access.
145
+ - Its expiration cannot exceed 30 days.
146
+
147
+ <Note>
148
+ Revoking or expiring an API key does not revoke tokens it already created. Those tokens remain valid until their own expiration, unless the environment's root key is regenerated.
149
+ </Note>
150
+
151
+ ## Target Preview and Development branches
152
+
153
+ Preview and named Development branches use their parent environment's keys. Select the branch by setting `TRIGGER_PREVIEW_BRANCH` alongside the environment key:
154
+
155
+ ```bash .env
156
+ TRIGGER_SECRET_KEY="tr_preview_sk_…"
157
+ TRIGGER_PREVIEW_BRANCH="feature/new-checkout"
54
158
  ```
159
+
160
+ The SDK sends the branch automatically. When calling the API directly, send the same value in the `x-trigger-branch` header.
161
+
162
+ ## Self-hosting
163
+
164
+ Self-hosted installations support multiple keys with **No restrictions**. The restricted access presets are available in Trigger.dev Cloud.
165
+
166
+ Keep your instance and SDK current before creating keys. Calling a public-token API with a key on a server that does not support server-minted tokens returns an upgrade error; use the root key until the server is upgraded.
167
+
168
+ ## Security recommendations
169
+
170
+ - Create one key per service or integration instead of sharing keys.
171
+ - Choose the narrowest access preset and task selection that supports the integration.
172
+ - Store keys in a secret manager and inject them as backend environment variables.
173
+ - Set expiration dates for temporary integrations and deployment credentials.
174
+ - Revoke keys when an integration or team member no longer needs access.
175
+ - Never put an API key in frontend code. Use scoped [Public Access Tokens](/realtime/auth) for client-side access.
176
+
177
+ ## Next steps
178
+
179
+ <CardGroup cols={2}>
180
+ <Card title="Trigger tasks" icon="bolt" href="/triggering">
181
+ Trigger tasks from your backend with an environment API key.
182
+ </Card>
183
+ <Card title="Realtime authentication" icon="key" href="/realtime/auth">
184
+ Create scoped public tokens for frontend and realtime access.
185
+ </Card>
186
+ </CardGroup>
@@ -128,9 +128,11 @@ const publicToken = await auth.createPublicToken({
128
128
  ```
129
129
 
130
130
  - If `expirationTime` is a string, it will be treated as a time span
131
- - If `expirationTime` is a number, it will be treated as a Unix timestamp
131
+ - If `expirationTime` is a number, it will be treated as a Unix timestamp in **seconds**
132
132
  - If `expirationTime` is a `Date`, it will be treated as a date
133
133
 
134
+ When using non-root API keys (recommended), the expiration cannot be more than 30 days in the future.
135
+
134
136
  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.
135
137
 
136
138
  ### Auto-generated tokens
@@ -48,6 +48,7 @@ mode: "wide"
48
48
  | `KUBERNETES_NAMESPACE` | No | default | The namespace that runs should be in. |
49
49
  | `KUBERNETES_WORKER_NODETYPE_LABEL` | No | v4-worker | Nodes for runs need `nodetype=<this>`. Empty: any node. |
50
50
  | `KUBERNETES_RUNNER_TOLERATIONS` | No | — | Run pod tolerations. CSV: `key=value:effect`/`key:effect`. |
51
+ | `KUBERNETES_ORG_PLACEMENT_OVERRIDES` | No | — | Per-org run pod placement. JSON keyed by internal org ID. |
51
52
  | `KUBERNETES_IMAGE_PULL_SECRETS` | No | — | Image pull secrets (CSV). |
52
53
  | `KUBERNETES_EPHEMERAL_STORAGE_SIZE_LIMIT` | No | 10Gi | Ephemeral storage size limit. Applies to all runs. |
53
54
  | `KUBERNETES_EPHEMERAL_STORAGE_SIZE_REQUEST` | No | 2Gi | Ephemeral storage size request. Applies to all runs. |
@@ -44,6 +44,7 @@ mode: "wide"
44
44
  | `LOGIN_RATE_LIMITS_ENABLED` | No | true | Enable rate limiting on magic-link login. |
45
45
  | `AUTH_GITHUB_CLIENT_ID` | No | — | GitHub client ID. |
46
46
  | `AUTH_GITHUB_CLIENT_SECRET` | No | — | GitHub client secret. |
47
+ | `CSP_IMG_SRC_ALLOWLIST` | No | — | Extra hosts the dashboard may load images from, e.g. an SSO or avatar host serving profile images. A comma-separated list of exact origins (`https://sso.example.com`); a wildcard host such as `https://*.example.com` is refused. |
47
48
  | **Email** | | | |
48
49
  | `EMAIL_TRANSPORT` | No | — | Email transport type. One of `resend`, `smtp`, `aws-ses`. |
49
50
  | `FROM_EMAIL` | No | — | From email address. |
@@ -76,6 +77,12 @@ mode: "wide"
76
77
  | `API_RATE_LIMIT_LIMITER_LOGS_ENABLED` | No | 0 | API rate limit limiter logs. |
77
78
  | `API_RATE_LIMIT_JWT_WINDOW` | No | 1m | API rate limit JWT window. |
78
79
  | `API_RATE_LIMIT_JWT_TOKENS` | No | 60 | API rate limit JWT tokens. |
80
+ | `DEPLOYMENT_RATE_LIMIT_REFILL_INTERVAL` | No | 10s | Deployment endpoints rate limit refill interval. |
81
+ | `DEPLOYMENT_RATE_LIMIT_MAX` | No | 1500 | Deployment endpoints rate limit max. |
82
+ | `DEPLOYMENT_RATE_LIMIT_REFILL_RATE` | No | 500 | Deployment endpoints rate limit refill rate. |
83
+ | `DEPLOYMENT_RATE_LIMIT_REQUEST_LOGS_ENABLED` | No | 0 | Deployment endpoints rate limit request logs. |
84
+ | `DEPLOYMENT_RATE_LIMIT_REJECTION_LOGS_ENABLED` | No | 1 | Deployment endpoints rate limit rejection logs. |
85
+ | `DEPLOYMENT_RATE_LIMIT_LIMITER_LOGS_ENABLED` | No | 0 | Deployment endpoints rate limit limiter logs. |
79
86
  | **Deploy & Registry** | | | |
80
87
  | `DEPLOY_REGISTRY_HOST` | Yes | — | Deploy registry host. |
81
88
  | `DEPLOY_REGISTRY_USERNAME` | No | — | Deploy registry username. |
@@ -140,6 +140,50 @@ To use imperative schedules you need to do two things:
140
140
  1. Define a task in your code using `schedules.task()`.
141
141
  2. Attach 1+ schedules to the task either using the dashboard or the SDK.
142
142
 
143
+ ## Spreading runs with windows
144
+
145
+ By default a schedule runs at its exact cron time. When many schedules share the same cron pattern, such as a daily `0 9 * * *`, they all fire at the same time and load your downstream systems as well as ours. A **window** spreads those runs out: each schedule is assigned a stable time within the window after its cron time, so the load is smoothed while each schedule keeps firing at a predictable, repeatable moment.
146
+
147
+ The assigned time is deterministic. A given schedule always lands at the same offset for a given interval, so runs don't jump around between occurrences. And you can always see exactly when the next run will start.
148
+
149
+ Set a `window` as either:
150
+
151
+ - **An absolute duration** in whole minutes or hours, up to 24 hours: `"30m"`, `"2h"`, `"24h"`. Absolute windows are capped at the next cron time, so a run is never delayed past its following occurrence.
152
+ - **A percentage** of the interval between runs: `"30%"`, `"100%"`. A `"50%"` window on an hourly schedule spreads runs across the first 30 minutes of each hour.
153
+
154
+ Set `"0m"` (or `"0%"`) for no spreading — the run fires at its exact cron time.
155
+
156
+ Declarative schedules set the window on the `cron` object:
157
+
158
+ ```ts
159
+ export const dailyReport = schedules.task({
160
+ id: "daily-report",
161
+ cron: {
162
+ pattern: "0 0 * * *",
163
+ // spread this run across the 30 minutes after midnight
164
+ window: "30m",
165
+ },
166
+ run: async (payload) => {},
167
+ });
168
+ ```
169
+
170
+ Imperative schedules set it when creating or updating a schedule, either in the dashboard form or through the SDK:
171
+
172
+ ```ts
173
+ const createdSchedule = await schedules.create({
174
+ task: dailyReport.id,
175
+ cron: "0 0 * * *",
176
+ window: "30m",
177
+ deduplicationKey: "user_123456-daily-report",
178
+ });
179
+ ```
180
+
181
+ <Note>
182
+ The payload `timestamp` and `upcoming` values are always the nominal cron times, not the assigned
183
+ times. When you retrieve a schedule, `nextRun` is the nominal cron time and `nextRunEffectiveAt`
184
+ is the assigned time the run will actually start.
185
+ </Note>
186
+
143
187
  ## Supported cron syntax
144
188
 
145
189
  ```
@@ -198,6 +242,7 @@ These are the options when creating a schedule:
198
242
  | Task | The id of the task you want to attach to. |
199
243
  | Cron pattern | The schedule in cron format. You can also describe it in natural language and press "Generate" to fill this in. |
200
244
  | Timezone | The timezone the schedule will run in. Defaults to "UTC" |
245
+ | Window | An optional [window](#spreading-runs-with-windows) to spread runs after their cron time, e.g. `30m`, `2h`, or `50%`. |
201
246
  | External id | An optional external id, usually you'd use a userId. |
202
247
  | Deduplication key | An optional deduplication key. If you pass the same value, it will update rather than create. Scoped per project, not per environment. |
203
248
  | Environments | The environments this schedule will run in. |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@trigger.dev/sdk",
3
- "version": "4.5.10",
3
+ "version": "4.5.12",
4
4
  "description": "trigger.dev Node.JS SDK",
5
5
  "license": "MIT",
6
6
  "publishConfig": {
@@ -66,30 +66,18 @@
66
66
  "dependencies": {
67
67
  "@opentelemetry/api": "1.9.1",
68
68
  "@opentelemetry/semantic-conventions": "1.41.1",
69
- "@trigger.dev/core": "4.5.10",
70
- "chalk": "^5.2.0",
71
- "cronstrue": "^2.21.0",
72
- "debug": "^4.3.4",
73
- "evt": "^2.4.13",
74
- "slug": "^6.0.0",
75
- "ulid": "^2.3.0",
76
- "uncrypto": "^0.1.3",
77
- "ws": "^8.11.0"
69
+ "@trigger.dev/core": "4.5.12",
70
+ "uncrypto": "^0.1.3"
78
71
  },
79
72
  "devDependencies": {
80
73
  "@ai-sdk/provider": "3.0.8",
81
74
  "@arethetypeswrong/cli": "^0.18.5",
82
- "@types/debug": "^4.1.7",
83
75
  "@types/react": "^19.2.14",
84
- "@types/slug": "^5.0.3",
85
- "@types/ws": "^8.5.3",
86
76
  "ai": "^6.0.116",
87
77
  "ai-v7": "npm:ai@7.0.0-canary.159",
88
- "encoding": "^0.1.13",
89
78
  "rimraf": "^6.0.1",
90
79
  "tshy": "^4.1.3",
91
80
  "tsx": "4.17.0",
92
- "typed-emitter": "^2.1.0",
93
81
  "typescript": "7.0.2",
94
82
  "zod": "3.25.76"
95
83
  },