@tailor-platform/sdk 2.0.0-next.5 → 2.0.0-next.7

package/docs/runtime.md

@@ -31,7 +31,7 @@ const token = await authconnection.getConnectionToken("google");
 const client = new idp.Client({ namespace: "my-namespace" });
 const { users } = await client.users({ first: 10 });
 
-const executionId = await workflow.triggerWorkflow("approval", { reportId });
+const executionId = await workflow.startWorkflow("approval", { reportId });
 
 const invoker = context.getInvoker();
 
@@ -81,7 +81,7 @@ The runtime entry re-exports the following namespaces. Detailed signatures, para
 - `secretmanager` — secret-vault access (`getSecret`, `getSecrets`)
 - `authconnection` — OAuth-style connection tokens (`getConnectionToken`)
 - `idp` — IdP user management (`new Client({ namespace })`)
-- `workflow` — workflow & job control (`triggerWorkflow`, `resumeWorkflow`, `triggerJobFunction`, `wait`, `resolve`)
+- `workflow` — workflow & job control (`startWorkflow`, `resumeWorkflowExecution`, `startJobFunction`, `wait`, `resolve`)
 - `context` — execution context (`getInvoker`)
 - `file` — `tailordb.file` BLOB API (`upload`, `download`, `downloadAsBase64`, `delete`, `getMetadata`, `downloadStream`, `uploadStream`)
 - `aigateway` — AI Gateway URL resolution (`get`)
@@ -97,17 +97,16 @@ import { expect, test } from "vitest";
 
 test("encodes via iconv", () => {
   using iconvM = mockIconv();
-  iconvM.setResolver(() => new Uint8Array([0x82, 0xa0]));
+  iconvM.convert.mockReturnValue(new Uint8Array([0x82, 0xa0]));
 
   const out = iconv.convert("あ", "UTF-8", "Shift_JIS");
 
   expect(out).toEqual(new Uint8Array([0x82, 0xa0]));
-  expect(iconvM.calls[0]?.method).toBe("convert");
+  expect(iconvM.convert).toHaveBeenCalledWith("あ", "UTF-8", "Shift_JIS");
 }); // iconvM disposed here — the iconv mock is removed (previous state restored)
 
 test("reads from a vault", async () => {
-  using sm = mockSecretmanager();
-  sm.setSecrets({ "my-vault": { API_KEY: "sk-123" } });
+  using sm = mockSecretmanager({ secrets: { "my-vault": { API_KEY: "sk-123" } } });
 
   await expect(secretmanager.getSecret("my-vault", "API_KEY")).resolves.toBe("sk-123");
 });

package/docs/services/auth.md

@@ -107,7 +107,7 @@ userProfile: {
 
 **usernameField**: The field in the TailorDB type used as the username. This field must have a unique constraint (`.unique()`) since it is used to uniquely identify users.
 
-**attributes**: Specifies which fields from the TailorDB type are used as user attributes. Set to `true` to enable a field. Enabled attributes must be assigned values in all machine user definitions. Only fields with ValueOperand types (string, boolean, string[], boolean[]) can be used as attributes. The `id` field and datetime/date/time types are excluded.
+**attributes**: Specifies which fields from the TailorDB type are used as user attributes. Set to `true` to enable a field. Machine user definitions must assign values to attributes derived from required fields; attributes derived from optional fields may be omitted (see [Machine Users](#machine-users)). Only fields with ValueOperand types (string, boolean, string[], boolean[]) can be used as attributes. The `id` field and datetime/date/time types are excluded.
 
 ## Attribute List
 
@@ -200,7 +200,7 @@ machineUsers: {
 },
 ```
 
-**attributes**: Values for attributes enabled in `userProfile.attributes` (or all fields defined in `machineUserAttributes` when `userProfile` is omitted). All enabled fields must be set here. These values are accessible via the runtime principal's `attributes`:
+**attributes**: Values for attributes enabled in `userProfile.attributes` (or fields defined in `machineUserAttributes` when `userProfile` is omitted). Attribute keys mirror the field's optionality: attributes derived from required fields must be set, while attributes derived from optional fields may be omitted. Setting an attribute to `null` or `undefined` is equivalent to omitting it — the attribute is deployed as unset. These values are accessible via the runtime principal's `attributes`:
 
 ```typescript
 // In a resolver
@@ -269,7 +269,7 @@ tailor machineuser token <name>
 
 ### Specifying a machine user invoker
 
-Resolvers, executors, and `workflow.trigger()` accept an `invoker` option that chooses which machine user runs the operation. Pass the machine user name as a plain string — it is type-narrowed to the names you registered in `machineUsers`.
+Resolvers, executors, and `workflow.start()` accept an `invoker` option that chooses which machine user runs the operation. Pass the machine user name as a plain string — it is type-narrowed to the names you registered in `machineUsers`.
 
 ```typescript
 // tailor.config.ts
@@ -284,19 +284,19 @@ export const auth = defineAuth("my-auth", {
 ```
 
 ```typescript
-// resolvers/trigger-workflow.ts
+// resolvers/start-workflow.ts
 import { createResolver, t } from "@tailor-platform/sdk";
 import myWorkflow from "../workflows/my-workflow";
 
 export default createResolver({
-  name: "triggerMyWorkflow",
+  name: "startMyWorkflow",
   operation: "mutation",
   input: {
     id: t.string(),
   },
   body: async ({ input }) => {
-    // Trigger workflow with machine user permissions
-    const workflowRunId = await myWorkflow.trigger(
+    // Start workflow with machine user permissions
+    const workflowRunId = await myWorkflow.start(
       { id: input.id },
       { invoker: "admin-machine-user" },
     );

package/docs/services/executor.md

@@ -329,6 +329,11 @@ createExecutor({
 });
 ```
 
+`args` must match the workflow's main job input. It is required when that input is required
+and can be omitted when the workflow has no input. Static arguments can be JSON-compatible
+primitives, arrays, or plain objects; top-level `null` is not supported. An argument callback
+must return the same input type.
+
 ### Authentication for Operations
 
 GraphQL and Workflow operations can specify an `invoker` to execute with machine user credentials. Pass the machine user name as a plain string — it is type-narrowed to the names defined in your auth config:

package/docs/services/tailordb.md

@@ -555,6 +555,48 @@ db.table("User", {
    });
    ```
 
+#### GraphQL Operations
+
+Control which GraphQL operations (`create`, `update`, `delete`, `read`) are exposed for a type. All operations are enabled by default.
+
+```typescript
+db.type("Order", {
+  status: db.string(),
+}).features({
+  gqlOperations: {
+    delete: false, // Disable the delete mutation
+  },
+});
+```
+
+Use the `"query"` alias to disable all mutations at once (read-only type: `create`/`update`/`delete` false, `read` true):
+
+```typescript
+db.type("AuditLog", {
+  action: db.string(),
+}).features({
+  gqlOperations: "query",
+});
+```
+
+**Namespace-level default**
+
+Set a default for every type in a TailorDB namespace in `tailor.config.ts`. A type's own `.features({ gqlOperations })` always takes precedence over this default.
+
+```typescript
+// tailor.config.ts
+export default defineConfig({
+  db: {
+    tailordb: {
+      files: ["./tailordb/*.ts"],
+      gqlOperations: { delete: false }, // Default for every type in this namespace
+    },
+  },
+});
+```
+
+This default is re-evaluated on every `tailor-sdk deploy`, so changing it also updates types that already exist on the platform, not only newly created ones.
+
 ### Field Extraction (`pickFields` / `omitFields`)
 
 Extract subsets of fields from a `TailorDBType` for reuse in resolvers, executors, seed schemas, etc.
@@ -635,6 +677,8 @@ Configure Permission and GQLPermission. For details, see the [TailorDB Permissio
 
 **Important**: Following the secure-by-default principle, all operations are denied if permissions are not configured. You must explicitly grant permissions for each operation (create, read, update, delete).
 
+`generate`/`deploy` reject a type that has no `.permission()`, or no `.gqlPermission()` while GraphQL operations are enabled for it (see [GraphQL Operations](#graphql-operations) above). Disable GraphQL exposure entirely with `.features({ gqlOperations: { create: false, update: false, delete: false, read: false } })` if a type only needs record-level permission.
+
 ```typescript
 db.table("User", {
   name: db.string(),

package/docs/services/workflow.md

@@ -10,7 +10,7 @@ Workflows provide:
 - Durable execution with automatic state management
 - Resume capabilities from failure points
 - Access to TailorDB via Kysely query builder
-- Job triggering to compose multi-step logic
+- Job starting to compose multi-step logic
 
 For the official Tailor Platform documentation, see [Workflow Guide](https://docs.tailor.tech/guides/workflow).
 
@@ -26,12 +26,12 @@ All workflow components must follow these rules:
 - **Job name uniqueness**: Job names must be unique across the entire project (not just within one file)
 - **mainJob required**: Every workflow must specify a `mainJob`
 
-| Rule                                           | Description                                                                                              |
-| ---------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
-| `createWorkflow` result must be default export | Workflow files must export the workflow as default                                                       |
-| All jobs must be named exports                 | Includes `mainJob` and any job triggered via `.trigger()` (even if referenced only within the same file) |
-| Job `name` values must be unique               | Job names must be unique across the entire project                                                       |
-| `mainJob` is required                          | Every workflow must specify a `mainJob`                                                                  |
+| Rule                                           | Description                                                                                          |
+| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `createWorkflow` result must be default export | Workflow files must export the workflow as default                                                   |
+| All jobs must be named exports                 | Includes `mainJob` and any job started via `.start()` (even if referenced only within the same file) |
+| Job `name` values must be unique               | Job names must be unique across the entire project                                                   |
+| `mainJob` is required                          | Every workflow must specify a `mainJob`                                                              |
 
 ## Creating a Workflow Job
 
@@ -92,11 +92,11 @@ export const nullJob = createWorkflowJob({
 
 These constraints are enforced at compile time — you will get a type error if you use an unsupported type.
 
-## Triggering Jobs
+## Starting Jobs
 
-Use `.trigger()` to start other jobs from within a job.
+Use `.start()` to start other jobs from within a job.
 
-Jobs are triggered by calling `.trigger()` on the other job object (no `deps` and no `jobs` object in the context).
+Jobs are started by calling `.start()` on the other job object (no `deps` and no `jobs` object in the context).
 
 ```typescript
 import { createWorkflowJob } from "@tailor-platform/sdk";
@@ -106,10 +106,10 @@ import { sendNotification } from "./jobs/send-notification";
 export const mainJob = createWorkflowJob({
   name: "main-job",
   body: (input: { customerId: string }) => {
-    const customer = fetchCustomer.trigger({
+    const customer = fetchCustomer.start({
       customerId: input.customerId,
     });
-    const notification = sendNotification.trigger({
+    const notification = sendNotification.start({
       message: "Order processed",
       recipient: customer.email,
     });
@@ -120,51 +120,51 @@ export const mainJob = createWorkflowJob({
 
 ### Deterministic Execution Requirement
 
-Workflow jobs use a **suspend/resume execution model**. When a job calls `.trigger()`, the runtime suspends the current job, executes the triggered job, and then **re-executes the calling job from the beginning** with cached results from previous triggers.
+Workflow jobs use a **suspend/resume execution model**. When a job calls `.start()`, the runtime suspends the current job, executes the started job, and then **re-executes the calling job from the beginning** with cached results from previous starts.
 
-This means that **job code must be deterministic** — every re-execution must produce the same sequence of `.trigger()` calls with the same arguments in the same order.
+This means that **job code must be deterministic** — every re-execution must produce the same sequence of `.start()` calls with the same arguments in the same order.
 
-Using `.trigger()` inside a loop works correctly, as long as the loop is deterministic:
+Using `.start()` inside a loop works correctly, as long as the loop is deterministic:
 
 ```typescript
 // ✅ OK: deterministic loop — same calls in the same order on every execution
 const regions = ["us", "eu", "ap"];
 for (const region of regions) {
-  const result = fetchData.trigger({ region });
+  const result = fetchData.start({ region });
   results.push(result);
 }
 ```
 
 ```typescript
 // ❌ Bad: non-deterministic — argument changes between executions
-processJob.trigger({ timestamp: Date.now() });
+processJob.start({ timestamp: Date.now() });
 
-// ✅ OK: call Date.now() in separated job
-const timestamp = timestampJob.trigger();
-processJob.trigger({ timestamp });
+// ✅ OK: call Date.now() in a separate job
+const timestamp = timestampJob.start();
+processJob.start({ timestamp });
 ```
 
 ```typescript
 // ❌ Bad: non-deterministic — external data may change between executions
 const items = await fetch("https://api.example.com/items").then((r) => r.json());
 for (const item of items) {
-  processItem.trigger({ id: item.id });
+  processItem.start({ id: item.id });
 }
 
-// ✅ OK: call fetch("https://api.example.com/items").then((r) => r.json()); in separated job
-const items = fetchItemsJob.trigger();
+// ✅ OK: call fetch("https://api.example.com/items").then((r) => r.json()); in a separate job
+const items = fetchItemsJob.start();
 for (const item of items) {
-  processItem.trigger({ id: item.id });
+  processItem.start({ id: item.id });
 }
 ```
 
-If the runtime detects that a `.trigger()` call at the same position has different arguments than the previous execution, it will throw an **argument hash mismatch error**.
+If the runtime detects that a `.start()` call at the same position has different arguments than the previous execution, it will throw an **argument hash mismatch error**.
 
 **Guidelines:**
 
-- Do not use non-deterministic values (random numbers, timestamps, external API responses) as `.trigger()` arguments.
-- Do not use conditions that may change between executions to decide whether to call `.trigger()`.
-- Any data that varies between executions should be fetched **inside the triggered job**, not passed as an argument from the calling job.
+- Do not use non-deterministic values (random numbers, timestamps, external API responses) as `.start()` arguments.
+- Do not use conditions that may change between executions to decide whether to call `.start()`.
+- Any data that varies between executions should be fetched **inside the started job**, not passed as an argument from the calling job.
 
 ## Workflow Definition
 
@@ -181,12 +181,12 @@ export const processOrder = createWorkflowJob({
   body: (input: { customerId: string }, { env, invoker }) => {
     // `env` contains values from `tailor.config.ts` -> `env`.
     // `invoker` is the principal running this job, or the machine user
-    // configured through the trigger `invoker` option; `null` for anonymous calls.
-    // Trigger other jobs by calling .trigger() on the job object.
-    const customer = fetchCustomer.trigger({
+    // configured through the start `invoker` option; `null` for anonymous calls.
+    // Start other jobs by calling .start() on the job object.
+    const customer = fetchCustomer.start({
       customerId: input.customerId,
     });
-    sendNotification.trigger({
+    sendNotification.start({
       message: "Order processed",
       recipient: customer.email,
     });
@@ -353,7 +353,7 @@ export default createWorkflow({
 
 ## Execution Policies
 
-Execution policies apply a per-key concurrency cap to workflow job function dispatches. Declare them at the workspace level and pass a matching key when triggering a job; the platform serializes dispatches that resolve to the same key and suspends any that would exceed the cap until slots free up.
+Execution policies apply a per-key concurrency cap to workflow job function dispatches. Declare them at the workspace level and pass a matching key when starting a job; the platform serializes dispatches that resolve to the same key and suspends any that would exceed the cap until slots free up.
 
 ### Declaring Policies
 
@@ -401,7 +401,7 @@ An exact-key policy applies to dispatches whose runtime key equals the policy ke
 
 ### Referencing a Policy from a Workflow
 
-Pass the runtime key through the `executionPolicyKey` option on `job.trigger()` or `tailor.workflow.triggerJobFunction()`. For exact-key policies, use `<policy>.key` directly — it's typed so only a value that came from a declared policy can be passed. For wildcard policies (`matchType: "prefix"`), there is no `<policy>.key` — call `<policy>.keyFor(suffix)` to build the concrete key. `keyFor` joins the prefix and suffix with `.` by default; override it with `separator` — the second argument to `defineWorkflowExecutionPolicies` (applies to every policy in the group), or a `def` field on a single `defineWorkflowExecutionPolicy`.
+Pass the runtime key through the `executionPolicyKey` option on `job.start()` or `tailor.workflow.startJobFunction()`. For exact-key policies, use `<policy>.key` directly — it's typed so only a value that came from a declared policy can be passed. For wildcard policies (`matchType: "prefix"`), there is no `<policy>.key` — call `<policy>.keyFor(suffix)` to build the concrete key. `keyFor` joins the prefix and suffix with `.` by default; override it with `separator` — the second argument to `defineWorkflowExecutionPolicies` (applies to every policy in the group), or a `def` field on a single `defineWorkflowExecutionPolicy`.
 
 ```typescript
 import { createWorkflowJob } from "@tailor-platform/sdk";
@@ -413,13 +413,13 @@ export const mainJob = createWorkflowJob({
   name: "main-job",
   body: async (input: { tenantId: string }) => {
     // Exact key policy: pass .key directly.
-    await sendNotification.trigger(
+    await sendNotification.start(
       { message: "Order processed" },
       { executionPolicyKey: executionPolicies.premium.key },
     );
 
     // Wildcard policy: build the concrete key with keyFor().
-    await fetchTenant.trigger(
+    await fetchTenant.start(
       { tenantId: input.tenantId },
       { executionPolicyKey: executionPolicies.tenantApi.keyFor(input.tenantId) },
     );
@@ -427,13 +427,13 @@ export const mainJob = createWorkflowJob({
 });
 ```
 
-The same `executionPolicyKey` option is available on `tailor.workflow.triggerJobFunction(name, args, options)` for jobs invoked by name.
+The same `executionPolicyKey` option is available on `tailor.workflow.startJobFunction(name, args, options)` for jobs invoked by name.
 
-## Triggering a Workflow from a Resolver
+## Starting a Workflow from a Resolver
 
-You can start a workflow execution from a resolver using `workflow.trigger()`.
+You can start a workflow execution from a resolver using `workflow.start()`.
 
-- `workflow.trigger(args, options?)` returns a workflow run ID (`Promise<string>`).
+- `workflow.start(args, options?)` returns a workflow run ID (`Promise<string>`).
 - To run with machine-user permissions, pass `{ invoker: "<machine-user>" }`. The name is type-narrowed to the machine users defined in your auth config.
 
 ```typescript
@@ -441,14 +441,14 @@ import { createResolver, t } from "@tailor-platform/sdk";
 import orderProcessingWorkflow from "../workflows/order-processing";
 
 export default createResolver({
-  name: "triggerOrderProcessing",
+  name: "startOrderProcessing",
   operation: "mutation",
   input: {
     orderId: t.string(),
     customerId: t.string(),
   },
   body: async ({ input }) => {
-    const workflowRunId = await orderProcessingWorkflow.trigger(
+    const workflowRunId = await orderProcessingWorkflow.start(
       { orderId: input.orderId, customerId: input.customerId },
       { invoker: "manager-machine-user" },
     );
@@ -461,7 +461,7 @@ export default createResolver({
 });
 ```
 
-See the full working example in the repository: [example/resolvers/triggerWorkflow.ts](https://github.com/tailor-platform/sdk/blob/main/example/resolvers/triggerWorkflow.ts).
+See the full working example in the repository: [example/resolvers/startWorkflow.ts](https://github.com/tailor-platform/sdk/blob/main/example/resolvers/startWorkflow.ts).
 
 ## File Organization