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

package/docs/webhooks/waiters.mdx

@@ -0,0 +1,190 @@
+---
+title: "Waiting for a webhook"
+description: "Pause a run until a matching webhook arrives on an endpoint, then resume it with the verified event."
+sidebarTitle: "Waiters"
+---
+
+**A waiter pauses a run until a matching delivery arrives on an [endpoint](/webhooks/overview).** Use it when your task starts something in another system and needs to know when that system reports back: a payment that settles, a build that finishes, a document that gets signed.
+
+```ts /trigger/checkout.ts
+import { task, webhooks } from "@trigger.dev/sdk";
+import { stripe } from "./stripe"; // webhooks.endpoint.define({ id: "stripe", source: webhooks.stripe() })
+
+export const checkout = task({
+  id: "checkout",
+  run: async ({
+    orderId,
+    customerId,
+    paymentMethodId,
+  }: {
+    orderId: string;
+    customerId: string;
+    paymentMethodId: string;
+  }) => {
+    const waiter = await webhooks.waiter.create(stripe, {
+      match: {
+        "event.type": "payment_intent.succeeded",
+        "event.data.object.metadata.orderId": orderId,
+      },
+      timeout: "1h",
+      // the same waiter (and its event) if this run is retried
+      idempotencyKey: `payment-${orderId}`,
+    });
+
+    // confirm: true charges the customer's saved payment method now, so Stripe sends payment_intent.succeeded.
+    // Stripe's own idempotency key stops a retry from creating a second intent for the order.
+    await stripeClient.paymentIntents.create(
+      {
+        amount: 4200,
+        currency: "usd",
+        customer: customerId,
+        payment_method: paymentMethodId,
+        confirm: true,
+        metadata: { orderId },
+      },
+      { idempotencyKey: `payment-intent-${orderId}` }
+    );
+
+    const { event, deliveryId } = await webhooks.waiter.wait(waiter).unwrap();
+    return { paymentIntent: event.data.object.id, deliveryId };
+  },
+});
+```
+
+While the run waits it is suspended, so it uses no compute. The endpoint's other subscribers still receive the delivery.
+
+## Create before you act
+
+A waiter only matches deliveries that arrive after it was created. Create it before the call that makes the provider send the webhook, as above, or a fast provider can deliver the event before anything is waiting for it.
+
+Match on values you control, such as your own order id in the provider object's metadata. Two runs waiting for the same values are both resumed by the delivery.
+
+## Matching
+
+`match` maps paths to the scalar each must equal. Paths use the same namespaces as a [filter](/webhooks/filters):
+
+| Path | Reads |
+| --- | --- |
+| `event.*` | The verified event body, for example `event.data.object.id`. |
+| `header.*` | A request header, matched case-insensitively, for example `header.x-shop-domain`. |
+| `webhook.*` | The endpoint: `id`, `source`, `externalRef`, `tenantId`, or `deliveryId`. |
+
+A waiter can match up to five paths, and each value is a string, number or boolean. Paths are checked against the endpoint's event type at build time: an unknown field on a typed event, a path to an object, or a path without a namespace is a type error. The API refuses the same paths at create time.
+
+For conditions that aren't equality, add a `filter`. It is checked after `match`:
+
+```ts
+await webhooks.waiter.create(stripe, {
+  match: { "event.data.object.metadata.orderId": orderId },
+  filter: "event.type in ['payment_intent.succeeded', 'payment_intent.payment_failed']",
+});
+```
+
+## The result
+
+`webhooks.waiter.wait(waiter)` returns a result you can check, and `.unwrap()` returns the output or throws:
+
+```ts
+const result = await webhooks.waiter.wait(waiter);
+if (result.ok) {
+  console.log(result.output.event, result.output.headers, result.output.endpoint);
+} else {
+  console.log(result.error.name); // "WaitpointTimeoutError" or "WebhookWaiterCancelledError"
+}
+```
+
+| Output field | Value |
+| --- | --- |
+| `event` | The verified event body, typed by the endpoint's source. |
+| `headers` | The request headers, with credentials such as signatures removed. |
+| `deliveryId` | The delivery that resumed the run (`whd_...`). |
+| `endpoint` | The endpoint the delivery arrived on. |
+
+`timeout` accepts a duration such as `"30m"` or a `Date`. It defaults to 24 hours and can be up to 90 days. A waiter that times out fails the wait with `WaitpointTimeoutError`.
+
+A waiter is a [waitpoint](/wait-for-token): its id starts with `waitpoint_` and it is tagged `webhook:<endpoint id>` plus any `tags` you pass (up to 10).
+
+## Providers that take a callback URL
+
+Some providers accept a webhook URL per request instead of one account-wide URL, such as Replicate's `webhook` parameter. Omit `match` and the waiter gets its own URL:
+
+```ts
+const waiter = await webhooks.waiter.create(replicateEndpoint, { timeout: "2h" });
+
+await replicate.predictions.create({ version, input, webhook: waiter.url });
+
+const { event } = await webhooks.waiter.wait(waiter).unwrap();
+```
+
+A delivery to `waiter.url` is verified with the endpoint's source, resumes only that waiter, and is not sent to the endpoint's subscribers.
+
+## Creating from your backend
+
+`webhooks.waiter.create` also works outside a run, for example in the API route that starts a checkout. Pass the waiter, or its id, to a task that waits on it:
+
+```ts
+const waiter = await webhooks.waiter.create(stripe, { match: { "event.data.object.metadata.orderId": orderId } });
+await fulfillWhenPaid.trigger({ waiterId: waiter.id });
+```
+
+```ts
+export const fulfillWhenPaid = task({
+  id: "fulfill-when-paid",
+  run: async ({ waiterId }: { waiterId: string }) => {
+    const { event } = await webhooks.waiter.wait(waiterId).unwrap();
+  },
+});
+```
+
+The same operations are on the REST API: [`POST /api/v1/webhooks/endpoints/{endpointId}/waiters`](/management/webhooks/create-waiter) with `match`, `filter`, `timeout`, `tags` and `idempotencyKey`, and [`POST /api/v1/webhooks/waiters/{waiterId}/cancel`](/management/webhooks/cancel-waiter). `endpointId` is the endpoint's declared id or its `wh_` id.
+
+## Retries and idempotency
+
+Pass an `idempotencyKey` so a task can be retried without losing its webhook. A create with a key it has seen returns the original waiter, with `isCached: true`, even if it has already completed, and waiting on a completed waiter returns its event straight away. Inside a task a string key is scoped to the run, as it is for [`trigger()`](/idempotency), so a retried attempt gets the waiter (and the event) the attempt before it created:
+
+```ts
+const waiter = await webhooks.waiter.create(stripe, {
+  match: { "event.data.object.metadata.orderId": orderId },
+  idempotencyKey: `payment-${orderId}`,
+});
+```
+
+Use [`idempotencyKeys.create(key, { scope })`](/idempotency) for a key scoped to one attempt or shared across runs, and `idempotencyKeyTTL` to set how long the key lasts.
+
+Without a key every call creates a new waiter, and a waiter only matches deliveries that arrive after it. If an attempt fails after its webhook arrived, the retry's new waiter waits for an event the provider already sent.
+
+## Cancelling
+
+`webhooks.waiter.cancel(waiter)` frees the waiter's slot and fails its wait with `WebhookWaiterCancelledError`. If a delivery has already claimed the waiter, the cancel is too late and the run resumes with that delivery:
+
+```ts
+const result = await webhooks.waiter.cancel(waiter);
+if (!result.cancelled) {
+  console.log("Already resumed by", result.deliveryId); // result.reason is "too_late"
+}
+```
+
+## Errors
+
+`webhooks.waiter.create` throws a typed error when nothing was created:
+
+| Error | Cause |
+| --- | --- |
+| `WebhookWaiterLimitError` | A limit was reached. `reason` is `endpoint_limit`, `environment_limit`, `shape_limit` or `timeout_too_long`. |
+| `WebhookEndpointNotFoundError` | The endpoint isn't in the environment's current deployment. |
+| `WebhookFilterError` | The `filter` doesn't parse. |
+
+## Limits
+
+| Limit | Default |
+| --- | --- |
+| Live waiters per endpoint | 10,000. This is also the most one delivery can resume. |
+| Live waiters per environment | 1,000,000 on self-hosted installs. |
+| Distinct sets of `match` paths per endpoint | 25 |
+| Paths per `match` | 5 |
+| Tags per waiter | 10 |
+| Timeout | 24 hours by default, 90 days at most |
+
+On Trigger.dev Cloud the per-endpoint and per-environment limits depend on your plan. Self-hosted installs can change them with `WEBHOOK_WAITER_MAX_PER_ENDPOINT`, `WEBHOOK_WAITER_MAX_PER_ENVIRONMENT` and `WEBHOOK_WAITER_MAX_SHAPES`.
+
+A delivery that resumes waiters shows one **Waiting runs** row on its [delivery page](/webhooks/deliveries#where-a-delivery-went) with how many matched, resumed and failed. A delivery that arrives while runs are waiting but matches none of them, and no subscriber takes, is `UNMATCHED`.

package/docs/writing-tasks-introduction.mdx

@@ -0,0 +1,34 @@
+---
+title: "Writing tasks: Overview"
+sidebarTitle: "Overview"
+description: "Tasks are the core of Trigger.dev. They are long-running processes that are triggered by events."
+---
+
+import ExamplesCards from "/snippets/examples-cards.mdx";
+
+Before digging deeper into the details of writing tasks, you should read the [fundamentals of tasks](/tasks/overview) to understand what tasks are and how they work.
+
+## Writing tasks
+
+| Topic                                        | Description                                                                                         |
+| :------------------------------------------- | :-------------------------------------------------------------------------------------------------- |
+| [Logging](/logging)                          | View and send logs and traces from your tasks.                                                      |
+| [Errors & retrying](/errors-retrying)        | How to deal with errors and write reliable tasks.                                                   |
+| [Wait](/wait)                                | Wait for periods of time or for external events to occur before continuing.                         |
+| [Queues](/queues)                            | Control the order your runs execute in.                                                             |
+| [Concurrency](/concurrency)                  | Limit how many runs execute at once: per task, per tenant, or shared across tasks.                  |
+| [Realtime notifications](/realtime/overview) | Send realtime notifications from your task that you can subscribe to from your backend or frontend. |
+| [Versioning](/versioning)                    | How versioning works.                                                                               |
+| [Machines](/machines)                        | Configure the CPU and RAM of the machine your task runs on                                          |
+| [Idempotency](/idempotency)                  | Protect against mutations happening twice.                                                          |
+| [Replaying](/replaying)                      | You can replay a single task or many at once with a new version of your code.                       |
+| [Max duration](/runs/max-duration)           | Set a maximum duration for your task to run.                                                        |
+| [Tags](/tags)                                | Tags allow you to easily filter runs in the dashboard and when using the SDK.                       |
+| [Metadata](/runs/metadata)                   | Attach a small amount of data to a run and update it as the run progresses.                         |
+| [Usage](/run-usage)                          | Get compute duration and cost from inside a run, or for a specific block of code.                   |
+| [Context](/context)                          | Access the context of the task run.                                                                 |
+| [Bulk actions](/bulk-actions)                | Run actions on many task runs at once.                                                              |
+| [Priority](/runs/priority)                   | Specify a priority when triggering a task.                                                          |
+| [Hidden tasks](/hidden-tasks)                | Create tasks that are not exported from your trigger files but can still be executed.               |
+
+<ExamplesCards />

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trigger.dev/sdk",
-  "version": "0.0.0-python-preview-20250226140121",
+  "version": "0.0.0-rc-4-8-0-20261021151928",
   "description": "trigger.dev Node.JS SDK",
   "license": "MIT",
   "publishConfig": {
@@ -12,18 +12,30 @@
     "directory": "packages/trigger-sdk"
   },
   "type": "module",
+  "sideEffects": false,
   "files": [
-    "dist"
+    "dist",
+    "docs",
+    "skills"
   ],
   "tshy": {
     "selfLink": false,
+    "exclude": [
+      "src/**/*.test.ts"
+    ],
     "main": true,
     "module": true,
     "project": "./tsconfig.build.json",
     "exports": {
       "./package.json": "./package.json",
-      ".": "./src/index.ts",
-      "./v3": "./src/v3/index.ts"
+      ".": "./src/v3/index.ts",
+      "./v3": "./src/v3/index.ts",
+      "./ai": "./src/v3/ai.ts",
+      "./ai/skills-runtime": "./src/v3/agentSkillsRuntime.ts",
+      "./ai/test": "./src/v3/test/index.ts",
+      "./chat": "./src/v3/chat.ts",
+      "./chat/react": "./src/v3/chat-react.ts",
+      "./chat-server": "./src/v3/chat-server.ts"
     },
     "sourceDialects": [
       "@triggerdotdev/source"
@@ -33,43 +45,63 @@
     "*": {
       "v3": [
         "dist/commonjs/v3/index.d.ts"
+      ],
+      "ai": [
+        "dist/commonjs/v3/ai.d.ts"
+      ],
+      "ai/skills-runtime": [
+        "dist/commonjs/v3/agentSkillsRuntime.d.ts"
+      ],
+      "ai/test": [
+        "dist/commonjs/v3/test/index.d.ts"
+      ],
+      "chat": [
+        "dist/commonjs/v3/chat.d.ts"
+      ],
+      "chat/react": [
+        "dist/commonjs/v3/chat-react.d.ts"
+      ],
+      "chat-server": [
+        "dist/commonjs/v3/chat-server.d.ts"
       ]
     }
   },
   "dependencies": {
-    "@opentelemetry/api": "1.9.0",
-    "@opentelemetry/api-logs": "0.52.1",
-    "@opentelemetry/semantic-conventions": "1.25.1",
-    "@trigger.dev/core": "0.0.0-python-preview-20250226140121",
-    "chalk": "^5.2.0",
-    "cronstrue": "^2.21.0",
-    "debug": "^4.3.4",
-    "evt": "^2.4.13",
-    "slug": "^6.0.0",
-    "terminal-link": "^3.0.0",
-    "ulid": "^2.3.0",
-    "uncrypto": "^0.1.3",
-    "uuid": "^9.0.0",
-    "ws": "^8.11.0"
+    "@opentelemetry/api": "1.9.1",
+    "@opentelemetry/semantic-conventions": "1.41.1",
+    "@trigger.dev/core": "0.0.0-rc-4-8-0-20261021151928",
+    "uncrypto": "^0.1.3"
   },
   "devDependencies": {
-    "@arethetypeswrong/cli": "^0.15.4",
-    "@types/debug": "^4.1.7",
-    "@types/node": "20.14.14",
-    "@types/slug": "^5.0.3",
-    "@types/uuid": "^9.0.0",
-    "@types/ws": "^8.5.3",
-    "ai": "^4.0.1",
-    "encoding": "^0.1.13",
-    "rimraf": "^3.0.2",
-    "tshy": "^3.0.2",
+    "@ai-sdk/provider": "3.0.8",
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@opentelemetry/sdk-trace-base": "2.8.0",
+    "@types/react": "^19.2.14",
+    "ai": "^6.0.116",
+    "ai-v7": "npm:ai@7.0.0-canary.159",
+    "rimraf": "^6.0.1",
+    "stripe": "23.0.0",
+    "tshy": "^4.1.3",
     "tsx": "4.17.0",
-    "typed-emitter": "^2.1.0",
-    "typescript": "^5.5.4",
-    "zod": "3.23.8"
+    "typescript": "7.0.2",
+    "zod": "4.5.4"
   },
   "peerDependencies": {
-    "zod": "^3.0.0"
+    "@ai-sdk/otel": ">=1.0.0-0 <2",
+    "ai": "^5.0.0 || ^6.0.0 || >=7.0.0-canary <8",
+    "react": "^18.0 || ^19.0",
+    "zod": "^3.25.56 || ^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@ai-sdk/otel": {
+      "optional": true
+    },
+    "ai": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
   },
   "engines": {
     "node": ">=18.20.0"
@@ -78,13 +110,13 @@
     "./package.json": "./package.json",
     ".": {
       "import": {
-        "@triggerdotdev/source": "./src/index.ts",
-        "types": "./dist/esm/index.d.ts",
-        "default": "./dist/esm/index.js"
+        "@triggerdotdev/source": "./src/v3/index.ts",
+        "types": "./dist/esm/v3/index.d.ts",
+        "default": "./dist/esm/v3/index.js"
       },
       "require": {
-        "types": "./dist/commonjs/index.d.ts",
-        "default": "./dist/commonjs/index.js"
+        "types": "./dist/commonjs/v3/index.d.ts",
+        "default": "./dist/commonjs/v3/index.js"
       }
     },
     "./v3": {
@@ -97,16 +129,85 @@
         "types": "./dist/commonjs/v3/index.d.ts",
         "default": "./dist/commonjs/v3/index.js"
       }
+    },
+    "./ai": {
+      "import": {
+        "@triggerdotdev/source": "./src/v3/ai.ts",
+        "types": "./dist/esm/v3/ai.d.ts",
+        "default": "./dist/esm/v3/ai.js"
+      },
+      "require": {
+        "types": "./dist/commonjs/v3/ai.d.ts",
+        "default": "./dist/commonjs/v3/ai.js"
+      }
+    },
+    "./ai/skills-runtime": {
+      "import": {
+        "@triggerdotdev/source": "./src/v3/agentSkillsRuntime.ts",
+        "types": "./dist/esm/v3/agentSkillsRuntime.d.ts",
+        "default": "./dist/esm/v3/agentSkillsRuntime.js"
+      },
+      "require": {
+        "types": "./dist/commonjs/v3/agentSkillsRuntime.d.ts",
+        "default": "./dist/commonjs/v3/agentSkillsRuntime.js"
+      }
+    },
+    "./ai/test": {
+      "import": {
+        "@triggerdotdev/source": "./src/v3/test/index.ts",
+        "types": "./dist/esm/v3/test/index.d.ts",
+        "default": "./dist/esm/v3/test/index.js"
+      },
+      "require": {
+        "types": "./dist/commonjs/v3/test/index.d.ts",
+        "default": "./dist/commonjs/v3/test/index.js"
+      }
+    },
+    "./chat": {
+      "import": {
+        "@triggerdotdev/source": "./src/v3/chat.ts",
+        "types": "./dist/esm/v3/chat.d.ts",
+        "default": "./dist/esm/v3/chat.js"
+      },
+      "require": {
+        "types": "./dist/commonjs/v3/chat.d.ts",
+        "default": "./dist/commonjs/v3/chat.js"
+      }
+    },
+    "./chat/react": {
+      "import": {
+        "@triggerdotdev/source": "./src/v3/chat-react.ts",
+        "types": "./dist/esm/v3/chat-react.d.ts",
+        "default": "./dist/esm/v3/chat-react.js"
+      },
+      "require": {
+        "types": "./dist/commonjs/v3/chat-react.d.ts",
+        "default": "./dist/commonjs/v3/chat-react.js"
+      }
+    },
+    "./chat-server": {
+      "import": {
+        "@triggerdotdev/source": "./src/v3/chat-server.ts",
+        "types": "./dist/esm/v3/chat-server.d.ts",
+        "default": "./dist/esm/v3/chat-server.js"
+      },
+      "require": {
+        "types": "./dist/commonjs/v3/chat-server.d.ts",
+        "default": "./dist/commonjs/v3/chat-server.js"
+      }
     }
   },
-  "main": "./dist/commonjs/index.js",
-  "types": "./dist/commonjs/index.d.ts",
-  "module": "./dist/esm/index.js",
+  "main": "./dist/commonjs/v3/index.js",
+  "types": "./dist/commonjs/v3/index.d.ts",
+  "module": "./dist/esm/v3/index.js",
   "scripts": {
-    "clean": "rimraf dist",
-    "build": "tshy && pnpm run update-version",
+    "clean": "rimraf dist docs .tshy .tshy-build .turbo",
+    "build": "tshy && pnpm run update-version && pnpm run bundle-docs",
+    "bundle-docs": "tsx ../../scripts/bundleSdkDocs.ts",
     "dev": "tshy --watch",
     "typecheck": "tsc --noEmit",
+    "typecheck:ai-v7": "tsc --noEmit -p tsconfig.ai-v7.json",
+    "test": "vitest",
     "update-version": "tsx ../../scripts/updateVersion.ts",
     "check-exports": "attw --pack ."
   }