@tailor-platform/sdk 1.57.0 → 1.59.0

package/docs/cli-reference.md

@@ -200,15 +200,16 @@ Commands for managing workspaces and profiles.
 
 Commands for managing Auth service resources.
 
-| Command                                                            | Description                                              |
-| ------------------------------------------------------------------ | -------------------------------------------------------- |
-| [authconnection authorize](./cli/auth.md#authconnection-authorize) | Authorize an auth connection via OAuth2 flow.            |
-| [authconnection list](./cli/auth.md#authconnection-list)           | List all auth connections.                               |
-| [authconnection revoke](./cli/auth.md#authconnection-revoke)       | Revoke an auth connection.                               |
-| [machineuser list](./cli/auth.md#machineuser-list)                 | List all machine users in the application.               |
-| [machineuser token](./cli/auth.md#machineuser-token)               | Get an access token for a machine user.                  |
-| [oauth2client list](./cli/auth.md#oauth2client-list)               | List all OAuth2 clients in the application.              |
-| [oauth2client get](./cli/auth.md#oauth2client-get)                 | Get OAuth2 client credentials (including client secret). |
+| Command                                                            | Description                                                                           |
+| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------- |
+| [authconnection authorize](./cli/auth.md#authconnection-authorize) | Authorize an auth connection via OAuth2 flow.                                         |
+| [authconnection list](./cli/auth.md#authconnection-list)           | List all auth connections.                                                            |
+| [authconnection revoke](./cli/auth.md#authconnection-revoke)       | Revoke an auth connection's tokens (keeps the connection; use 'delete' to remove it). |
+| [authconnection delete](./cli/auth.md#authconnection-delete)       | Delete an auth connection entirely.                                                   |
+| [machineuser list](./cli/auth.md#machineuser-list)                 | List all machine users in the application.                                            |
+| [machineuser token](./cli/auth.md#machineuser-token)               | Get an access token for a machine user.                                               |
+| [oauth2client list](./cli/auth.md#oauth2client-list)               | List all OAuth2 clients in the application.                                           |
+| [oauth2client get](./cli/auth.md#oauth2client-get)                 | Get OAuth2 client credentials (including client secret).                              |
 
 ### [Workflow Commands](./cli/workflow.md)
 
@@ -263,11 +264,13 @@ Commands for managing secrets and vaults.
 
 Commands for managing and deploying static websites.
 
-| Command                                                             | Description                                           |
-| ------------------------------------------------------------------- | ----------------------------------------------------- |
-| [staticwebsite deploy](./cli/staticwebsite.md#staticwebsite-deploy) | Deploy a static website from a local build directory. |
-| [staticwebsite list](./cli/staticwebsite.md#staticwebsite-list)     | List all static websites in a workspace.              |
-| [staticwebsite get](./cli/staticwebsite.md#staticwebsite-get)       | Get details of a specific static website.             |
+| Command                                                                       | Description                                           |
+| ----------------------------------------------------------------------------- | ----------------------------------------------------- |
+| [staticwebsite deploy](./cli/staticwebsite.md#staticwebsite-deploy)           | Deploy a static website from a local build directory. |
+| [staticwebsite domain list](./cli/staticwebsite.md#staticwebsite-domain-list) | List custom domains for a static website.             |
+| [staticwebsite domain get](./cli/staticwebsite.md#staticwebsite-domain-get)   | Get details of a custom domain.                       |
+| [staticwebsite list](./cli/staticwebsite.md#staticwebsite-list)               | List all static websites in a workspace.              |
+| [staticwebsite get](./cli/staticwebsite.md#staticwebsite-get)                 | Get details of a specific static website.             |
 
 ### [Crash Report Commands](./cli/crashreport.md)
 

package/docs/configuration.md

@@ -39,7 +39,7 @@ export default defineConfig({
 
 **Disable Introspection**: Disable GraphQL introspection. Default is `false`.
 
-**Log Level**: Controls which `console.*` calls are kept when deployment functions are bundled. Supported values are `"DEBUG"`, `"INFO"`, `"WARN"`, `"ERROR"`, and `"SILENT"`. The default is `"DEBUG"` and keeps all console calls. For production deployments, use `"WARN"` to keep `console.warn` and `console.error` while dropping debug, log, and info calls:
+**Log Level**: Controls which `console.*` calls are kept when deployment functions are bundled. Supported values are `"DEBUG"`, `"INFO"`, `"WARN"`, `"ERROR"`, and `"SILENT"`. The default is `"DEBUG"` and keeps all console calls. `console.log` is treated as a DEBUG-level call (matching the platform's OpenTelemetry severity mapping), so it is dropped at `"INFO"` and above. For production deployments, use `"WARN"` to keep `console.warn` and `console.error` while dropping debug, log, and info calls:
 
 ```typescript
 export default defineConfig({

package/docs/generator/builtin.md

@@ -22,7 +22,7 @@ Generates a TypeScript file containing:
 
 - Type definitions for all TailorDB types
 - `getDB(namespace)` function to create Kysely instances
-- Utility types for `Timestamp`, `Serial`, and `ObjectColumnType` (wraps nested objects containing date/datetime fields to provide correct insert vs select types)
+- Utility types for `Timestamp`, `Serial`, and `ObjectColumnType` (used for nested object fields so insert and select types stay correct)
 
 ### Usage
 

package/docs/runtime.md

@@ -82,29 +82,26 @@ The runtime entry re-exports the following namespaces. Detailed signatures, para
 
 ## Testing
 
-`@tailor-platform/sdk/vitest` ships mock controllers for every runtime namespace. Pair them with the `tailor-runtime` Vitest environment so your unit tests run against the same wrappers your production code does.
+`@tailor-platform/sdk/vitest` ships mock controllers for every runtime namespace. Pair them with the `tailor-runtime` Vitest environment so your unit tests run against the same wrappers your production code does. Each controller is a factory — acquire it with a `using` declaration and its state is reset automatically when the test scope exits (no `beforeEach(() => mock.reset())` needed). Requires TypeScript ≥ 5.2 and a runtime with `Symbol.dispose` (Node ≥ 20.4; the SDK targets Node ≥ 22).
 
 ```ts
 import { iconv, secretmanager } from "@tailor-platform/sdk/runtime";
-import { iconvMock, secretmanagerMock } from "@tailor-platform/sdk/vitest";
-import { beforeEach, expect, test } from "vitest";
-
-beforeEach(() => {
-  iconvMock.reset();
-  secretmanagerMock.reset();
-});
+import { mockIconv, mockSecretmanager } from "@tailor-platform/sdk/vitest";
+import { expect, test } from "vitest";
 
 test("encodes via iconv", () => {
-  iconvMock.setResolver(() => new Uint8Array([0x82, 0xa0]));
+  using iconvM = mockIconv();
+  iconvM.setResolver(() => new Uint8Array([0x82, 0xa0]));
 
   const out = iconv.convert("あ", "UTF-8", "Shift_JIS");
 
   expect(out).toEqual(new Uint8Array([0x82, 0xa0]));
-  expect(iconvMock.calls[0]?.method).toBe("convert");
-});
+  expect(iconvM.calls[0]?.method).toBe("convert");
+}); // iconvM disposed here — the iconv mock is removed (previous state restored)
 
 test("reads from a vault", async () => {
-  secretmanagerMock.setSecrets({ "my-vault": { API_KEY: "sk-123" } });
+  using sm = mockSecretmanager();
+  sm.setSecrets({ "my-vault": { API_KEY: "sk-123" } });
 
   await expect(secretmanager.getSecret("my-vault", "API_KEY")).resolves.toBe("sk-123");
 });

package/docs/services/auth.md

@@ -521,14 +521,3 @@ tailor-sdk oauth2client get <name>
 ```
 
 See [Auth Resource Commands](../cli/auth.md) for full documentation.
-
-## SDK vs Platform Naming
-
-> **Note for Platform developers**: The SDK uses different names than the underlying Platform API for user attributes:
->
-> | SDK             | Platform API    | Description                      |
-> | --------------- | --------------- | -------------------------------- |
-> | `attributes`    | `attribute_map` | Key-value map of user attributes |
-> | `attributeList` | `attributes`    | Ordered list of UUID values      |
->
-> This mapping is handled automatically by the SDK. If you're reading Platform documentation or API responses, be aware of this naming difference.

package/docs/services/staticwebsite.md

@@ -9,6 +9,7 @@ Static Website provides:
 - Static file hosting
 - Type-safe URL references for configuration
 - IP address restrictions
+- Custom domain support
 
 For the official Tailor Platform documentation, see [Static Website Guide](https://docs.tailor.tech/guides/static-website-hosting).
 
@@ -61,6 +62,18 @@ defineStaticWebSite("my-website", {
 });
 ```
 
+### customDomains
+
+Associate custom domains with the static website:
+
+```typescript
+defineStaticWebSite("my-website", {
+  customDomains: ["app.example.com"],
+});
+```
+
+After deploying, use `tailor-sdk staticwebsite domain get <domain>` to check domain status and retrieve the CNAME targets required for DNS configuration.
+
 ## Type-safe URL References
 
 The returned website object provides a `url` property that resolves to the actual URL at deployment time. Use this for type-safe configuration:

package/docs/testing.md

@@ -19,11 +19,11 @@ Helpers under `@tailor-platform/sdk/test`:
 
 - `unauthenticatedTailorUser` — default `user` value for resolver contexts
 
-Platform API mocks under `@tailor-platform/sdk/vitest` (auto-injected by the [`tailor-runtime` Vitest environment](#runtime-environment-emulation-beta) below):
+Platform API mocks under `@tailor-platform/sdk/vitest` (for use with the [`tailor-runtime` Vitest environment](#runtime-environment-emulation-beta) below):
 
-- `tailordbMock` — TailorDB query stubs and call recording
-- `workflowMock` — `tailor.workflow` job / wait / resolve mocks
-- `secretmanagerMock`, `authconnectionMock`, `idpMock`, `fileMock`, `iconvMock` — corresponding platform API mocks
+- `mockTailordb` — TailorDB query stubs and call recording
+- `mockWorkflow` — `tailor.workflow` job / wait / resolve mocks
+- `mockSecretmanager`, `mockAuthconnection`, `mockIdp`, `mockFile`, `mockIconv` — corresponding platform API mocks
 
 For tighter alignment with the production runtime — Node.js module blocking, Web-only globals, and platform API mocks — pair the resolver helpers with the [`tailor-runtime` Vitest environment](#runtime-environment-emulation-beta) below.
 
@@ -56,22 +56,41 @@ export default defineConfig({
 
 1. **Node.js module blocking** — `import { randomBytes } from "node:crypto"` in production code throws an error with a suggestion for the Web Standard API alternative (`globalThis.crypto`). Test files (`*.test.ts`, `*.spec.ts`) are exempt.
 2. **Node.js globals removal** — Only globals available in the platform runtime are kept (whitelist). `Buffer`, `global`, `setImmediate`, `__dirname`, `__filename`, `performance`, and others are removed.
-3. **Platform API mocks** — `globalThis.tailordb`, `globalThis.tailor`, `TailorErrors`, `TailorErrorMessage`, `TailorDBFileError` are auto-injected with mock control objects for response configuration and call recording.
+3. **Platform API mocks** — the platform error classes (`TailorErrors`, `TailorErrorMessage`, `TailorDBFileError`) and `tailor.context` are always available. The other namespaces (`tailordb.Client`, `tailor.workflow`, `tailor.secretmanager`, …) are mocked when you acquire the corresponding `mockX()` — see below.
 
-### TailorDB Mock
+### Acquiring mocks with `using`
 
-The environment auto-injects a mock `tailordb.Client`. Use `tailordbMock` to configure responses and assert on executed queries:
+Each mock controller (`mockTailordb`, `mockWorkflow`, `mockSecretmanager`, `mockAuthconnection`, `mockIdp`, `mockFile`, `mockIconv`) is a **factory function**. Acquire it inside a test with a [`using` declaration](https://github.com/tc39/proposal-explicit-resource-management) — its state is reset automatically when the test scope exits, so you no longer need `beforeEach(() => mock.reset())`:
 
 ```typescript
-import { tailordbMock } from "@tailor-platform/sdk/vitest";
+import { mockTailordb } from "@tailor-platform/sdk/vitest";
 
-beforeEach(() => {
-  tailordbMock.reset();
-});
+test("...", () => {
+  using db = mockTailordb();
+  db.enqueueResult({ age: 30 });
+  // …
+}); // reset automatically here
+```
+
+The mock functions are also exposed directly (e.g. `db.queryObject`, `wf.triggerJobFunction`) so you can assert on them with `expect(...).toHaveBeenCalledWith(...)`.
+
+> **Requirements:** `using` requires TypeScript ≥ 5.2 and a runtime that provides `Symbol.dispose` (Node ≥ 20.4 — the SDK already targets Node ≥ 22, and Vitest's transformer downlevels the syntax for you).
+>
+> **Acquire what you use:** a namespace is only mocked while you hold it with `using`, so code under test that calls a platform API (e.g. `tailor.workflow`, `tailordb.Client`) must run inside a test that has acquired the matching `mockX()`. The error classes and `tailor.context` are always present.
+>
+> **Seeded secrets survive:** secrets seeded from `tailor.config.ts` stay available across tests; a per-test `mockSecretmanager().setSecrets(...)` override applies only within that test.
+
+### TailorDB Mock
+
+Acquire `mockTailordb()` to install the mock `tailordb.Client`, configure responses, and assert on executed queries:
+
+```typescript
+import { mockTailordb } from "@tailor-platform/sdk/vitest";
 
 test("resolver queries the database", async () => {
+  using db = mockTailordb();
   // Order-based: stage rows for each upcoming query in one call
-  tailordbMock.enqueueResults(
+  db.enqueueResults(
     [], // BEGIN (empty result)
     [{ age: 30 }], // SELECT (one row)
     [], // COMMIT
@@ -80,8 +99,8 @@ test("resolver queries the database", async () => {
   const result = await resolver.body({ input: { email: "test@example.com" } });
 
   expect(result).toEqual({ oldAge: 30, newAge: 31 });
-  expect(tailordbMock.executedQueries).toHaveLength(3);
-  expect(tailordbMock.createdClients).toMatchObject([{ namespace: "tailordb" }]);
+  expect(db.executedQueries).toHaveLength(3);
+  expect(db.createdClients).toMatchObject([{ namespace: "tailordb" }]);
 });
 ```
 
@@ -93,30 +112,28 @@ Three response modes:
 
 ```typescript
 test("content-based mock", async () => {
-  tailordbMock.setQueryResolver((query) => {
+  using db = mockTailordb();
+  db.setQueryResolver((query) => {
     if (query.includes("SELECT")) return [{ id: "1", name: "test" }];
     return [];
   });
 
   const result = await resolver.body({ input: { userId: "1" } });
 
-  expect(tailordbMock.executedQueries[0].query).toContain("SELECT");
+  expect(db.executedQueries[0].query).toContain("SELECT");
 });
 ```
 
 ### Workflow Mock
 
-The environment auto-injects `tailor.workflow.triggerJobFunction`. Use `workflowMock` to configure job responses:
+`.trigger()` runs the real job bodies locally out of the box (see [Running a full workflow locally](#running-a-full-workflow-locally)). Acquire `mockWorkflow()` when you want to override responses with `setJobHandler` / `enqueueResult` or assert on `triggeredJobs`:
 
 ```typescript
-import { workflowMock } from "@tailor-platform/sdk/vitest";
-
-beforeEach(() => {
-  workflowMock.reset();
-});
+import { mockWorkflow } from "@tailor-platform/sdk/vitest";
 
 test("workflow triggers jobs", async () => {
-  workflowMock.setJobHandler((jobName, args) => {
+  using wf = mockWorkflow();
+  wf.setJobHandler((jobName, args) => {
     if (jobName === "validate-order") return { valid: true };
     if (jobName === "process-payment") return { txnId: "txn-1" };
     return null;
@@ -124,52 +141,50 @@ test("workflow triggers jobs", async () => {
 
   const result = await main({ input: { orderId: "o-1" } });
 
-  expect(workflowMock.triggeredJobs).toEqual([
+  expect(wf.triggeredJobs).toEqual([
     { jobName: "validate-order", args: { orderId: "o-1" } },
     { jobName: "process-payment", args: { orderId: "o-1" } },
   ]);
 });
 ```
 
-`workflowMock` also supports order-based responses:
+`mockWorkflow()` also supports order-based responses:
 
 ```typescript
+using wf = mockWorkflow();
+
 // Single response for the next triggerJobFunction call
-workflowMock.enqueueResult({ valid: true });
+wf.enqueueResult({ valid: true });
 
 // Multiple responses for subsequent calls (FIFO)
-workflowMock.enqueueResults({ valid: true }, { txnId: "txn-1" });
+wf.enqueueResults({ valid: true }, { txnId: "txn-1" });
 ```
 
 ### SecretManager Mock
 
 ```typescript
-import { secretmanagerMock } from "@tailor-platform/sdk/vitest";
-
-beforeEach(() => secretmanagerMock.reset());
+import { mockSecretmanager } from "@tailor-platform/sdk/vitest";
 
 test("reads secrets from vault", async () => {
-  secretmanagerMock.setSecrets({
+  using sm = mockSecretmanager();
+  sm.setSecrets({
     "my-vault": { API_KEY: "sk-123", DB_PASS: "secret" },
   });
 
   const key = await tailor.secretmanager.getSecret("my-vault", "API_KEY");
   expect(key).toBe("sk-123");
-  expect(secretmanagerMock.calls).toEqual([
-    { method: "getSecret", vault: "my-vault", name: "API_KEY" },
-  ]);
+  expect(sm.calls).toEqual([{ method: "getSecret", vault: "my-vault", name: "API_KEY" }]);
 });
 ```
 
 ### AuthConnection Mock
 
 ```typescript
-import { authconnectionMock } from "@tailor-platform/sdk/vitest";
-
-beforeEach(() => authconnectionMock.reset());
+import { mockAuthconnection } from "@tailor-platform/sdk/vitest";
 
 test("returns configured token", async () => {
-  authconnectionMock.setTokens({
+  using ac = mockAuthconnection();
+  ac.setTokens({
     google: { access_token: "ya29.xxx", expires_in: 3600 },
   });
 
@@ -183,12 +198,11 @@ When no token is configured for a connection, it returns `{ access_token: "mock-
 ### IDP Mock
 
 ```typescript
-import { idpMock } from "@tailor-platform/sdk/vitest";
-
-beforeEach(() => idpMock.reset());
+import { mockIdp } from "@tailor-platform/sdk/vitest";
 
 test("resolver-based", async () => {
-  idpMock.setResolver((method, args) => {
+  using idp = mockIdp();
+  idp.setResolver((method, args) => {
     if (method === "user") return { id: "u-1", name: "alice", disabled: false };
     return null; // falls back to defaults
   });
@@ -199,31 +213,31 @@ test("resolver-based", async () => {
 });
 
 test("queue-based", async () => {
-  idpMock.enqueueResult({ id: "u-1", name: "alice", disabled: false });
+  using idp = mockIdp();
+  idp.enqueueResult({ id: "u-1", name: "alice", disabled: false });
 
   const client = new tailor.idp.Client({ namespace: "my-ns" });
   const user = await client.user("u-1");
   expect(user.name).toBe("alice");
-  expect(idpMock.calls).toMatchObject([{ method: "user", namespace: "my-ns" }]);
+  expect(idp.calls).toMatchObject([{ method: "user", namespace: "my-ns" }]);
 });
 ```
 
 ### File Mock
 
 ```typescript
-import { fileMock } from "@tailor-platform/sdk/vitest";
-
-beforeEach(() => fileMock.reset());
+import { mockFile } from "@tailor-platform/sdk/vitest";
 
 test("mock file download", async () => {
-  fileMock.enqueueResult({
+  using file = mockFile();
+  file.enqueueResult({
     data: new Uint8Array([1, 2, 3]),
     metadata: { contentType: "image/png", fileSize: 3, sha256sum: "abc", lastUploadedAt: "" },
   });
 
   const result = await tailordb.file.download("ns", "Doc", "attachment", "r-1");
   expect(result.data).toEqual(new Uint8Array([1, 2, 3]));
-  expect(fileMock.calls).toMatchObject([{ method: "download", recordId: "r-1" }]);
+  expect(file.calls).toMatchObject([{ method: "download", recordId: "r-1" }]);
 });
 ```
 
@@ -231,13 +245,14 @@ For `downloadStream`, enqueue a `FileDownloadStreamResponse` object with a `Read
 
 ```typescript
 test("mock file download stream", async () => {
+  using file = mockFile();
   const body = new ReadableStream({
     start(controller) {
       controller.enqueue(new Uint8Array([1, 2, 3]));
       controller.close();
     },
   });
-  fileMock.enqueueResult({
+  file.enqueueResult({
     body,
     metadata: { contentType: "image/png", fileSize: 3, sha256sum: "abc", lastUploadedAt: "" },
   });
@@ -251,7 +266,8 @@ For the deprecated `openDownloadStream`, enqueue an iterable of `StreamValue` it
 
 ```typescript
 test("mock file download stream (deprecated openDownloadStream)", async () => {
-  fileMock.enqueueResult([
+  using file = mockFile();
+  file.enqueueResult([
     {
       type: "metadata",
       metadata: { contentType: "image/png", fileSize: 3, sha256sum: "abc" },
@@ -271,19 +287,18 @@ test("mock file download stream (deprecated openDownloadStream)", async () => {
 ### Iconv Mock
 
 ```typescript
-import { iconvMock } from "@tailor-platform/sdk/vitest";
-
-beforeEach(() => iconvMock.reset());
+import { mockIconv } from "@tailor-platform/sdk/vitest";
 
 test("mock encoding conversion", () => {
-  iconvMock.setResolver((method, args) => {
+  using iconv = mockIconv();
+  iconv.setResolver((method, args) => {
     if (method === "decode") return "decoded-text";
     return null; // falls back to default empty string
   });
 
   const result = tailor.iconv.decode(new Uint8Array([0x48, 0x69]), "UTF-8");
   expect(result).toBe("decoded-text");
-  expect(iconvMock.calls).toMatchObject([{ method: "decode" }]);
+  expect(iconv.calls).toMatchObject([{ method: "decode" }]);
 });
 ```
 
@@ -298,7 +313,7 @@ export default defineConfig({
 });
 ```
 
-This makes `tailor.secretmanager.getSecret("vault", "key")` return the values defined in your config. You can still override with `secretmanagerMock.setSecrets()` in individual tests.
+This makes `tailor.secretmanager.getSecret("vault", "key")` return the values defined in your config. You can still override with `using sm = mockSecretmanager(); sm.setSecrets(...)` in individual tests: a per-test override applies only within that test, and the config-loaded secrets remain available to every other test.
 
 ### Per-Project Configuration
 
@@ -371,7 +386,7 @@ describe("add resolver", () => {
 
 Stub the global `tailordb.Client` and queue raw query results in order. Best for resolvers that issue a short, predictable query sequence:
 
-> If you are running with the [`tailor-runtime` Vitest environment](#runtime-environment-emulation-beta), `tailordb.Client` is auto-injected — drive it with `tailordbMock` instead of `vi.stubGlobal()`.
+> If you are running with the [`tailor-runtime` Vitest environment](#runtime-environment-emulation-beta), acquire `using db = mockTailordb()` to install and drive the mock `tailordb.Client` instead of `vi.stubGlobal()`.
 
 ```typescript
 import { unauthenticatedTailorUser } from "@tailor-platform/sdk/test";
@@ -519,25 +534,22 @@ describe("upsertUsers resolver", () => {
 });
 ```
 
-Reach for [`tailordbMock`](#mocking-the-tailordb-client) instead when you want to drive the raw query sequence at the `tailordb.Client` level rather than at the Kysely layer.
+Reach for [`mockTailordb`](#mocking-the-tailordb-client) instead when you want to drive the raw query sequence at the `tailordb.Client` level rather than at the Kysely layer.
 
 #### Resolvers that resume a workflow
 
-Resolvers that call `waitPoint.resolve(...)` delegate to `tailor.workflow.resolve` at runtime. With the `tailor-runtime` environment active, use `workflowMock.setResolveHandler` to drive the user-supplied callback and inspect `workflowMock.resolveCalls`:
+Resolvers that call `waitPoint.resolve(...)` delegate to `tailor.workflow.resolve` at runtime. With the `tailor-runtime` environment active, use `mockWorkflow().setResolveHandler` to drive the user-supplied callback and inspect `resolveCalls`:
 
 ```typescript
 import { unauthenticatedTailorUser } from "@tailor-platform/sdk/test";
-import { workflowMock } from "@tailor-platform/sdk/vitest";
-import { beforeEach, describe, expect, test } from "vitest";
+import { mockWorkflow } from "@tailor-platform/sdk/vitest";
+import { describe, expect, test } from "vitest";
 import resolver from "./resolveApproval";
 
 describe("resolveApproval resolver", () => {
-  beforeEach(() => {
-    workflowMock.reset();
-  });
-
   test("resolves approval with approved=true", async () => {
-    workflowMock.setResolveHandler((_executionId, _key, callback) => {
+    using wf = mockWorkflow();
+    wf.setResolveHandler((_executionId, _key, callback) => {
       const result = callback({ message: "Please approve order order-1", orderId: "order-1" });
       expect(result).toEqual({ approved: true });
     });
@@ -549,7 +561,7 @@ describe("resolveApproval resolver", () => {
     });
 
     expect(result).toEqual({ resolved: true });
-    expect(workflowMock.resolveCalls).toEqual([{ executionId: "exec-1", key: "approval" }]);
+    expect(wf.resolveCalls).toEqual([{ executionId: "exec-1", key: "approval" }]);
   });
 });
 ```
@@ -660,32 +672,30 @@ describe("fulfillOrder", () => {
 
 #### Jobs that wait on approval
 
-`.wait()` calls delegate to `tailor.workflow.wait`. With the `tailor-runtime` environment active, use `workflowMock.setWaitHandler` to drive each branch and inspect `workflowMock.waitCalls`:
+`.wait()` calls delegate to `tailor.workflow.wait`. With the `tailor-runtime` environment active, use `mockWorkflow().setWaitHandler` to drive each branch and inspect `waitCalls`:
 
 ```typescript
-import { workflowMock } from "@tailor-platform/sdk/vitest";
-import { beforeEach, describe, expect, test } from "vitest";
+import { mockWorkflow } from "@tailor-platform/sdk/vitest";
+import { describe, expect, test } from "vitest";
 import { processWithApproval } from "./approval";
 
 describe("processWithApproval", () => {
-  beforeEach(() => {
-    workflowMock.reset();
-  });
-
   test("returns approved status when .wait() resolves positively", async () => {
-    workflowMock.setWaitHandler({ approved: true });
+    using wf = mockWorkflow();
+    wf.setWaitHandler({ approved: true });
 
     const result = await processWithApproval.body({ orderId: "order-1" }, { env: {} });
 
     expect(result).toEqual({ orderId: "order-1", status: "approved" });
-    expect(workflowMock.waitCalls[0]).toEqual({
+    expect(wf.waitCalls[0]).toEqual({
       key: "approval",
       payload: { message: "Please approve order order-1", orderId: "order-1" },
     });
   });
 
   test("returns rejected status when .wait() resolves negatively", async () => {
-    workflowMock.setWaitHandler({ approved: false });
+    using wf = mockWorkflow();
+    wf.setWaitHandler({ approved: false });
 
     const result = await processWithApproval.body({ orderId: "order-2" }, { env: {} });
 
@@ -698,19 +708,14 @@ describe("processWithApproval", () => {
 
 #### Running a full workflow locally
 
-To exercise the full chain with real job bodies, call `workflow.mainJob.trigger()`. Dependent jobs run their real `.body()` functions. Use `workflowMock.setEnv()` to control the env value that triggered jobs receive in their context (defaults to `{}`):
+To exercise the full chain with real job bodies, just call `workflow.mainJob.trigger()` — no `mockWorkflow()` needed. Dependent jobs run their real `.body()` functions, and trigger args/results cross the same JSON boundary as the platform, so a non-serializable payload fails the test exactly as it would in production:
 
 ```typescript
-import { workflowMock } from "@tailor-platform/sdk/vitest";
-import { afterEach, describe, expect, test } from "vitest";
+import { describe, expect, test } from "vitest";
 import workflow from "./order-fulfillment";
 
 describe("order-fulfillment workflow", () => {
-  afterEach(() => workflowMock.reset());
-
   test("mainJob.trigger() executes all jobs", async () => {
-    workflowMock.setEnv({ PAYMENT_GATEWAY: "stripe" });
-
     const result = await workflow.mainJob.trigger({ orderId: "order-3", amount: 300 });
 
     expect(result).toMatchObject({ confirmed: true, paymentStatus: "completed" });
@@ -718,6 +723,8 @@ describe("order-fulfillment workflow", () => {
 });
 ```
 
+Acquire `mockWorkflow()` only when you need to override a dependent job with `wf.setJobHandler(...)` / `wf.enqueueResult(...)` (the rest still run their real bodies), control the env via `wf.setEnv(...)`, or assert on `wf.triggeredJobs`.
+
 **Use when:** you want to verify orchestration end to end without the cost of a real deployment.
 
 ## End-to-End (E2E) Tests

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailor-platform/sdk",
-  "version": "1.57.0",
+  "version": "1.59.0",
   "description": "Tailor Platform SDK - The SDK to work with Tailor Platform",
   "license": "MIT",
   "repository": {
@@ -175,14 +175,14 @@
     "pkg-types": "2.3.1",
     "politty": "0.5.1",
     "rolldown": "1.0.3",
-    "semver": "7.8.1",
+    "semver": "7.8.2",
     "sql-highlight": "6.1.0",
     "std-env": "4.1.0",
     "table": "6.9.0",
     "ts-cron-validator": "1.1.5",
     "tsx": "4.22.4",
     "type-fest": "5.7.0",
-    "undici": "8.3.0",
+    "undici": "8.4.0",
     "xdg-basedir": "5.1.0",
     "zod": "4.4.3"
   },
@@ -190,9 +190,9 @@
     "@opentelemetry/sdk-trace-base": "2.7.1",
     "@types/madge": "5.0.3",
     "@types/mime-types": "3.0.1",
-    "@types/node": "24.12.4",
+    "@types/node": "24.13.1",
     "@types/semver": "7.7.1",
-    "@typescript/native-preview": "7.0.0-dev.20260527.2",
+    "@typescript/native-preview": "7.0.0-dev.20260605.1",
     "@vitest/coverage-v8": "4.1.8",
     "oxfmt": "0.53.0",
     "oxlint": "1.68.0",
@@ -221,11 +221,11 @@
   },
   "scripts": {
     "test": "vitest",
-    "test:unit": "vitest --project=unit",
+    "test:unit": "vitest --project=unit*",
     "test:e2e": "vitest --project=e2e",
     "test:coverage": "vitest --coverage",
-    "docs:check": "vitest run --project=unit src/cli/docs.test.ts",
-    "docs:update": "POLITTY_DOCS_UPDATE=true vitest run --project=unit src/cli/docs.test.ts",
+    "docs:check": "vitest run --project=unit* src/cli/docs.test.ts",
+    "docs:update": "POLITTY_DOCS_UPDATE=true vitest run --project=unit* src/cli/docs.test.ts",
     "build": "tsdown",
     "lint": "oxlint --type-aware .",
     "check:public-api-jsdoc": "tsx scripts/check-public-api-jsdoc.ts",