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

package/docs/versioning.mdx

@@ -0,0 +1,56 @@
+---
+title: "Versioning"
+description: "We use atomic versioning to ensure that started tasks are not affected by changes to the task code."
+---
+
+A version is a bundle of tasks at a certain point in time.
+
+## Version identifiers
+
+Version identifiers look like this:
+
+- `20240313.1` - March 13th, 2024, version 1
+- `20240313.2` - March 13th, 2024, version 2
+- `20240314.1` - March 14th, 2024, version 1
+
+You can see there are two parts to the version identifier:
+
+- The date (in reverse format)
+- The version number
+
+Versions numbers are incremented each time a new version is created for that date and environment. So it's possible to have `20240313.1` in both the `dev` and `prod` environments.
+
+## Version locking
+
+When a task run starts it is locked to the latest version of the code (for that environment). Once locked it won't change versions, even if you deploy new versions. This is to ensure that a task run is not affected by changes to the code.
+
+Delayed runs are locked to the version that's active when they begin executing, not when they're enqueued.
+
+### Child tasks and version locking
+
+Trigger and wait functions version lock child task runs to the parent task run version. This ensures the results from child runs match what the parent task is expecting. If you don't wait then version locking doesn't apply.
+
+| Trigger function        | Parent task version | Child task version | isLocked |
+| ----------------------- | ------------------- | ------------------ | -------- |
+| `trigger()`             | `20240313.2`        | Latest             | No       |
+| `batchTrigger()`        | `20240313.2`        | Latest             | No       |
+| `triggerAndWait()`      | `20240313.2`        | `20240313.2`       | Yes      |
+| `batchTriggerAndWait()` | `20240313.2`        | `20240313.2`       | Yes      |
+
+## Local development
+
+When running the local server (using `npx trigger.dev dev`), every relevant code change automatically creates a new version of all tasks.
+
+So a task run will continue running on the version it was locked to. We do this by spawning a new process for each task run. This ensures that the task run is not affected by changes to the code.
+
+## Deployment
+
+Every deployment creates a new version of all tasks for that environment.
+
+## Retries and reattempts
+
+When a task has an uncaught error it will [retry](/errors-retrying), assuming you have not set `maxAttempts` to 0. Retries are locked to the original version of the run.
+
+## Replays
+
+A "replay" is a new run of a task that uses the same inputs but will use the latest version of the code. This is useful when you fix a bug and want to re-run a task with the same inputs. See [replaying](/replaying) for more information.

package/docs/video-walkthrough.mdx

@@ -0,0 +1,23 @@
+---
+title: "Video walkthrough"
+description: "Go from zero to a working task in your Next.js app in 10 minutes."
+---
+
+{" "}
+<iframe
+  width="100%"
+  height="315"
+  src="https://www.youtube.com/embed/YH_4c0K7fGM?si=5JzZmZseuqI5aciM"
+  title="Trigger.dev walkthrough"
+  allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
+  referrerPolicy="strict-origin-when-cross-origin"
+  allowFullScreen
+/>
+
+### In this video we cover the following topics:
+
+- [0:00](https://youtu.be/YH_4c0K7fGM?si=J8svVzotZtyTXDap&t=0) – [Install Trigger.dev](/quick-start) in an existing Next.js project
+- [1:44](https://youtu.be/YH_4c0K7fGM?si=J8svVzotZtyTXDap&t=104) – [Run and test](/run-tests) the "Hello, world!" example project
+- [2:09](https://youtu.be/YH_4c0K7fGM?si=FMTP8ep_cDBCU0_x&t=128) – Create and run an AI image generation task that uses [Fal.ai](https://fal.ai) – ([View the code](/guides/examples/fal-ai-image-to-cartoon))
+- [6:25](https://youtu.be/YH_4c0K7fGM?si=pPc8iLI2Y9FGD3yo&t=385) – Create and run a [Realtime](/realtime/overview) example using [React hooks](/realtime/react-hooks) – ([View the code](/guides/examples/fal-ai-realtime))
+- [11:10](https://youtu.be/YH_4c0K7fGM?si=Mjd0EvvNsNlVouvY&t=670) – [Deploy your task](/cli-deploy) to the Trigger.dev Cloud

package/docs/wait-for-token.mdx

@@ -0,0 +1,540 @@
+---
+title: "Wait for token"
+description: "Wait until a token is completed using waitpoint tokens."
+---
+
+Waitpoint tokens pause task runs until you complete the token. They're commonly used for approval workflows and other scenarios where you need to wait for external confirmation, such as human-in-the-loop processes.
+
+You can complete a token using the SDK or by making a POST request to the token's URL.
+
+<Note>
+  If you're waiting for data from an [input stream](/tasks/streams#input-streams), use
+  [`inputStream.wait()`](/tasks/streams#wait--suspend-until-data-arrives) instead — it uses
+  waitpoint tokens internally but provides a simpler API with full type safety from your stream
+  definition.
+</Note>
+
+## Usage
+
+To get started using wait tokens, you need to first create a token using the `wait.createToken` function:
+
+```ts
+import { wait } from "@trigger.dev/sdk";
+
+// This can be called anywhere in your codebase, either in a task or in your backend code
+const token = await wait.createToken({
+  timeout: "10m", // you can optionally specify a timeout for the token
+});
+```
+
+Once you have a token, you can wait for it to be completed using the `wait.forToken` function:
+
+```ts
+import { wait } from "@trigger.dev/sdk";
+
+type ApprovalToken = {
+  status: "approved" | "rejected";
+};
+
+// This must be called inside a task run function
+const result = await wait.forToken<ApprovalToken>(tokenId);
+
+if (result.ok) {
+  console.log("Token completed", result.output.status); // "approved" or "rejected"
+} else {
+  console.log("Token timed out", result.error);
+}
+```
+
+To complete a token, you can use the `wait.completeToken` function:
+
+```ts
+import { wait } from "@trigger.dev/sdk";
+// This can be called anywhere in your codebase, or from an external service,
+// passing in the token ID and the output of the token
+await wait.completeToken<ApprovalToken>(tokenId, {
+  status: "approved",
+});
+```
+
+## Completing from the browser
+
+The `publicAccessToken` returned by `wait.createToken()` is scoped to that specific waitpoint and intended for client-side completion. The completion endpoint has CORS enabled, so you can call it directly from client-side code without proxying through your backend.
+
+<Steps>
+  <Step title="Create the token in your backend">
+    ```typescript
+    import { wait } from "@trigger.dev/sdk";
+
+    const token = await wait.createToken({ timeout: "10m" });
+    // Pass token.id and token.publicAccessToken to your frontend
+    ```
+  </Step>
+  <Step title="Complete the token from the browser">
+    ```typescript
+    // tokenId and publicAccessToken passed from your backend
+    const tokenId = token.id;
+    const publicAccessToken = token.publicAccessToken;
+
+    const response = await fetch(
+      `https://api.trigger.dev/api/v1/waitpoints/tokens/${tokenId}/complete`,
+      {
+        method: "POST",
+        headers: {
+          "Authorization": `Bearer ${publicAccessToken}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ data: { status: "approved" } }),
+      }
+    );
+
+    if (!response.ok) {
+      throw new Error(`Failed to complete token: ${response.statusText}`);
+    }
+    ```
+  </Step>
+</Steps>
+
+## Completing via webhook callback
+
+<Warning>
+  The `token.url` webhook callback URL is designed for server-to-server use and does **not** have
+  CORS headers. Don't call it from the browser, use the [Completing from the
+  browser](#completing-from-the-browser) pattern instead.
+</Warning>
+
+Or you can make an HTTP POST request to the `url` it returns. This is an HTTP callback:
+
+```ts
+import { wait } from "@trigger.dev/sdk";
+
+const token = await wait.createToken({
+  timeout: "10m",
+});
+
+const call = await replicate.predictions.create({
+  version: "27b93a2413e7f36cd83da926f3656280b2931564ff050bf9575f1fdf9bcd7478",
+  input: {
+    prompt: "A painting of a cat by Andy Warhol",
+  },
+  // pass the provided URL to Replicate's webhook, so they can "callback"
+  webhook: token.url,
+  webhook_events_filter: ["completed"],
+});
+
+const prediction = await wait.forToken<Prediction>(token).unwrap();
+// unwrap() throws a timeout error or returns the result   👆
+```
+
+## wait.createToken
+
+Create a waitpoint token.
+
+### options
+
+The `createToken` function accepts an object with the following properties:
+
+<ParamField query="timeout" type="string" optional>
+  The maximum amount of time to wait for the token to be completed. Defaults to "10m".
+</ParamField>
+
+<ParamField query="idempotencyKey" type="string" optional>
+  An idempotency key for the token. If provided, the token will be completed with the same payload
+  if the same idempotency key is used again.
+</ParamField>
+
+<ParamField query="idempotencyKeyTTL" type="string" optional>
+  The time to live for the idempotency key. Defaults to "1h".
+</ParamField>
+
+<ParamField query="tags" type="string[]" optional>
+  Tags to attach to the token. Tags can be used to filter waitpoints in the dashboard.
+</ParamField>
+
+### returns
+
+The `createToken` function returns a token object with the following properties:
+
+<ParamField query="id" type="string">
+  The ID of the token. Starts with `waitpoint_`.
+</ParamField>
+
+<ParamField query="url" type="string">
+  The URL of the token. This is the URL you can make a POST request to in order to complete the token.
+
+The JSON body of the POST request will be used as the output of the token. If there's no body the output will be an empty object `{}`.
+
+</ParamField>
+
+<ParamField query="isCached" type="boolean">
+  Whether the token is cached. Will return true if the token was created with an idempotency key and
+  the same idempotency key was used again.
+</ParamField>
+
+<ParamField query="publicAccessToken" type="string">
+  A Public Access Token that can be used to complete the token from a client-side application (or
+  another backend). See our [Realtime docs](/realtime/auth) for more details.
+</ParamField>
+
+### Example
+
+```ts
+import { wait } from "@trigger.dev/sdk";
+
+const token = await wait.createToken({
+  timeout: "10m",
+  idempotencyKey: "my-idempotency-key",
+  tags: ["my-tag"],
+});
+```
+
+## wait.completeToken
+
+Complete a waitpoint token.
+
+### parameters
+
+<ParamField query="id" type="string">
+  The ID of the token to complete.
+</ParamField>
+
+<ParamField query="output" type="any">
+  The data to complete the token with.
+</ParamField>
+
+### returns
+
+The `completeToken` function returns an object with the following properties:
+
+<ParamField query="success" type="boolean">
+  Whether the token was completed successfully.
+</ParamField>
+
+### Example
+
+```ts
+import { wait } from "@trigger.dev/sdk";
+
+await wait.completeToken<ApprovalToken>(tokenId, {
+  status: "approved",
+});
+```
+
+### From another language
+
+You can complete a token using a raw HTTP request or from another language.
+
+<CodeGroup>
+
+```bash curl
+curl -X POST "https://api.trigger.dev/api/v1/waitpoints/tokens/{tokenId}/complete" \
+  -H "Authorization: Bearer {token}" \
+  -H "Content-Type: application/json" \
+  -d '{"data": { "status": "approved"}}'
+```
+
+```python python
+import requests
+
+response = requests.post(
+  "https://api.trigger.dev/api/v1/waitpoints/tokens/{tokenId}/complete",
+  headers={"Authorization": f"Bearer {token}"},
+  json={"data": { "status": "approved"}}
+)
+```
+
+```ruby ruby
+require "net/http"
+
+uri = URI("https://api.trigger.dev/api/v1/waitpoints/tokens/{tokenId}/complete")
+
+http = Net::HTTP.new(uri.host, uri.port)
+request = Net::HTTP::Post.new(uri)
+request["Authorization"] = "Bearer {token}"
+request["Content-Type"] = "application/json"
+request.body = JSON.generate({ data: { status: "approved" } })
+
+response = http.request(request)
+```
+
+```go go
+package main
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"net/http"
+)
+
+func main() {
+	url := "https://api.trigger.dev/api/v1/waitpoints/tokens/{tokenId}/complete"
+
+	payload := map[string]interface{}{
+		"data": map[string]interface{}{
+			"status": "approved",
+		},
+	}
+
+	jsonData, err := json.Marshal(payload)
+	if err != nil {
+		fmt.Println("Error marshalling payload:", err)
+		return
+	}
+
+	req, err := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
+	if err != nil {
+		fmt.Println("Error creating request:", err)
+		return
+	}
+
+	req.Header.Set("Authorization", "Bearer {token}")
+	req.Header.Set("Content-Type", "application/json")
+
+	client := &http.Client{}
+	resp, err := client.Do(req)
+	if err != nil {
+		fmt.Println("Error sending request:", err)
+		return
+	}
+
+	defer resp.Body.Close()
+
+	fmt.Println("Response status:", resp.Status)
+}
+```
+
+</CodeGroup>
+
+## wait.forToken
+
+Wait for a token to be completed.
+
+### parameters
+
+<ParamField query="token" type="string | { id: string }">
+  The token to wait for.
+</ParamField>
+
+### returns
+
+The `forToken` function returns a result object with the following properties:
+
+<ParamField query="ok" type="boolean">
+  Whether the token was completed successfully.
+</ParamField>
+
+<ParamField query="output" type="any">
+  If `ok` is `true`, this will be the output of the token.
+</ParamField>
+
+<ParamField query="error" type="Error">
+  If `ok` is `false`, this will be the error that occurred. The only error that can occur is a
+  timeout error.
+</ParamField>
+
+### unwrap()
+
+We provide a handy `.unwrap()` method that will throw an error if the result is not ok. This means your happy path is a lot cleaner.
+
+```ts
+const approval = await wait.forToken<ApprovalToken>(tokenId).unwrap();
+// unwrap means an error will throw if the waitpoint times out 👆
+
+// This is the actual data you sent to the token now, not a result object
+console.log("Approval", approval);
+```
+
+### Example
+
+```ts
+import { wait } from "@trigger.dev/sdk";
+
+const result = await wait.forToken<ApprovalToken>(tokenId);
+
+if (result.ok) {
+  console.log("Token completed", result.output.status); // "approved" or "rejected"
+} else {
+  console.log("Token timed out", result.error);
+}
+```
+
+## wait.listTokens
+
+List all tokens for an environment.
+
+### parameters
+
+The `listTokens` function accepts an object with the following properties:
+
+<ParamField query="status" type="string | string[]" optional>
+  Statuses to filter by. Can be one or more of: `WAITING`, `COMPLETED`, `TIMED_OUT`.
+</ParamField>
+
+<ParamField query="idempotencyKey" type="string" optional>
+  The idempotency key to filter by.
+</ParamField>
+
+<ParamField query="tags" type="string | string[]" optional>
+  Tags to filter by.
+</ParamField>
+
+<ParamField query="period" type="string" optional>
+  The period to filter by. Can be one of: `1h`, `1d`, `7d`, `30d`.
+</ParamField>
+
+<ParamField query="from" type="Date | number" optional>
+  The start date to filter by.
+</ParamField>
+
+<ParamField query="to" type="Date | number" optional>
+  The end date to filter by.
+</ParamField>
+
+### returns
+
+The `listTokens` function returns a list of tokens that can be iterated over using a for-await-of loop.
+
+Each token is an object with the following properties:
+
+<ParamField query="id" type="string">
+  The ID of the token.
+</ParamField>
+
+<ParamField query="url" type="string">
+  The URL of the token. This is the URL you can make a POST request to in order to complete the token.
+
+The JSON body of the POST request will be used as the output of the token. If there's no body the output will be an empty object `{}`.
+
+</ParamField>
+
+<ParamField query="status" type="string">
+  The status of the token.
+</ParamField>
+
+<ParamField query="completedAt" type="Date">
+  The date and time the token was completed.
+</ParamField>
+
+<ParamField query="timeoutAt" type="Date">
+  The date and time the token will timeout.
+</ParamField>
+
+<ParamField query="idempotencyKey" type="string">
+  The idempotency key of the token.
+</ParamField>
+
+<ParamField query="idempotencyKeyExpiresAt" type="Date">
+  The date and time the idempotency key will expire.
+</ParamField>
+
+<ParamField query="tags" type="string[]">
+  The tags of the token.
+</ParamField>
+
+<ParamField query="createdAt" type="Date">
+  The date and time the token was created.
+</ParamField>
+
+<Note>
+  The output of the token is not included in the list. To get the output, you need to retrieve the
+  token using the `wait.retrieveToken` function.
+</Note>
+
+### Example
+
+```ts
+import { wait } from "@trigger.dev/sdk";
+
+const tokens = await wait.listTokens({
+  status: "COMPLETED",
+  tags: ["user:123"],
+});
+
+for await (const token of tokens) {
+  console.log(token);
+}
+```
+
+## wait.retrieveToken
+
+Retrieve a token by ID.
+
+### parameters
+
+<ParamField query="id" type="string">
+  The ID of the token to retrieve.
+</ParamField>
+
+### returns
+
+The `retrieveToken` function returns a token object with the following properties:
+
+<ParamField query="id" type="string">
+  The ID of the token.
+</ParamField>
+
+<ParamField query="url" type="string">
+  The URL of the token. This is the URL you can make a POST request to in order to complete the token.
+
+The JSON body of the POST request will be used as the output of the token. If there's no body the output will be an empty object `{}`.
+
+</ParamField>
+
+<ParamField query="status" type="string">
+  The status of the token.
+</ParamField>
+
+<ParamField query="completedAt" type="Date">
+  The date and time the token was completed.
+</ParamField>
+
+<ParamField query="timeoutAt" type="Date">
+  The date and time the token will timeout.
+</ParamField>
+
+<ParamField query="idempotencyKey" type="string">
+  The idempotency key of the token.
+</ParamField>
+
+<ParamField query="idempotencyKeyExpiresAt" type="Date">
+  The date and time the idempotency key will expire.
+</ParamField>
+
+<ParamField query="tags" type="string[]">
+  The tags of the token.
+</ParamField>
+
+<ParamField query="createdAt" type="Date">
+  The date and time the token was created.
+</ParamField>
+
+<ParamField query="output" type="any">
+  The output of the token.
+</ParamField>
+
+<ParamField query="error" type="Error">
+  The error that occurred.
+</ParamField>
+
+### Example
+
+```ts
+import { wait } from "@trigger.dev/sdk";
+
+const token = await wait.retrieveToken(tokenId);
+
+console.log(token);
+```
+
+## Wait idempotency
+
+You can pass an idempotency key to any wait function, allowing you to skip waits if the same idempotency key is used again. This can be useful if you want to skip waits when retrying a task, for example:
+
+```ts
+// Specify the idempotency key and TTL when creating a wait token
+const token = await wait.createToken({
+  idempotencyKey: "my-idempotency-key",
+  idempotencyKeyTTL: "1h",
+});
+```

package/docs/wait-for.mdx

@@ -0,0 +1,42 @@
+---
+title: "Wait for"
+description: "Wait for a period of time, then continue execution."
+---
+
+import PausedExecutionFree from "/snippets/paused-execution-free.mdx"
+
+Inside your tasks you can wait for a period of time before you want execution to continue.
+
+```ts /trigger/long-task.ts
+export const veryLongTask = task({
+  id: "very-long-task",
+  run: async (payload) => {
+    await wait.for({ seconds: 5 });
+
+    await wait.for({ minutes: 10 });
+
+    await wait.for({ hours: 1 });
+
+    await wait.for({ days: 1 });
+
+    await wait.for({ weeks: 1 });
+
+    await wait.for({ months: 1 });
+
+    await wait.for({ years: 1 });
+  },
+});
+```
+
+This allows you to write linear code without having to worry about the complexity of scheduling or managing cron jobs.
+
+<PausedExecutionFree />
+
+## Wait idempotency
+
+You can pass an idempotency key to any wait function, allowing you to skip waits if the same idempotency key is used again. This can be useful if you want to skip waits when retrying a task, for example:
+
+```ts
+// Specify the idempotency key and TTL when waiting for a duration:
+await wait.for({ seconds: 10 }, { idempotencyKey: "my-idempotency-key", idempotencyKeyTTL: "1h" });
+```