@tailor-platform/sdk 1.40.1 → 1.43.0

package/docs/services/workflow.md

@@ -60,7 +60,7 @@ export const fetchCustomer = createWorkflowJob({
 
 Workflow job inputs and outputs are serialized as JSON when passed between jobs. This imposes type constraints:
 
-**Input types** must be JSON-compatible — only primitives (`string`, `number`, `boolean`, `null`), arrays, and plain objects are allowed. `Date`, `Map`, `Set`, functions, and other non-serializable types cannot be used.
+**Input types** must be JSON-compatible — primitives (`string`, `number`, `boolean`), arrays, and plain objects are allowed. `Date`, `Map`, `Set`, functions, and other non-serializable types cannot be used. Top-level `null` is also rejected because the platform normalizes top-level `null`/`undefined` args to `{}` (nested `null` inside objects or arrays is preserved).
 
 ```typescript
 // OK
@@ -78,9 +78,17 @@ export const badJob = createWorkflowJob({
     // ...
   },
 });
+
+// Compile error — top-level null would be normalized to {} by the platform
+export const nullJob = createWorkflowJob({
+  name: "null-job",
+  body: async (input: { id: string } | null) => {
+    // ...
+  },
+});
 ```
 
-**Output types** are more permissive — `Date` and objects with `toJSON()` are allowed because they are serialized via `JSON.stringify` at runtime (e.g., `Date` becomes a string).
+**Output types** have the same restriction as inputs: must be JsonValue-compatible (plain objects/arrays; no class instances or functions). Values with methods (function-typed properties) are rejected at compile time — this covers class instances like `Date` or `RegExp` as well as any plain object that exposes a method such as `toJSON()`.
 
 These constraints are enforced at compile time — you will get a type error if you use an unsupported type.
 
@@ -175,8 +183,10 @@ import { sendNotification } from "./jobs/send-notification";
 // Jobs must be named exports
 export const processOrder = createWorkflowJob({
   name: "process-order",
-  body: async (input: { customerId: string }, { env }) => {
+  body: async (input: { customerId: string }, { env, invoker }) => {
     // `env` contains values from `tailor.config.ts` -> `env`.
+    // `invoker` is the principal running this job, overridden by `authInvoker`
+    // when set; `null` for anonymous calls.
     // Trigger other jobs by calling .trigger() on the job object.
     const customer = await fetchCustomer.trigger({
       customerId: input.customerId,
@@ -196,6 +206,110 @@ export default createWorkflow({
 });
 ```
 
+## Wait Points
+
+Wait points allow a workflow job to suspend execution and wait for an external signal before resuming. This enables human-in-the-loop patterns such as approvals, reviews, and manual confirmations.
+
+### Defining Wait Points
+
+Use `defineWaitPoint` to declare a single typed wait point:
+
+```typescript
+import { defineWaitPoint } from "@tailor-platform/sdk";
+
+export const approval = defineWaitPoint<
+  { message: string; requestId: string },
+  { approved: boolean }
+>("approval");
+```
+
+For multiple wait points, use `defineWaitPoints` with a builder callback. Property names become wait point keys, and JSDoc on each property is preserved in IDE autocompletion:
+
+```typescript
+import { defineWaitPoints } from "@tailor-platform/sdk";
+
+export const waitPoints = defineWaitPoints((define) => ({
+  /** Manager approval step */
+  managerApproval: define<{ amount: number }, { approved: boolean }>(),
+  /** Finance review step */
+  financeReview: define<{ invoiceId: string }, { validated: boolean }>(),
+}));
+
+await waitPoints.managerApproval.wait({ amount: 50000 });
+```
+
+Both accept two type parameters:
+
+- **`Payload`** — Data sent when the job suspends (passed to `.wait()`). Must be a pure JSON value (`string`, `number`, `boolean`, `null`, arrays, plain objects). Use `undefined` if no payload is needed.
+- **`Result`** — Data returned when the wait point is resolved (returned from `.wait()`, produced by the `.resolve()` callback). Must be a pure JSON value.
+
+Both must be JsonValue-compatible (plain objects/arrays; no class instances or functions). Values with methods (function-typed properties) are rejected at compile time — this covers class instances like `Date` or `RegExp` as well as any plain object that exposes a method such as `toJSON()`. Convert such values to `string` (e.g. ISO strings) or `number` (epoch millis) before passing them through a wait point.
+
+### Waiting in a Job
+
+Call `.wait()` inside a workflow job body to suspend execution:
+
+```typescript
+import { createWorkflow, createWorkflowJob, defineWaitPoint } from "@tailor-platform/sdk";
+
+export const approval = defineWaitPoint<
+  { message: string; requestId: string },
+  { approved: boolean }
+>("approval");
+
+export const processWithApproval = createWorkflowJob({
+  name: "process-with-approval",
+  body: async (input: { orderId: string }) => {
+    // Suspends here until resolved externally
+    const result = await approval.wait({
+      message: `Please approve order ${input.orderId}`,
+      requestId: input.orderId,
+    });
+
+    if (!result.approved) {
+      return { orderId: input.orderId, status: "rejected" as const };
+    }
+    return { orderId: input.orderId, status: "approved" as const };
+  },
+});
+
+export default createWorkflow({
+  name: "approval-workflow",
+  mainJob: processWithApproval,
+});
+```
+
+### Resolving from a Resolver
+
+Call `.resolve()` from a resolver (or executor) to resume a suspended job. The callback receives the payload that was passed to `.wait()` and returns the result:
+
+```typescript
+import { createResolver, t } from "@tailor-platform/sdk";
+import { approval } from "../workflows/approval";
+
+export default createResolver({
+  name: "resolveApproval",
+  description: "Resolve a waiting approval",
+  operation: "mutation",
+  input: {
+    executionId: t.string(),
+    approved: t.bool(),
+  },
+  body: async ({ input }) => {
+    await approval.resolve(input.executionId, (payload) => {
+      console.log("Resolving:", payload.message);
+      return { approved: input.approved };
+    });
+    return { resolved: true };
+  },
+  output: t.object({
+    resolved: t.bool(),
+  }),
+});
+```
+
+Wait points can be imported and used in any file (workflow jobs, resolvers, executors). For local testing, see [Testing Wait Points](../testing.md#testing-wait-points).
+
 ## Retry Policy
 
 You can configure automatic retry behavior with exponential backoff by setting `retryPolicy` on a workflow. All fields are required when `retryPolicy` is set:

package/docs/testing.md

@@ -10,7 +10,7 @@ npm create @tailor-platform/sdk -- --template testing <your-project-name>
 
 ## Unit Tests
 
-Unit tests verify resolver logic without requiring deployment.
+Unit tests verify resolver and workflow logic locally without requiring deployment.
 
 ### Simple Resolver Testing
 
@@ -171,13 +171,52 @@ describe("decrementUserAge resolver", () => {
 - Mock high-level operations instead of low-level SQL queries
 - **Best for:** Complex business logic with multiple database operations
 
-## Workflow Tests
+### Testing Resolvers that Call `.resolve()`
 
-Test workflows locally without deploying to Tailor Platform.
+Use `setupWaitPointMock` to mock `tailor.workflow.resolve` when testing resolvers that resume a suspended workflow execution.
 
-### Job Unit Tests
+```typescript
+import { afterEach } from "vitest";
+import { setupWaitPointMock, unauthenticatedTailorUser } from "@tailor-platform/sdk/test";
+import resolver from "./resolvers/resolveApproval";
+
+const TailorGlobal = globalThis as { tailor?: { workflow?: Record<string, unknown> } };
+
+describe("resolveApproval resolver", () => {
+  afterEach(() => {
+    delete TailorGlobal.tailor;
+  });
+
+  test("resolves approval", async () => {
+    const { resolveCalls } = setupWaitPointMock({
+      onResolve: (_execId, _key, callback) => {
+        const result = callback({ message: "Please approve", orderId: "order-1" });
+        expect(result).toEqual({ approved: true });
+      },
+    });
+
+    const result = await resolver.body({
+      input: { executionId: "exec-1", approved: true },
+      user: unauthenticatedTailorUser,
+      env: {},
+    });
 
-Test individual job logic by calling `.body()` directly:
+    expect(result).toEqual({ resolved: true });
+    expect(resolveCalls).toHaveLength(1);
+    expect(resolveCalls[0]).toEqual({ executionId: "exec-1", key: "approval" });
+  });
+});
+```
+
+**Key points:**
+
+- `onResolve` lets you verify the callback behavior in resolvers that call `.resolve()`
+- Clean up mocks in `afterEach` by deleting `TailorGlobal.tailor`
+- **Best for:** Resolvers that resume suspended workflow executions
+
+### Workflow Job Unit Tests
+
+Test individual workflow job logic locally without deploying. Call `.body()` directly:
 
 ```typescript
 import workflow, { addNumbers, calculate } from "./workflows/calculation";
@@ -218,9 +257,9 @@ describe("workflow with dependencies", () => {
 
 **Note:** To execute dependent jobs without mocking, and they require `env`, use `vi.stubEnv(WORKFLOW_TEST_ENV_KEY, ...)` and call `.trigger()` directly as shown in the integration test section below.
 
-### Integration Tests with `.trigger()`
+### Workflow Integration Tests with `.trigger()`
 
-Test the full workflow execution using `workflow.mainJob.trigger()`:
+Test the full workflow execution locally using `workflow.mainJob.trigger()`:
 
 ```typescript
 import { WORKFLOW_TEST_ENV_KEY } from "@tailor-platform/sdk/test";
@@ -252,6 +291,55 @@ describe("workflow integration", () => {
 - Use `workflow.mainJob.trigger()` to execute the full workflow chain and get the result
 - **Best for:** Testing workflow orchestration and job dependencies
 
+### Testing Jobs with Wait Points
+
+Use `setupWaitPointMock` to mock `tailor.workflow.wait` when testing jobs that suspend on wait points:
+
+```typescript
+import { afterEach, vi } from "vitest";
+import { setupWaitPointMock } from "@tailor-platform/sdk/test";
+import { processWithApproval } from "./workflows/approval";
+
+const TailorGlobal = globalThis as { tailor?: { workflow?: Record<string, unknown> } };
+
+describe("approval workflow", () => {
+  afterEach(() => {
+    delete TailorGlobal.tailor;
+  });
+
+  test("approved flow returns approved status", async () => {
+    const { waitCalls } = setupWaitPointMock({
+      onWait: (_key, _payload) => ({ approved: true }),
+    });
+
+    const result = await processWithApproval.body({ orderId: "order-1" }, { env: {} });
+
+    expect(result).toEqual({ orderId: "order-1", status: "approved" });
+    expect(waitCalls).toHaveLength(1);
+    expect(waitCalls[0]).toEqual({
+      key: "approval",
+      payload: { message: "Please approve order order-1", orderId: "order-1" },
+    });
+  });
+
+  test("rejected flow returns rejected status", async () => {
+    setupWaitPointMock({
+      onWait: () => ({ approved: false }),
+    });
+
+    const result = await processWithApproval.body({ orderId: "order-2" }, { env: {} });
+
+    expect(result).toEqual({ orderId: "order-2", status: "rejected" });
+  });
+});
+```
+
+**Key points:**
+
+- `onWait` controls what `.wait()` returns — use it to test different branches (approved/rejected)
+- Clean up mocks in `afterEach` by deleting `TailorGlobal.tailor`
+- **Best for:** Jobs that suspend on wait points for human-in-the-loop approval
+
 ## End-to-End (E2E) Tests
 
 E2E tests verify your application works correctly when deployed to Tailor Platform. They test the full stack including GraphQL API, database operations, and authentication.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailor-platform/sdk",
-  "version": "1.40.1",
+  "version": "1.43.0",
   "description": "Tailor Platform SDK - The SDK to work with Tailor Platform",
   "license": "MIT",
   "repository": {
@@ -81,8 +81,8 @@
     "@bufbuild/protobuf": "2.11.0",
     "@connectrpc/connect": "2.1.1",
     "@connectrpc/connect-node": "2.1.1",
-    "@inquirer/core": "11.1.8",
-    "@inquirer/prompts": "8.4.1",
+    "@inquirer/core": "11.1.9",
+    "@inquirer/prompts": "8.4.2",
     "@jridgewell/trace-mapping": "0.3.31",
     "@liam-hq/cli": "0.7.24",
     "@napi-rs/keyring": "1.2.0",
@@ -91,12 +91,12 @@
     "@opentelemetry/resources": "2.7.0",
     "@opentelemetry/sdk-trace-node": "2.7.0",
     "@opentelemetry/semantic-conventions": "1.40.0",
-    "@oxc-project/types": "0.126.0",
+    "@oxc-project/types": "0.127.0",
     "@standard-schema/spec": "1.1.0",
     "@tailor-platform/function-kysely-tailordb": "0.1.3",
-    "@tailor-platform/function-types": "0.8.4",
-    "@toiroakr/lines-db": "0.9.1",
-    "@toiroakr/read-multiline": "0.3.1",
+    "@tailor-platform/function-types": "0.8.5",
+    "@toiroakr/lines-db": "0.9.2",
+    "@toiroakr/read-multiline": "0.3.2",
     "@urql/core": "6.0.1",
     "chalk": "5.6.2",
     "chokidar": "5.0.0",
@@ -113,7 +113,7 @@
     "multiline-ts": "4.0.1",
     "open": "11.0.0",
     "ora": "9.3.0",
-    "oxc-parser": "0.126.0",
+    "oxc-parser": "0.127.0",
     "p-limit": "7.3.0",
     "pathe": "2.0.3",
     "pgsql-ast-parser": "12.0.2",
@@ -123,11 +123,11 @@
     "semver": "7.7.4",
     "serve": "14.2.6",
     "sql-highlight": "6.1.0",
-    "std-env": "4.0.0",
+    "std-env": "4.1.0",
     "table": "6.9.0",
     "ts-cron-validator": "1.1.5",
     "tsx": "4.21.0",
-    "type-fest": "5.5.0",
+    "type-fest": "5.6.0",
     "xdg-basedir": "5.1.0",
     "zod": "4.3.6"
   },
@@ -138,18 +138,18 @@
     "@types/mime-types": "3.0.1",
     "@types/node": "24.12.2",
     "@types/semver": "7.7.1",
-    "@typescript/native-preview": "7.0.0-dev.20260417.1",
+    "@typescript/native-preview": "7.0.0-dev.20260423.1",
     "@vitest/coverage-v8": "4.1.4",
-    "eslint": "10.2.0",
+    "eslint": "10.2.1",
     "eslint-plugin-jsdoc": "62.9.0",
-    "eslint-plugin-oxlint": "1.60.0",
-    "oxfmt": "0.45.0",
-    "oxlint": "1.60.0",
-    "oxlint-tsgolint": "0.20.0",
+    "eslint-plugin-oxlint": "1.61.0",
+    "oxfmt": "0.46.0",
+    "oxlint": "1.61.0",
+    "oxlint-tsgolint": "0.21.1",
     "sonda": "0.11.1",
     "tsdown": "0.21.9",
     "typescript": "5.9.3",
-    "typescript-eslint": "8.58.2",
+    "typescript-eslint": "8.59.0",
     "vitest": "4.1.4",
     "zinfer": "0.1.8"
   },

package/dist/application-CE2s_a6w.mjs

@@ -1,4 +0,0 @@
-
-import { n as generatePluginFilesIfNeeded, r as loadApplication, t as defineApplication } from "./application-EvhIIVg0.mjs";
-
-export { defineApplication };