@tailor-platform/sdk 2.0.0-next.0 → 2.0.0-next.2

package/docs/testing.md

@@ -11,18 +11,21 @@ Lean on unit tests for the day-to-day feedback loop — they run fast and exerci
 
 Unit-test entrypoints exposed by the SDK:
 
-- `resolver.body({ input, user, env })` — invoke a resolver
-- `workflowJob.body(input, { env })` / `workflowJob.trigger(input)` — invoke or chain a workflow job
-- `executor.operation.body(args)` — invoke a function-kind executor
+- `resolver.body({ input, caller, invoker, env })` — invoke a resolver
+- `workflowJob.body(input, { env, invoker })` — invoke a workflow job body directly
+- `workflowJob.trigger(input)` — chain a workflow job through the workflow runtime
+- `runWorkflowLocally(workflow, args)` — run a workflow chain locally with real job bodies
+- `executor.operation.body({ ...args, invoker })` — invoke a function-kind executor
 
-Helpers under `@tailor-platform/sdk/test`:
+For anonymous direct calls:
 
-- `unauthenticatedTailorUser` — default `user` value for resolver contexts
+- Pass `null` for anonymous `caller` / `invoker` context in direct unit tests.
 
 Platform API mocks under `@tailor-platform/sdk/vitest` (for use with the [`tailor-runtime` Vitest environment](#runtime-environment-emulation-beta) below):
 
 - `mockTailordb` — TailorDB query stubs and call recording
 - `mockWorkflow` — `tailor.workflow` job / wait / resolve mocks
+- `runWorkflowLocally` — local full-chain workflow runner
 - `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.
@@ -96,7 +99,12 @@ test("resolver queries the database", async () => {
     [], // COMMIT
   );
 
-  const result = await resolver.body({ input: { email: "test@example.com" } });
+  const result = await resolver.body({
+    input: { email: "test@example.com" },
+    caller: null,
+    invoker: null,
+    env: {},
+  });
 
   expect(result).toEqual({ oldAge: 30, newAge: 31 });
   expect(db.executedQueries).toHaveLength(3);
@@ -118,7 +126,12 @@ test("content-based mock", async () => {
     return [];
   });
 
-  const result = await resolver.body({ input: { userId: "1" } });
+  const result = await resolver.body({
+    input: { userId: "1" },
+    caller: null,
+    invoker: null,
+    env: {},
+  });
 
   expect(db.executedQueries[0].query).toContain("SELECT");
 });
@@ -126,7 +139,7 @@ test("content-based mock", async () => {
 
 ### Workflow Mock
 
-`.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`:
+Workflow job `.trigger()` calls use the platform workflow runtime. Acquire `mockWorkflow()` when you want to provide trigger responses with `setJobHandler` / `enqueueResult` or assert on `triggeredJobs`. If no response is configured, the mock throws so missing job mocks fail loudly:
 
 ```typescript
 import { mockWorkflow } from "@tailor-platform/sdk/vitest";
@@ -160,6 +173,8 @@ wf.enqueueResult({ valid: true });
 wf.enqueueResults({ valid: true }, { txnId: "txn-1" });
 ```
 
+Use `wf.setEnv(...)` when locally-run workflow job bodies need configuration values. Per-run `runWorkflowLocally(..., { env })` options take precedence over the mock's env.
+
 ### SecretManager Mock
 
 ```typescript
@@ -262,28 +277,6 @@ test("mock file download stream", async () => {
 });
 ```
 
-For the deprecated `openDownloadStream`, enqueue an iterable of `StreamValue` items — `metadata`, one or more `chunk` items, and a terminal `complete`. Raw `Uint8Array` / `ArrayBuffer` chunks are rejected so tests stay aligned with the platform's structured stream contract.
-
-```typescript
-test("mock file download stream (deprecated openDownloadStream)", async () => {
-  using file = mockFile();
-  file.enqueueResult([
-    {
-      type: "metadata",
-      metadata: { contentType: "image/png", fileSize: 3, sha256sum: "abc" },
-    },
-    { type: "chunk", data: new Uint8Array([1, 2]), position: 0 },
-    { type: "chunk", data: new Uint8Array([3]), position: 2 },
-    { type: "complete" },
-  ]);
-
-  const stream = await tailordb.file.openDownloadStream("ns", "Doc", "attachment", "r-1");
-  const items = [];
-  for await (const item of stream) items.push(item);
-  expect(items).toHaveLength(4);
-});
-```
-
 ### Iconv Mock
 
 ```typescript
@@ -364,7 +357,6 @@ Unit tests call `.body()` (or `.trigger()`) directly on a resolver, workflow job
 For pure logic with no external dependencies, invoke `.body()` directly:
 
 ```typescript
-import { unauthenticatedTailorUser } from "@tailor-platform/sdk/test";
 import { describe, expect, test } from "vitest";
 import resolver from "../src/resolver/add";
 
@@ -372,7 +364,8 @@ describe("add resolver", () => {
   test("adds two numbers", async () => {
     const result = await resolver.body({
       input: { left: 1, right: 2 },
-      user: unauthenticatedTailorUser,
+      caller: null,
+      invoker: null,
       env: {},
     });
     expect(result).toBe(3);
@@ -389,7 +382,6 @@ Stub the global `tailordb.Client` and queue raw query results in order. Best for
 > 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";
 import { afterAll, afterEach, beforeAll, describe, expect, test, vi } from "vitest";
 import resolver from "../src/resolver/incrementUserAge";
 
@@ -419,7 +411,8 @@ describe("incrementUserAge resolver", () => {
 
     const result = await resolver.body({
       input: { email: "test@example.com" },
-      user: unauthenticatedTailorUser,
+      caller: null,
+      invoker: null,
       env: {},
     });
 
@@ -490,7 +483,6 @@ describe("decrementUserAge", () => {
 Pass `mock.db` to functions that take a Kysely instance. When a resolver or executor calls `getDB()` internally there is no such seam, so spy the generated `getDB` and point it at the mock:
 
 ```typescript
-import { unauthenticatedTailorUser } from "@tailor-platform/sdk/test";
 import { createKyselyMock } from "@tailor-platform/sdk/vitest";
 import { describe, expect, test, vi } from "vitest";
 import { getDB, type Namespace } from "../generated/db";
@@ -522,7 +514,8 @@ describe("upsertUsers resolver", () => {
           { name: "Existing", email: "exists@example.com", age: 41 },
         ],
       },
-      user: unauthenticatedTailorUser,
+      caller: null,
+      invoker: null,
       env: { appName: "Resolver Template", version: 1 },
     });
 
@@ -541,7 +534,6 @@ Reach for [`mockTailordb`](#mocking-the-tailordb-client) instead when you want t
 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 { mockWorkflow } from "@tailor-platform/sdk/vitest";
 import { describe, expect, test } from "vitest";
 import resolver from "./resolveApproval";
@@ -556,7 +548,8 @@ describe("resolveApproval resolver", () => {
 
     const result = await resolver.body({
       input: { executionId: "exec-1", approved: true },
-      user: unauthenticatedTailorUser,
+      caller: null,
+      invoker: null,
       env: {},
     });
 
@@ -570,7 +563,7 @@ describe("resolveApproval resolver", () => {
 
 ### Testing Executors
 
-Function-kind executors expose their handler as `executor.operation.body(args)`. The shape of `args` is determined by the trigger — for example, `recordCreatedTrigger({ type: user })` produces `{ newRecord }` typed against the type's output. GraphQL, webhook, and workflow operation kinds are declarative and don't expose a user-authored body to test.
+Function-kind executors expose their handler as `executor.operation.body(args)`. The shape of `args` is determined by the trigger — for example, `recordCreatedTrigger({ type: user })` produces `{ newRecord }` typed against the type's output, plus runtime fields such as `env`, `actor`, and `invoker`. GraphQL, webhook, and workflow operation kinds are declarative and don't expose a user-authored body to test.
 
 The `executor` template extracts shared DB access into a helper (`shared.ts`) and tests the helper directly against a mocked `tailordb.Client` (same TailorDB-mocking pattern as the resolver section). Executor handlers themselves stay thin and can be tested by spying on the helper:
 
@@ -587,6 +580,14 @@ describe("onUserCreated executor", () => {
       throw new Error("expected function operation");
     }
     await onUserCreated.operation.body({
+      workspaceId: "workspace-1",
+      appNamespace: "app",
+      env: {},
+      actor: null,
+      invoker: null,
+      event: "created",
+      rawEvent: "tailordb.type_record.created",
+      typeName: "User",
       newRecord: {
         id: "user-1",
         name: "Alice",
@@ -615,7 +616,7 @@ Workflow jobs expose the same `.body()` entrypoint as resolvers, plus `.trigger(
 
 #### Simple job
 
-Call `.body()` with the input and a stub `{ env: {} }`:
+Call `.body()` with the input and a stub `{ env: {}, invoker: null }`:
 
 ```typescript
 import { describe, expect, test } from "vitest";
@@ -623,14 +624,17 @@ import { validateOrder } from "./order-fulfillment";
 
 describe("validateOrder", () => {
   test("accepts a valid order", () => {
-    const result = validateOrder.body({ orderId: "order-1", amount: 100 }, { env: {} });
+    const result = validateOrder.body(
+      { orderId: "order-1", amount: 100 },
+      { env: {}, invoker: null },
+    );
     expect(result).toEqual({ valid: true, orderId: "order-1" });
   });
 
   test("rejects a non-positive amount", () => {
-    expect(() => validateOrder.body({ orderId: "order-1", amount: 0 }, { env: {} })).toThrow(
-      "Order amount must be positive",
-    );
+    expect(() =>
+      validateOrder.body({ orderId: "order-1", amount: 0 }, { env: {}, invoker: null }),
+    ).toThrow("Order amount must be positive");
   });
 });
 ```
@@ -645,22 +649,25 @@ import { fulfillOrder, processPayment, sendConfirmation, validateOrder } from ".
 
 describe("fulfillOrder", () => {
   test("chains validate → pay → confirm", async () => {
-    using _validateSpy = vi.spyOn(validateOrder, "trigger").mockResolvedValue({
+    using _validateSpy = vi.spyOn(validateOrder, "trigger").mockReturnValue({
       valid: true,
       orderId: "order-1",
     });
-    using _paymentSpy = vi.spyOn(processPayment, "trigger").mockResolvedValue({
+    using _paymentSpy = vi.spyOn(processPayment, "trigger").mockReturnValue({
       transactionId: "txn-order-1",
       amount: 100,
       status: "completed",
     });
-    using _confirmSpy = vi.spyOn(sendConfirmation, "trigger").mockResolvedValue({
+    using _confirmSpy = vi.spyOn(sendConfirmation, "trigger").mockReturnValue({
       orderId: "order-1",
       transactionId: "txn-order-1",
       confirmed: true,
     });
 
-    const result = await fulfillOrder.body({ orderId: "order-1", amount: 100 }, { env: {} });
+    const result = await fulfillOrder.body(
+      { orderId: "order-1", amount: 100 },
+      { env: {}, invoker: null },
+    );
 
     expect(validateOrder.trigger).toHaveBeenCalledWith({ orderId: "order-1", amount: 100 });
     expect(result).toMatchObject({ confirmed: true, paymentStatus: "completed" });
@@ -684,7 +691,10 @@ describe("processWithApproval", () => {
     using wf = mockWorkflow();
     wf.setWaitHandler({ approved: true });
 
-    const result = await processWithApproval.body({ orderId: "order-1" }, { env: {} });
+    const result = await processWithApproval.body(
+      { orderId: "order-1" },
+      { env: {}, invoker: null },
+    );
 
     expect(result).toEqual({ orderId: "order-1", status: "approved" });
     expect(wf.waitCalls[0]).toEqual({
@@ -697,7 +707,10 @@ describe("processWithApproval", () => {
     using wf = mockWorkflow();
     wf.setWaitHandler({ approved: false });
 
-    const result = await processWithApproval.body({ orderId: "order-2" }, { env: {} });
+    const result = await processWithApproval.body(
+      { orderId: "order-2" },
+      { env: {}, invoker: null },
+    );
 
     expect(result.status).toBe("rejected");
   });
@@ -708,22 +721,29 @@ describe("processWithApproval", () => {
 
 #### Running a full workflow locally
 
-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:
+To exercise the full chain with real job bodies, call `runWorkflowLocally(workflow, args)`. 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 { runWorkflowLocally } from "@tailor-platform/sdk/vitest";
 import { describe, expect, test } from "vitest";
 import workflow from "./order-fulfillment";
 
 describe("order-fulfillment workflow", () => {
-  test("mainJob.trigger() executes all jobs", async () => {
-    const result = await workflow.mainJob.trigger({ orderId: "order-3", amount: 300 });
+  test("runWorkflowLocally() executes all jobs", async () => {
+    const result = await runWorkflowLocally(workflow, { orderId: "order-3", amount: 300 });
 
     expect(result).toMatchObject({ confirmed: true, paymentStatus: "completed" });
   });
 });
 ```
 
-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`.
+Pass `{ env }` as the third argument when job bodies need configuration values during the local run.
+
+If you already acquired `mockWorkflow()`, you can also call `wf.setEnv(...)` to reuse the same env across local workflow runs.
+
+Like the platform runtime, the local runner re-runs the orchestrator body once per `.trigger()` call (N triggers means N+1 passes), so any side effects outside the trigger results fire on every pass. Keep the body deterministic and move repeatable side effects into the triggered jobs.
+
+This helper is still a local runner. Use E2E tests when you need to verify deployed workflow scheduling, suspension, or replay behavior.
 
 **Use when:** you want to verify orchestration end to end without the cost of a real deployment.
 
@@ -823,14 +843,13 @@ Use `startWorkflow` from the CLI helpers. It starts the workflow on the deployed
 import { randomUUID } from "node:crypto";
 import { startWorkflow } from "@tailor-platform/sdk/cli";
 import { describe, expect, test } from "vitest";
-import config from "../tailor.config";
 import userProfileSync from "../src/workflow/sync-profile";
 
 describe("user-profile-sync workflow", () => {
   test("executes end to end", { timeout: 180_000 }, async () => {
     const { executionId, wait } = await startWorkflow({
       workflow: userProfileSync,
-      authInvoker: config.auth.invoker("admin"),
+      invoker: "admin",
       arg: {
         name: "workflow-test",
         email: `wf-${randomUUID()}@example.com`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailor-platform/sdk",
-  "version": "2.0.0-next.0",
+  "version": "2.0.0-next.2",
   "description": "Tailor Platform SDK - The SDK to work with Tailor Platform",
   "license": "MIT",
   "repository": {
@@ -9,8 +9,7 @@
     "directory": "packages/sdk"
   },
   "bin": {
-    "tailor-sdk": "./dist/cli/index.mjs",
-    "tailor-sdk-skills": "./dist/cli/skills.mjs"
+    "tailor-sdk": "./dist/cli/index.mjs"
   },
   "files": [
     "CHANGELOG.md",
@@ -135,12 +134,12 @@
     }
   },
   "dependencies": {
-    "@0no-co/graphql.web": "1.2.0",
+    "@0no-co/graphql.web": "1.3.2",
     "@badgateway/oauth2-client": "3.3.1",
     "@bufbuild/protobuf": "2.12.0",
     "@bufbuild/protovalidate": "1.2.0",
-    "@connectrpc/connect": "2.1.1",
-    "@connectrpc/connect-node": "2.1.1",
+    "@connectrpc/connect": "2.1.2",
+    "@connectrpc/connect-node": "2.1.2",
     "@inquirer/core": "11.2.1",
     "@inquirer/prompts": "8.5.2",
     "@jridgewell/trace-mapping": "0.3.31",
@@ -160,10 +159,10 @@
     "chokidar": "5.0.0",
     "confbox": "0.2.4",
     "date-fns": "4.4.0",
-    "es-toolkit": "1.47.0",
+    "es-toolkit": "1.47.1",
     "find-up-simple": "1.0.1",
     "globals": "17.6.0",
-    "graphql": "16.14.1",
+    "graphql": "16.14.2",
     "inflection": "3.0.2",
     "kysely": "0.29.2",
     "madge": "8.0.0",
@@ -174,16 +173,16 @@
     "pathe": "2.0.3",
     "pgsql-ast-parser": "12.0.2",
     "pkg-types": "2.3.1",
-    "politty": "0.5.1",
-    "rolldown": "1.1.0",
-    "semver": "7.8.3",
+    "politty": "0.6.0",
+    "rolldown": "1.1.1",
+    "semver": "7.8.5",
     "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.4.1",
+    "undici": "8.5.0",
     "xdg-basedir": "5.1.0",
     "zod": "4.4.3"
   },
@@ -191,16 +190,16 @@
     "@opentelemetry/sdk-trace-base": "2.8.0",
     "@types/madge": "5.0.3",
     "@types/mime-types": "3.0.1",
-    "@types/node": "24.13.1",
+    "@types/node": "24.13.2",
     "@types/semver": "7.7.1",
-    "@typescript/native-preview": "7.0.0-dev.20260612.1",
+    "@typescript/native-preview": "7.0.0-dev.20260614.1",
     "@vitest/coverage-v8": "4.1.8",
     "oxfmt": "0.54.0",
     "oxlint": "1.69.0",
     "oxlint-tsgolint": "0.23.0",
-    "sonda": "0.11.1",
+    "sonda": "0.13.1",
     "tsdown": "0.22.2",
-    "typescript": "5.9.3",
+    "typescript": "6.0.3",
     "vitest": "4.1.8",
     "zinfer": "0.1.8"
   },
@@ -227,9 +226,11 @@
     "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",
-    "build": "tsdown",
+    "build": "tsdown && politty generate-worker --bin dist/cli/index.mjs --program tailor-sdk --shell zsh --verify",
     "lint": "oxlint --type-aware .",
     "check:public-api-jsdoc": "tsx scripts/check-public-api-jsdoc.ts",
+    "check:zod-isolation": "tsx scripts/check-zod-isolation.ts",
+    "check:import-cycles": "tsx scripts/check-import-cycles.ts",
     "lint:fix": "oxlint --type-aware . --fix",
     "typecheck": "tsc --noEmit",
     "typecheck:go": "tsgo",

package/dist/actor-J2gJ0eK5.d.mts

@@ -1,24 +0,0 @@
-import { A as InferredAttributeList, j as InferredAttributeMap } from "./tailordb-BlBGmQK-.mjs";
-
-//#region src/types/actor.d.ts
-/** User type enum values from the Tailor Platform server. */
-type TailorActorType = "USER_TYPE_USER" | "USER_TYPE_MACHINE_USER" | "USER_TYPE_UNSPECIFIED";
-/** Represents an actor in event triggers. */
-type TailorActor = {
-  /** The ID of the workspace the user belongs to. */workspaceId: string; /** The ID of the user. */
-  userId: string;
-  /**
-   * A map of the user's attributes.
-   * Maps from server's `attributeMap` field.
-   */
-  attributes: InferredAttributeMap | null;
-  /**
-   * A list of the user's attributes.
-   * Maps from server's `attributes` field.
-   */
-  attributeList: InferredAttributeList; /** The type of the user. */
-  userType: TailorActorType;
-};
-//#endregion
-export { TailorActor as t };
-//# sourceMappingURL=actor-J2gJ0eK5.d.mts.map