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

package/docs/services/aigateway.md

@@ -0,0 +1,97 @@
+# AI Gateway
+
+AI Gateway provides a unified endpoint for accessing multiple LLM providers (Azure OpenAI, Google Vertex AI Gemini, Anthropic via Vertex AI) through a single OpenAI-compatible API, with platform-managed credentials and workspace-scoped authentication.
+
+## Overview
+
+AI Gateway provides:
+
+- A unified, OpenAI-compatible endpoint for multiple LLM providers
+- Mandatory authentication via your workspace's auth (request tokens are resolved against the configured auth namespace)
+- Per-workspace isolation: each gateway is provisioned with its own platform-assigned URL
+- Optional CORS allow-list for browser-based clients
+- Built-in usage tracking and rate limiting (configured platform-side)
+
+## Configuration
+
+Configure an AI Gateway using `defineAIGateway()`:
+
+**Definition Rules:**
+
+- **Multiple gateways allowed**: You can define multiple AI Gateways in your config file
+- **Configuration location**: Define in `tailor.config.ts` and add to the `aiGateways` array
+- **Uniqueness**: Gateway names must be unique across all AI Gateways
+- **Name pattern**: `name` must match `^[a-z0-9][a-z0-9-]{1,28}[a-z0-9]$` (lowercase alphanumeric and hyphens, 3-30 characters)
+
+```typescript
+import { defineAIGateway, defineConfig } from "@tailor-platform/sdk";
+
+const aiGateway = defineAIGateway("my-aigateway", {
+  authNamespace: "default",
+});
+
+export default defineConfig({
+  aiGateways: [aiGateway],
+});
+```
+
+## Options
+
+### authNamespace
+
+The auth namespace used to resolve request tokens against your workspace's auth configuration. Must match an existing auth namespace.
+
+```typescript
+defineAIGateway("my-aigateway", {
+  authNamespace: "default",
+});
+```
+
+### cors
+
+Optional list of allowed origins for browser-based clients. Each entry is one of:
+
+- `*` — any origin (any scheme, any host)
+- `http(s)://*` — any host on the given scheme
+- `http(s)://*.example.com` — any subdomain of `example.com` on the given scheme
+- `http(s)://app.example.com` — an exact origin
+
+An optional `:port` may be appended in all URL forms. Omitting `cors` (or passing `[]`) disables cross-origin access — browsers will block any cross-origin reads.
+
+```typescript
+defineAIGateway("my-aigateway", {
+  authNamespace: "default",
+  cors: ["https://app.example.com", "https://*.example.com"],
+});
+```
+
+## Complete Example
+
+```typescript
+import {
+  defineAIGateway,
+  defineAuth,
+  defineConfig,
+  defineStaticWebSite,
+} from "@tailor-platform/sdk";
+
+const website = defineStaticWebSite("my-frontend", {
+  description: "Frontend application",
+});
+
+const aiGateway = defineAIGateway("my-aigateway", {
+  authNamespace: "default",
+  cors: [website.url],
+});
+
+const auth = defineAuth("my-auth", {
+  // ...auth configuration...
+});
+
+export default defineConfig({
+  name: "my-app",
+  auth,
+  staticWebsites: [website],
+  aiGateways: [aiGateway],
+});
+```

package/docs/services/auth.md

@@ -139,18 +139,18 @@ export const user = db.type("User", {
 });
 ```
 
-The `attributeList` values are accessible via `user.attributeList` as a tuple:
+The `attributeList` values are accessible via the runtime principal's `attributeList` as a tuple:
 
 ```typescript
 // In a resolver
 body: (context) => {
-  const [organizationId, teamId] = context.user.attributeList;
+  const [organizationId, teamId] = context.caller?.attributeList ?? [];
 },
 
 // In TailorDB hooks
 .hooks({
   field: {
-    create: ({ user }) => user.attributeList[0], // First UUID from list
+    create: ({ invoker }) => invoker?.attributeList[0] ?? null, // First UUID from list
   },
 })
 ```
@@ -160,7 +160,7 @@ body: (context) => {
 When you want to use machine users without defining a `userProfile`, define `machineUserAttributes` instead. These attributes are used for:
 
 - type-safe `machineUsers[*].attributes`
-- `context.user.attributes` typing (via `tailor.d.ts`)
+- runtime principal `attributes` typing (via `tailor.d.ts`)
 
 ```typescript
 import { defineAuth, t } from "@tailor-platform/sdk";
@@ -200,12 +200,12 @@ 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 `user.attributes`:
+**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`:
 
 ```typescript
 // In a resolver
 body: (context) => {
-  const role = context.user.attributes?.role;
+  const role = context.caller?.attributes.role;
 },
 ```
 
@@ -230,25 +230,25 @@ machineUsers: {
 },
 ```
 
-These values are accessible via `user.attributeList`:
+These values are accessible via the runtime principal's `attributeList`:
 
 ```typescript
 // In a resolver
 body: (context) => {
-  const [organizationId, teamId] = context.user.attributeList;
+  const [organizationId, teamId] = context.caller?.attributeList ?? [];
 },
 
 // In TailorDB hooks
 .hooks({
   field: {
-    create: ({ user }) => user.attributes?.role === "ADMIN" ? "default" : null,
+    create: ({ invoker }) => invoker?.attributes.role === "ADMIN" ? "default" : null,
   },
 })
 
 // In TailorDB validate
 .validate({
   field: [
-    ({ user }) => user.attributes?.role === "ADMIN",
+    ({ invoker }) => invoker?.attributes.role === "ADMIN",
     "Only admins can set this field",
   ],
 })
@@ -269,7 +269,7 @@ tailor-sdk machineuser token <name>
 
 ### Specifying a machine user invoker
 
-Resolvers, executors, and `workflow.trigger()` accept an `authInvoker` 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.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`.
 
 ```typescript
 // tailor.config.ts
@@ -298,7 +298,7 @@ export default createResolver({
     // Trigger workflow with machine user permissions
     const workflowRunId = await myWorkflow.trigger(
       { id: input.id },
-      { authInvoker: "admin-machine-user" },
+      { invoker: "admin-machine-user" },
     );
     return { workflowRunId };
   },
@@ -310,8 +310,6 @@ export default createResolver({
 
 Type narrowing is provided by the generated `tailor.d.ts` (the `MachineUserNameRegistry` interface). Run `tailor-sdk generate` (or `apply`) after defining new machine users to refresh it.
 
-> **Deprecated:** The `auth.invoker("<name>")` helper is still available for backward compatibility. Prefer the string form — it does not require importing `auth` from `tailor.config.ts` into runtime files, avoiding bundling config-layer (Node-only) dependencies.
-
 ## OAuth 2.0 Clients
 
 Configure OAuth 2.0 clients for third-party applications:
@@ -515,6 +513,25 @@ export const auth = defineAuth("my-auth", {
 
 **invoker**: The machine user whose permissions are used to execute the hook. Must reference a machine user defined in the same auth configuration.
 
+### Federated identity claims
+
+When a user signs in through a Built-in IdP OAuth provider (Google or Microsoft), the upstream provider's profile is available on `claims.federated_identity`. It is `undefined` for password logins, so guard before reading it. Commonly present claims (`name`, `given_name`, `family_name`, `picture`, `locale`) are typed; any other claim the provider issues is forwarded as-is. Availability varies by provider (for example, Microsoft does not issue `picture`).
+
+```typescript
+hooks: {
+  beforeLogin: {
+    handler: async ({ claims }) => {
+      const federated = claims.federated_identity;
+      if (federated?.provider === "google") {
+        // Populate the user record from the upstream profile
+        const avatarUrl = federated.claims.picture;
+      }
+    },
+    invoker: "hook-invoker",
+  },
+}
+```
+
 ## CLI Commands
 
 Manage Auth resources using the CLI:

package/docs/services/executor.md

@@ -219,7 +219,7 @@ createExecutor({
 });
 ```
 
-Executor callbacks receive the trigger args, including `env` from `defineConfig({ env })`. `function` and `jobFunction` `body` args also include an `invoker` field: the principal running this function, overridden by `authInvoker` when set; `null` for anonymous calls. Other operation kinds (`graphql`, `webhook`, `workflow`) receive `env` through their callback args but do not pass `invoker` into those callbacks.
+Executor callbacks receive the trigger args, including `env` from `defineConfig({ env })`. `function` and `jobFunction` `body` args also include an `invoker` field: the principal running this function, or the machine user configured through the operation `invoker` option; `null` for anonymous calls. Other operation kinds (`graphql`, `webhook`, `workflow`) receive `env` through their callback args but do not pass `invoker` into those callbacks.
 
 ### Job Function Operation
 
@@ -331,7 +331,7 @@ createExecutor({
 
 ### Authentication for Operations
 
-GraphQL and Workflow operations can specify an `authInvoker` 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:
+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:
 
 ```typescript
 import { createExecutor, scheduleTrigger } from "@tailor-platform/sdk";
@@ -342,13 +342,11 @@ export default createExecutor({
   operation: {
     kind: "graphql",
     query: `mutation { cleanupOldRecords { count } }`,
-    authInvoker: "batch-processor",
+    invoker: "batch-processor",
   },
 });
 ```
 
-> **Deprecated:** `auth.invoker("batch-processor")` still works, but is deprecated. Prefer the string form to avoid importing config-layer modules into runtime files.
-
 ## Event Payloads
 
 Each trigger type provides specific context data in the callback functions.

package/docs/services/resolver.md

@@ -208,7 +208,7 @@ Validation functions receive:
 
 - `value` - The field value being validated
 - `data` - The entire input object
-- `user` - The user performing the operation
+- `invoker` - The principal performing the operation
 
 You can specify validation as:
 
@@ -234,13 +234,13 @@ Validation runs automatically before the `body` function executes. When validati
 Define actual resolver logic in the `body` function. Function arguments include:
 
 - `input` - Input data from GraphQL request
-- `user` - The user who called this resolver; unaffected by `authInvoker`
-- `invoker` - The principal running this function; equals `user` by default, or the machine user set by `authInvoker`. `null` for anonymous calls.
+- `caller` - The user or machine user who called this resolver; unaffected by `invoker`. `null` for anonymous calls.
+- `invoker` - The principal running this function; equals `caller` by default, or the machine user configured through the resolver `invoker` option. `null` for anonymous calls.
 - `env` - Environment variables declared in `tailor.config.ts`
 
 ### Using Kysely for Database Access
 
-If you're generating Kysely types with a generator, you can use `getDB` to execute typed queries:
+If you're generating Kysely types with `kyselyTypePlugin`, you can use `getDB` to execute typed queries:
 
 ```typescript
 import { getDB } from "../generated/tailordb";
@@ -306,7 +306,7 @@ createResolver({
 
 - When `publishEvents: true`, resolver execution events are published
 - When not specified, it is **automatically set to `true`** if an executor uses this resolver with `resolverExecutedTrigger`
-- When explicitly set to `false` while an executor uses this resolver, an error is thrown during `tailor apply`
+- When explicitly set to `false` while an executor uses this resolver, an error is thrown during `tailor-sdk deploy`
 
 **Use cases:**
 
@@ -352,7 +352,7 @@ createResolver({
 
 ## Authentication
 
-Specify an `authInvoker` to execute the resolver with machine user credentials. Pass the machine user name as a plain string — it is type-narrowed to the names you defined in your auth config:
+Specify an `invoker` to execute the resolver with machine user credentials. Pass the machine user name as a plain string — it is type-narrowed to the names you defined in your auth config:
 
 ```typescript
 import { createResolver, t } from "@tailor-platform/sdk";
@@ -365,12 +365,10 @@ export default createResolver({
     // Executes as "batch-processor" machine user
     return { result: "ok" };
   },
-  authInvoker: "batch-processor",
+  invoker: "batch-processor",
 });
 ```
 
 The machine user name is looked up in the auth service configured on your app (`machineUsers` in `defineAuth`). The namespace is resolved automatically — no need to import `auth` from `tailor.config.ts` in resolver files.
 
-> **Deprecated:** `auth.invoker("batch-processor")` still works, but is deprecated. Importing `auth` into runtime files pulls config-layer (Node-only) dependencies into the bundle.
-
-**Note:** `authInvoker` controls the permissions for database operations and other platform actions. The `user` object passed to `body` still reflects the original caller, while `invoker` reflects the principal actually running the body.
+**Note:** The `invoker` option controls the permissions for database operations and other platform actions. The `caller` object passed to `body` still reflects the original caller, while the `invoker` body field reflects the principal actually running the body.

package/docs/services/tailordb.md

@@ -260,7 +260,7 @@ Add hooks to execute functions during data creation or update. Hooks receive thr
 
 - `value`: User input if provided, otherwise existing value on update or null on create
 - `data`: Entire record data (for accessing other field values)
-- `user`: User performing the operation
+- `invoker`: Principal performing the operation
 
 #### Field-level Hooks
 
@@ -268,7 +268,7 @@ Set hooks directly on individual fields:
 
 ```typescript
 db.string().hooks({
-  create: ({ user }) => user.id,
+  create: ({ invoker }) => invoker?.id ?? "",
   update: ({ value }) => value,
 });
 ```
@@ -323,7 +323,7 @@ Add validation rules to fields. Validators receive three arguments (executed aft
 
 - `value`: Field value after hook transformation
 - `data`: Entire record data after hook transformations (for accessing other field values)
-- `user`: User performing the operation
+- `invoker`: Principal performing the operation
 
 Validators return `true` for success, `false` for failure. Use array form `[validator, errorMessage]` for custom error messages.
 
@@ -409,6 +409,8 @@ export const user = db.type("User", {
 });
 ```
 
+`db.fields.timestamps()` adds non-null `createdAt` and `updatedAt` datetime fields. Both fields are populated when a record is created; provided values are preserved so seed data can use historical timestamps. `updatedAt` is also refreshed automatically when a record is updated.
+
 ## Type Modifiers
 
 ### Composite Indexes
@@ -461,7 +463,7 @@ db.type("User", {
 
 - When `publishEvents: true`, record creation/update/deletion events are published
 - When not specified, it is **automatically set to `true`** if an executor uses this type with `recordCreatedTrigger`, `recordUpdatedTrigger`, or `recordDeletedTrigger`
-- When explicitly set to `false` while an executor uses this type, an error is thrown during `tailor apply`
+- When explicitly set to `false` while an executor uses this type, an error is thrown during `tailor-sdk deploy`
 
 **Use cases:**
 
@@ -516,8 +518,8 @@ const user = db.type("User", {
   ...db.fields.timestamps(),
 });
 
-// Pick id and createdAt, making them optional
-user.pickFields(["id", "createdAt"], { optional: true });
+// Pick id, createdAt, and updatedAt, making them optional
+user.pickFields(["id", "createdAt", "updatedAt"], { optional: true });
 ```
 
 Available options:
@@ -532,8 +534,8 @@ Available options:
 Return all fields except the specified ones:
 
 ```typescript
-// All fields except id and createdAt
-user.omitFields(["id", "createdAt"]);
+// All fields except id, createdAt, and updatedAt
+user.omitFields(["id", "createdAt", "updatedAt"]);
 ```
 
 #### Common Pattern: Input Schema Composition
@@ -548,9 +550,9 @@ export default createResolver({
   name: "createUser",
   operation: "mutation",
   input: {
-    // id/createdAt are optional (auto-generated), other fields are required
-    ...user.pickFields(["id", "createdAt"], { optional: true }),
-    ...user.omitFields(["id", "createdAt"]),
+    // id/createdAt/updatedAt are optional (auto-generated), other fields are required
+    ...user.pickFields(["id", "createdAt", "updatedAt"], { optional: true }),
+    ...user.omitFields(["id", "createdAt", "updatedAt"]),
   },
   output: t.object({ id: t.uuid() }),
   body: async (context) => {
@@ -567,8 +569,8 @@ import { t } from "@tailor-platform/sdk";
 import { invoice } from "../../tailordb/invoice";
 
 const schemaType = t.object({
-  ...invoice.pickFields(["id", "createdAt"], { optional: true }),
-  ...invoice.omitFields(["id", "createdAt", "invoiceNumber", "sequentialId"]),
+  ...invoice.pickFields(["id", "createdAt", "updatedAt"], { optional: true }),
+  ...invoice.omitFields(["id", "createdAt", "updatedAt", "invoiceNumber", "sequentialId"]),
 });
 ```
 

package/docs/services/workflow.md

@@ -105,11 +105,11 @@ import { sendNotification } from "./jobs/send-notification";
 
 export const mainJob = createWorkflowJob({
   name: "main-job",
-  body: async (input: { customerId: string }) => {
-    const customer = await fetchCustomer.trigger({
+  body: (input: { customerId: string }) => {
+    const customer = fetchCustomer.trigger({
       customerId: input.customerId,
     });
-    const notification = await sendNotification.trigger({
+    const notification = sendNotification.trigger({
       message: "Order processed",
       recipient: customer.email,
     });
@@ -130,31 +130,31 @@ Using `.trigger()` inside a loop works correctly, as long as the loop is determi
 // ✅ OK: deterministic loop — same calls in the same order on every execution
 const regions = ["us", "eu", "ap"];
 for (const region of regions) {
-  const result = await fetchData.trigger({ region });
+  const result = fetchData.trigger({ region });
   results.push(result);
 }
 ```
 
 ```typescript
 // ❌ Bad: non-deterministic — argument changes between executions
-await processJob.trigger({ timestamp: Date.now() });
+processJob.trigger({ timestamp: Date.now() });
 
 // ✅ OK: call Date.now() in separated job
-const timestamp = await timestampJob.trigger();
-await processJob.trigger({ timestamp });
+const timestamp = timestampJob.trigger();
+processJob.trigger({ 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) {
-  await processItem.trigger({ id: item.id });
+  processItem.trigger({ id: item.id });
 }
 
 // ✅ OK: call fetch("https://api.example.com/items").then((r) => r.json()); in separated job
-const items = await fetchItemsJob.trigger();
+const items = fetchItemsJob.trigger();
 for (const item of items) {
-  await processItem.trigger({ id: item.id });
+  processItem.trigger({ id: item.id });
 }
 ```
 
@@ -178,15 +178,15 @@ import { sendNotification } from "./jobs/send-notification";
 // Jobs must be named exports
 export const processOrder = createWorkflowJob({
   name: "process-order",
-  body: async (input: { customerId: string }, { env, invoker }) => {
+  body: (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.
+    // `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 = await fetchCustomer.trigger({
+    const customer = fetchCustomer.trigger({
       customerId: input.customerId,
     });
-    await sendNotification.trigger({
+    sendNotification.trigger({
       message: "Order processed",
       recipient: customer.email,
     });
@@ -356,7 +356,7 @@ export default createWorkflow({
 You can start a workflow execution from a resolver using `workflow.trigger()`.
 
 - `workflow.trigger(args, options?)` returns a workflow run ID (`Promise<string>`).
-- To run with machine-user permissions, pass `{ authInvoker: "<machine-user>" }`. The name is type-narrowed to the machine users defined in your auth config.
+- 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
 import { createResolver, t } from "@tailor-platform/sdk";
@@ -372,7 +372,7 @@ export default createResolver({
   body: async ({ input }) => {
     const workflowRunId = await orderProcessingWorkflow.trigger(
       { orderId: input.orderId, customerId: input.customerId },
-      { authInvoker: "manager-machine-user" },
+      { invoker: "manager-machine-user" },
     );
 
     return { workflowRunId };
@@ -383,8 +383,6 @@ export default createResolver({
 });
 ```
 
-> **Deprecated:** `auth.invoker("manager-machine-user")` still works but is deprecated. Using the string form avoids importing `auth` into runtime code.
-
 See the full working example in the repository: [example/resolvers/triggerWorkflow.ts](https://github.com/tailor-platform/sdk/blob/main/example/resolvers/triggerWorkflow.ts).
 
 ## File Organization