---
url: https://docs.tailor.tech/administration.md
---
# Administration

Platform administration guides for managing workspaces, accounts, and platform resources.

## Account Management

* [Account Management](account-management.md) - User accounts, organizations, and role-based access control
* [Workspace Management](workspace.md) - Creating and managing workspaces and folders
* [IP Restriction](ip-restriction.md) - IP allowlists at the organization, folder, and application levels
* [Data Retention](data-retention.md) - Data retention policies and compliance
* [Support](support.md) - Getting help and support resources

---

---
url: https://docs.tailor.tech/administration/account-management.md
---
# Platform Account management

The Tailor Platform enables comprehensive account management for admins and developers through the [Console](https://console.tailor.tech).
This functionality is key to managing user permissions, roles, organization accounts, folders, and teams, facilitating effective collaboration and resource organization.

![Platform account management](./assets/platform-account-concept.png)

The Platform implements a hierarchical structure to organize accounts and manage access:

Structure Overview

* Organizations
  * Folders
    * Workspace

* Teams
  * Members

Each level (Organization, Folder, Team) supports role-based access control to help manage permissions efficiently at every layer.

 To get started, please [contact us](https://www.tailor.tech/demo) to create an Organization. 

## Organization

Organization admins and editors manage teams and folders, while viewers can develop apps within assigned workspaces.

Roles and permissions define access and responsibilities.

Every permission is either a **view** or a **manage**. Viewing something is generally granted one role lower than changing it, so a viewer can see how the organization is set up without being able to alter it. The exception is anything that returns a credential — machine users — which stays with admins in both directions.

Here's a list of permissions for each role

| Permission                          | Admin | Editor | Viewer |
| ----------------------------------- | ----- | ------ | ------ |
| View the organization               | ✅    | ✅     | ✅     |
| Modify the organization             | ✅    | 🚫     | 🚫     |
| View organization access controls   | ✅    | ✅     | ✅     |
| Manage organization access controls | ✅    | 🚫     | 🚫     |
| View folders and workspaces         | ✅    | ✅     | ✅     |
| Create folders                      | ✅    | ✅     | 🚫     |
| Modify folders                      | ✅    | ✅     | 🚫     |
| View teams and their members        | ✅    | ✅     | ✅     |
| Create teams                        | ✅    | ✅     | 🚫     |
| Manage team members                 | ✅    | ✅     | 🚫     |
| View IP restrictions                | ✅    | ✅     | ✅     |
| Manage IP restrictions              | ✅    | 🚫     | 🚫     |
| View machine users                  | ✅    | 🚫     | 🚫     |
| Manage machine users                | ✅    | 🚫     | 🚫     |

Organization roles apply all the way down the hierarchy. An organization editor can act on every folder and workspace in the organization without being granted a role on them individually.

## Folders

You can organize workspaces using folders and control team access.
As a Folder admin, you can invite team members individually or an entire team with specific roles, ensuring members only interact with relevant resources.

Here's a list of permissions for each role

| Permission                    | Admin | Editor | Viewer |
| ----------------------------- | ----- | ------ | ------ |
| View the folder               | ✅    | ✅     | ✅     |
| Modify the folder name        | ✅    | 🚫     | 🚫     |
| View folder access controls   | ✅    | ✅     | ✅     |
| Manage folder access controls | ✅    | 🚫     | 🚫     |
| Manage folders                | ✅    | 🚫     | 🚫     |
| Manage sub folders            | ✅    | ✅     | 🚫     |
| View workspaces               | ✅    | ✅     | ✅     |
| Manage workspace              | ✅    | ✅     | 🚫     |
| View IP restrictions          | ✅    | ✅     | ✅     |
| Manage IP restrictions        | ✅    | 🚫     | 🚫     |
| View machine users            | ✅    | 🚫     | 🚫     |
| Manage machine users          | ✅    | 🚫     | 🚫     |

 Sub folder creators are granted admin rights only for the subfolder they create 

Roles are inherited down the folder tree: a role on a folder applies to everything nested inside it. An editor on a parent folder can therefore manage a child folder, including its access controls, even though an editor cannot manage the folder the role was granted on.

To create a new folder from the [Console](https://console.tailor.tech), select the organization, click on the '+' sign, select 'Create new folder', enter the folder name, and click 'Submit'.

![Console Create New Folder](./assets/console-create-new-folder.png)

To create a new workspace, select the organization, click on the '+' sign and select 'Create new workspace'.

![Console Create New Workspace](./assets/console-create-new-workspace.png)

Select the region from the dropdown menu, enter the workspace name, and click 'Submit'.

![Console Create New Workspace Modal](./assets/console-create-new-workspace-modal.png)

## Workspaces

A workspace can be shared with people directly, in addition to whatever access they inherit from the organization or the folder above it.

Here's a list of permissions for each role

| Permission                       | Admin | Editor | Viewer |
| -------------------------------- | ----- | ------ | ------ |
| View the workspace               | ✅    | ✅     | ✅     |
| Modify the workspace             | ✅    | ✅     | 🚫     |
| Delete the workspace             | ✅    | 🚫     | 🚫     |
| View workspace access controls   | ✅    | ✅     | ✅     |
| Manage workspace access controls | ✅    | 🚫     | 🚫     |
| View apps and resources          | ✅    | ✅     | ✅     |
| Create and modify resources      | ✅    | ✅     | 🚫     |
| Run functions and workflows      | ✅    | ✅     | 🚫     |
| View the activity log            | ✅    | ✅     | 🚫     |
| View authentication settings     | ✅    | ✅     | 🚫     |
| Manage secrets                   | ✅    | 🚫     | 🚫     |
| Delete all records in a type     | ✅    | 🚫     | 🚫     |

The activity log and authentication settings are the two reads that stop at editor. Both expose how a workspace is accessed rather than what it contains.

## Teams

You can manage teams by inviting organization members and assigning roles to the team members.

Here's a list of permissions for each role

| Permission                    | Admin | Manager | Member |
| ----------------------------- | ----- | ------- | ------ |
| View the team and its members | ✅    | ✅      | ✅     |
| Modify the team name          | ✅    | 🚫      | 🚫     |
| Manage team members           | ✅    | ✅      | 🚫     |

Team members can see their own team regardless of their organization role.

To create a team in your organization, first select `Settings`, then select the `Teams` tab.

![Console Create New Workspace Modal](./assets/console-create-new-team.png)

---

---
url: https://docs.tailor.tech/administration/data-retention.md
---
# Data Retention

Tailor Platform automatically removes old data after specific retention periods to maintain system performance and optimize storage.
This document outlines the retention periods for different types of data in the platform.

## Retention Periods

Logs for the following data types are automatically removed after their respective retention periods:

| Data Type                  | Description                                                           | Retention Period |
| -------------------------- | --------------------------------------------------------------------- | ---------------- |
| Jobs and Attempts          | Background tasks and their execution attempts in the Executor service | 30 days          |
| Executions                 | Function service execution records                                    | 30 days          |
| Resolver Execution Results | Results of GraphQL resolver operations                                | 30 days          |
| Dataplane Events           | System events from the data plane                                     | 3 days           |
| Controlplane Activity Logs | Platform activity logs from the control plane                         | 90 days          |

After these retention periods expire, the data is permanently deleted from the system and cannot be recovered.

## Impact on Applications

When building applications on the Tailor Platform, be aware of these retention periods and design your data storage and retrieval strategies accordingly. For data that needs to be retained for longer periods, consider implementing custom archiving solutions or exporting the data to external storage systems before the retention period expires.

---

---
url: https://docs.tailor.tech/administration/ip-restriction.md
---
# IP Restriction

IP restriction lets you define an IP allowlist that controls which client IPs can reach your resources.
Requests whose client IP does not match the configured CIDR blocks are rejected at the routing layer, before they reach any application.

You can apply IP restriction at three levels, matching the [account hierarchy](account-management) (Organization → Folder → Workspace, with applications running inside workspaces):

* **Organization** — applies to every workspace in the organization.
* **Folder** — applies to every workspace in a folder.
* **Application** — applies to a single application.

Organization- and folder-level restrictions are managed through the [Tailor Platform Terraform provider](https://registry.terraform.io/providers/tailor-platform/tailor/latest) (version `>= 2.16.0`). Application-level restriction is configured in the [application manifest](/guides/application).

## How the layers combine

When more than one layer is configured, a request must satisfy **all** of them — the layers compose with **AND**. For example, if both an organization-level and a folder-level rule exist, the client IP must match both allowlists to reach a workspace in that folder. A layer with no rule configured imposes no restriction at that level.

## Organization level

Use [`tailor_organization_ip_restriction`](https://registry.terraform.io/providers/tailor-platform/tailor/latest/docs/resources/organization_ip_restriction) to apply an allowlist across every workspace in the organization.

```hcl {{ label: "organization_ip_restriction.tf" }}
resource "tailor_organization_ip_restriction" "this" {
  organization_id = "<organization_id>"
  allowed_ip_addresses = [
    "203.0.113.10/32", # a single public IP
    "198.51.100.0/24", # a public subnet range
  ]
}
```

| Argument               | Type           | Description                                                                                                                                                       |
| ---------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `organization_id`      | String         | The ID of the organization. Changing this forces replacement of the resource. **(required)**                                                                      |
| `allowed_ip_addresses` | List of String | List of allowed IPv4/IPv6 addresses or CIDR blocks. Each entry must be a **public** address; private, loopback, and multicast ranges are rejected. **(required)** |

## Folder level

Use [`tailor_organization_folder_ip_restriction`](https://registry.terraform.io/providers/tailor-platform/tailor/latest/docs/resources/organization_folder_ip_restriction) to apply an allowlist to every workspace in a [folder](account-management#folders). This composes with any organization-level rule (AND).

```hcl {{ label: "organization_folder_ip_restriction.tf" }}
resource "tailor_organization_folder_ip_restriction" "this" {
  organization_id = "<organization_id>"
  folder_id       = "<folder_id>"
  allowed_ip_addresses = [
    "203.0.113.10/32",
    "198.51.100.0/24",
  ]
}
```

| Argument               | Type           | Description                                                                                                                                                       |
| ---------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `organization_id`      | String         | The ID of the organization that owns the folder. Changing this forces replacement of the resource. **(required)**                                                 |
| `folder_id`            | String         | The ID of the folder. Changing this forces replacement of the resource. **(required)**                                                                            |
| `allowed_ip_addresses` | List of String | List of allowed IPv4/IPv6 addresses or CIDR blocks. Each entry must be a **public** address; private, loopback, and multicast ranges are rejected. **(required)** |

## Application level

To restrict access to a single application, set [`AllowedIPAddresses`](/guides/application) in the application manifest. This applies on top of any organization- and folder-level rules.

## Provider configuration

The organization- and folder-level resources require the Tailor Platform Terraform provider:

```hcl {{ label: "provider.tf" }}
terraform {
  required_providers {
    tailor = {
      source  = "tailor-platform/tailor"
      version = ">= 2.16.0"
    }
  }
}

provider "tailor" {}
```

---

---
url: https://docs.tailor.tech/administration/support.md
---
# Customer Support

Tailor provides dedicated customer support to help you with any questions or issues you may encounter while using the Tailor Platform.

## Contact Us

For support inquiries, please reach out to our support team via email:

**Email:** <support@tailor.tech>

## Service Level Agreement (SLA)

Our support team is committed to responding to all inquiries within **48 hours**.

We strive to provide timely and helpful assistance to ensure your success with the Tailor Platform.

---

---
url: https://docs.tailor.tech/administration/workspace.md
---
# Workspace Administration

A [Workspace](/getting-started/core-concepts/workspace-application#workspace) is the top-level namespace in the Tailor Platform for your organization,
containing all applications, including each Tailor Platform service.
Since changing workspace settings affects all the applications within the workspace,
only [Platform users](#what-is-the-platform-user) have permission to manage workspaces.

You can use the interactive mode of `tailor` to view all the options available for workspace management by running the following command.

```bash
tailor workspace
  Commands:
  workspace app                   Manage workspace applications
  workspace create                Create a new Tailor Platform workspace.
  workspace delete                Delete a Tailor Platform workspace.
  workspace get                   Show detailed information about a workspace
  workspace list                  List all Tailor Platform workspaces.
  workspace restore               Restore a deleted workspace
  workspace user                  Manage workspace users
```

Platform users with an admin role can create a new workspace, manage workspace users, and delete the workspace.

By default, a maximum of 10 workspaces can be created per organization.

## What is the Platform user?

The Platform user is the user who can log in to Tailor Platform using the following command:

```bash
tailor login
```

When you sign up for an account, we create a Platform user with an admin role for you to manage your workspace. Please note that the [users you add to your application](/tutorials/setup-auth/login/create-user) are not Platform users and therefore cannot manage your workspace.\
To add a new Platform user, you can invite anyone with a Tailor Platform account to your workspace using the following command:

```bash
tailor workspace user invite --email $userEmailAddress --role $(admin|editor|viewer)
```

Depending on the role assigned, the Platform user will have different permissions to manage workspaces.

## Platform User Permissions

There are three roles for the Platform user: `admin`, `editor` and `viewer`.

### admin

The `admin` role can manage all workspace and application settings.

### editor

The `editor` role can manage all application settings but cannot manage workspace settings.\
However, `editor` users have read permission for the workspace settings they belong to.

### viewer

The `viewer` role can only view all application and workspace settings.

### Here's a list of permissions for each role:

| Permission                    | admin | editor | viewer |
| ----------------------------- | ----- | ------ | ------ |
| **Workspace**                 |       |        |        |
| Create a workspace            | ✅    |        |        |
| Describe a workspace          | ✅    | ✅     | ✅     |
| Delete a workspace            | ✅    |        |        |
| Restore a workspace           | ✅    |        |        |
| Invite users to a workspace   | ✅    |        |        |
| Remove users from a workspace | ✅    |        |        |
| Update platform user role     | ✅    |        |        |
| List workspaces               | ✅    | ✅     | ✅     |
| List services                 | ✅    | ✅     | ✅     |
| List machine users            | ✅    | ✅     |        |
| List platform users           | ✅    | ✅     | ✅     |
| Delete services               | ✅    |        |        |
| List oauth2 clients           | ✅    | ✅     |        |

## Deleting and restoring a workspace

Platform users with an `admin` role can destroy a workspace using the following command:

```bash
tailor workspace delete -w {WORKSPACE_ID}
```

If you need to restore a destroyed workspace, you can do so within 2 weeks of deletion using the following command:

```bash
tailor workspace restore -w {WORKSPACE_ID}
```

After 2 weeks, all data associated with the workspace will be permanently removed and cannot be recovered.

---

---
url: https://docs.tailor.tech/app-shell/quickstart.md
description: Install and set up your first AppShell application
---

# Quick Start

Get your first AppShell application running in minutes.

## Prerequisites

* Node.js 16+
* React 19.2.7+
* A React project (Vite, Next.js, or any bundler)

## Step 1: Install AppShell

```bash
# npm
npm install @tailor-platform/app-shell

# yarn
yarn add @tailor-platform/app-shell

# pnpm
pnpm add @tailor-platform/app-shell
```

## Step 2: Set Up File-Based Routing (Vite)

Add the `appShellRoutes` plugin to your `vite.config.ts`:

```typescript
// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import tailwindcss from "@tailwindcss/vite";
import { appShellRoutes } from "@tailor-platform/app-shell/vite-plugin";

export default defineConfig({
  plugins: [react(), tailwindcss(), appShellRoutes({ entrypoint: "src/App.tsx" })],
});
```

## Step 3: Create Your First App

Add AppShell styles to your global CSS file:

```css
/* index.css */
@import "tailwindcss";
@import "@tailor-platform/app-shell/styles";
```

Create `src/App.tsx`:

```tsx
// src/App.tsx
import { AppShell, SidebarLayout } from "@tailor-platform/app-shell";

function App() {
  return (
    <AppShell title="My ERP App">
      <SidebarLayout />
    </AppShell>
  );
}

export default App;
```

Create your first page at `src/pages/page.tsx`:

```tsx
// src/pages/page.tsx
const HomePage = () => {
  return (
    <div className="astw:p-8">
      <h1 className="astw:text-2xl astw:font-bold">Welcome to AppShell</h1>
    </div>
  );
};

export default HomePage;
```

## Step 4: Run

```bash
npm run dev
```

Navigate to `/` - you should see your page with automatic sidebar navigation.

## Add Nested Pages

Create pages by adding directories and `page.tsx` files:

```
src/pages/
├── page.tsx                        → /
├── dashboard/
│   ├── page.tsx                    → /dashboard
│   └── orders/
│       ├── page.tsx                → /dashboard/orders
│       └── [id]/
│           └── page.tsx            → /dashboard/orders/:id
```

```tsx
// src/pages/dashboard/page.tsx
const DashboardPage = () => {
  return (
    <div className="astw:p-8">
      <h1 className="astw:text-xl astw:font-bold">Dashboard</h1>
    </div>
  );
};

export default DashboardPage;
```

```tsx
// src/pages/dashboard/orders/[id]/page.tsx
import { useParams } from "@tailor-platform/app-shell";

const OrderDetailPage = () => {
  const { id } = useParams();
  return (
    <div className="astw:p-8">
      <h2 className="astw:text-xl astw:font-bold">Order #{id}</h2>
    </div>
  );
};

export default OrderDetailPage;
```

AppShell automatically generates sidebar navigation and breadcrumbs.

[Learn more about File-Based Routing →](concepts/file-based-routing)

## Framework-Specific Notes

### Next.js (App Router)

Next.js does not support file-based routing with the Vite plugin. Use the module-based approach instead:

```tsx
// app/dashboard/[[...props]]/page.tsx
"use client";

import { AppShell, SidebarLayout, defineModule } from "@tailor-platform/app-shell";

const dashboardModule = defineModule({
  path: "home",
  component: () => <div>Home</div>,
  meta: { title: "Home" },
});

export default function Page() {
  return (
    <AppShell title="My App" basePath="dashboard" modules={[dashboardModule]}>
      <SidebarLayout />
    </AppShell>
  );
}
```

See [Modules & Resources](concepts/modules-and-resources) for the module-based API.

## Next Steps

* [File-Based Routing](concepts/file-based-routing) - Define pages via directory structure
* [Routing & Navigation](concepts/routing-navigation) - Navigation hooks
* [Authentication](concepts/authentication) - Set up user authentication
* [Sidebar Navigation](concepts/sidebar-navigation) - Customize sidebar menus
* [Styling & Theming](concepts/styling-theming) - Theming and Tailwind CSS configuration
* [Modules & Resources](concepts/modules-and-resources) - Legacy module-based routing

---

---
url: https://docs.tailor.tech/app-shell/changelog.md
---
# @tailor-platform/app-shell

## 1.13.0

### Minor Changes

* 41ae0e3: Add `filter.operators` on DataTable columns to narrow which conditions the built-in filter UI exposes.

  ```tsx
  column({
    label: "Customer",
    filter: { field: "customer", type: "string", operators: ["contains", "eq"] },
  });
  ```

  `inferColumns()` now also accepts `filter: { operators: [...] }` so metadata-derived columns can use the same restriction.
* fdf7e6a: Bundle Noto Sans JP so `font-medium` is a real weight in Japanese text.

  Inter carries no CJK glyphs, so Japanese fell through to the system font. On Windows that is Yu Gothic UI, which ships only Light/Semilight/Regular/Semibold/Bold — no 500 — so CSS weight matching resolved `font-weight: 500` down to Regular and `font-medium`, the weight behind most labels, table cells and card titles, was indistinguishable from body copy. Current macOS was unaffected, since it ships Hiragino Sans W5. Bundling a variable font makes the weight scale hold on every platform instead of depending on what the OS installs.

  `@tailor-platform/app-shell/styles` now ships Noto Sans JP Variable (continuous 100–900 axis) alongside Inter, metric-harmonised against it so mixed Japanese/Latin strings read at one optical size and a line containing Japanese is exactly as tall as one without. No import change is needed.

  **This changes how Japanese text renders.** Japanese previously drew from the OS font (Hiragino Sans on macOS, Yu Gothic UI on Windows) and now draws from Noto Sans JP. Japanese runs measure about 6% narrower, which can relieve truncation and wrapping but not cause it; Latin is unaffected. Layouts pinned to the old Japanese metrics may need a look.

  It also adds roughly 4.8 MB of woff2 subsets to your build output even if your app renders no Japanese, and takes the stylesheet from about 98 KB to 200 KB uncompressed (15 KB to 45 KB gzipped). The faces are restricted to Japanese codepoint blocks, so users download only the subsets their content touches — nothing at all for an app with no Japanese, ~910 KB for a typical first Japanese screen — and weight costs nothing extra, since every weight shares one file.

  To opt out, or to use a brand font, set the new `--app-shell-font-sans` on `:root` after importing the styles:

  ```css
  @import "@tailor-platform/app-shell/styles";

  :root {
    --app-shell-font-sans: "Your Brand Sans", ui-sans-serif, system-ui, sans-serif;
  }
  ```

  Naming no Japanese family opts out of the download entirely, since each face carries a `unicode-range`. A replacement should be a variable font, or otherwise supply real 400/500/600/700 faces — the weight scale assumes all four exist.

  See [Typography and Fonts](https://github.com/tailor-platform/app-shell/blob/main/docs/concepts/styling-theming.md#typography-and-fonts).
* 891a253: Fix the published type declarations, which referenced types they never declared.

  `dist/app-shell.d.ts` shipped with nine errors inside our own package. Consumers who compile with `skipLibCheck: false` saw all nine attributed to `@tailor-platform/app-shell`, not to their own code. We never noticed because `packages/core/tsconfig.json` sets `skipLibCheck: true`, so neither `pnpm type-check` nor CI ever looked at the declarations we emit.

  Three defects, all now fixed at the source:

  * **`PositionProps` was referenced but never declared.** It is the type of the `position` prop on `Menu.Content` and `Tooltip.Content`, but it was tagged `@internal`, so the declaration rollup stripped it while keeping five references to it. It is now **exported from the package root**, which is the additive change that makes this release a minor: consumers can finally name the type they are required to pass.

    ```tsx
    import { Menu, type PositionProps } from "@tailor-platform/app-shell";

    const dropdown: PositionProps = { side: "bottom", align: "start", sideOffset: 8 };
    <Menu.Content position={dropdown} />;
    ```

  * **`Form` emitted a broken merged declaration** (TS2395). A `function` declaration carrying an expando `displayName` is emitted as a function/namespace merge, and the rollup duplicated the namespace — once exported, once local. `Form` is now a const with an explicit component type, following the same idiom already used by `Select`, `Combobox`, and `Autocomplete`. Its generic is unchanged, so `<Form<MyValues>>` still infers callback values.

  * **`Layout.Header` was emitted as a type instead of a value** (TS2709). `Layout.Header = Header` emitted `var Header: typeof import("./Layout").Header`, which the rollup rewrote to a bare `Header` — a namespace, not a type. `Layout` now uses the explicit `Object.assign` idiom, like `Grid`.

  The public runtime API is unchanged: the built bundle exports exactly the same 100 names as before, and `PositionProps` is a type-only export.

  A `check-dts` gate now runs in CI to keep this from returning. It builds, packs the tarball, installs it into a scratch project, and type-checks every entry point that publishes `types` with `skipLibCheck: false` — the same thing a consumer does. Entry points are read from `package.json`, so new ones are covered as soon as they are added.
* 7e1a1e3: Expand the re-exported React Router surface so an app never needs `react-router` as a direct
  dependency, and add `memory` routing to `AppShell` for tests.

  AppShell owns the router — it builds the route tree, constructs the router, and renders the
  `RouterProvider`. An app that also resolves its own copy of `react-router` ends up with two
  copies in the bundle and two unrelated router contexts: AppShell's navigation keeps working
  while the app's own `useNavigate` / `useLocation` / `<Link>` throw
  `may be used only in the context of a <Router> component`, with nothing for TypeScript to catch.
  Apps were reaching for a direct dependency because the re-exported surface was incomplete. This
  closes those gaps.

  **Newly available from `@tailor-platform/app-shell`:**

  * `useMatch`, `useResolvedPath` — route matching, for active states and relative paths
  * `useNavigation` — the in-flight navigation, for pending UI
  * `NavLink` — a link that knows when it is active
  * `useBlocker`, `useBeforeUnload` — guard navigation away from unsaved changes
  * Types: `Location`, `NavigateFunction`, `NavigateOptions`, `To`, `Params`, `PathMatch`,
    `LinkProps`, `NavLinkProps`, `Navigation`, `Blocker`, `BlockerFunction`

  **New `@tailor-platform/app-shell/testing` entry point**, so tests need no `react-router` either:

  * `AppShell` — the same shell, additionally accepting `memory` / `initialEntries` to mount at a
    fixed URL without touching `window.location`. For page and integration tests.
  * `TestRouter` — a minimal router context for unit-testing a single component that uses
    `useNavigate` or renders a `<Link>`, without booting the whole shell. Pass `path` when the
    component reads the route (`useParams`, `useMatch`), so the location matches something.

  ```tsx
  import { AppShell, TestRouter } from "@tailor-platform/app-shell/testing";

  render(
    <AppShell memory initialEntries={["/orders/A42"]} modules={modules}>
      <SidebarLayout />
    </AppShell>,
  );
  ```

  Memory routing is reachable only from `/testing`. The production `AppShell` pins it off, so it
  holds for JS callers and `any` spreads as well as typed ones.

  Router construction (`createBrowserRouter`, `RouterProvider`, `MemoryRouter`, `Routes`, `Route`)
  and the data-router APIs (`useLoaderData`, `useSubmit`, `useFetcher`, `useActionData`) remain
  deliberately unexported: AppShell owns the former and does not wire up the latter. If something
  you need is missing, ask for it rather than adding a direct `react-router` dependency.
* 719ba91: Add standalone `Textarea` component

  * New `Textarea` — a styled multi-line text control wrapping Base UI's field control rendered as a `<textarea>`. Integrates with `Field` and React Hook Form for label association, `aria-describedby`, `disabled`, and invalid/error state exactly like `Input`/`Checkbox` (no bespoke `error` prop), and works standalone outside a `Field.Root`. The invalid state is styled off both `data-invalid` (AppShell `Field.Root`) and `aria-invalid` (shadcn-style `FormControl`), so it fits either form stack.
  * Unlike `Input`, it has no fixed height: `rows` sets the visible line count, `min-h-16` is the floor, and `resize-y` lets the user drag it taller. Previously the only multi-line route was `<Field.Control render={<textarea />} />`, which inherited the single-line `h-9` and clipped the box to 36px.
  * `cols` and `wrap` are not accepted: the control is always `w-full`, so `cols` can never affect its width, and per the HTML spec every `wrap` value depends on `cols` being set. `className` is typed as `string` rather than Base UI's `string | ((state) => string | undefined)`, because it is merged through `cn()`, which silently drops a function.
  * Internal: `inputBaseClasses` now composes from a shared `controlBaseClasses` so `Input` and `Textarea` keep the same border/focus/placeholder treatment while owning their own height and padding. The emitted class list for `Input` and `Field.Control` is unchanged apart from ordering.

### Patch Changes

* 7b08250: Fix sessions hanging permanently after the server rejects the grant, by raising `@tailor-platform/auth-public-client` to `^0.6.1`. The new floor also picks up 0.6.1's callback-URL cleanup: a failed OAuth callback no longer leaves `?code=` / `?error=` in the URL, and cleanup on every outcome preserves unrelated query parameters, the hash, and the router's history state.

  When a refresh token expired or was revoked, the auth client kept `isAuthenticated` true and reattached the dead token to every request, so apps sat in a permanent `{"errors":[{"message":"unauthorized","type":"Gateway"}]}` loop that only a manual IndexedDB clear recovered from. Any token-endpoint rejection now ends the session (`use_dpop_nonce` excepted), emitting `logout` and `auth_state_changed`. `AuthProvider` responds as it already does for a signed-out user: `guardComponent` renders, and with `autoLogin` the app redirects to sign-in. A timeout, a network failure, and a plain 5xx still leave the session intact. Note that the boundary is the response shape rather than the underlying cause: any 4xx carrying an `error` code ends the session, so a token endpoint that reports overload as `400 {"error":"server_error"}` will sign users out.

  One behaviour change worth checking even though this is a patch: `fetch` and `getAuthHeaders` no longer throw `Error("No valid access token")` when a refresh is rejected — they throw the underlying error. If your app detects dead sessions by matching that message, it has stopped detecting them; listen for `logout` / `auth_state_changed` instead, which fire on exactly that condition. Grepping the installed package for the string will not tell you whether you are affected, because the throw still exists for the genuinely-no-token case — check your own error handling.
* 17a03fe: Fix `autoLogin` being permanently disabled after a failed OAuth callback.

  `@tailor-platform/auth-public-client` cleans the callback parameters out of the URL only when the code exchange succeeds; every failure path leaves `?code=` or `?error=` in the query string (tailor-platform/auth-public-client#139). `AuthProvider` decided whether a callback was in progress by reading that URL, so after any failed callback it treated the page as a live callback forever: auto-login never fired again, the app sat on `guardComponent`, and reloading only replayed the same failing callback.

  Auto-login now decides from the callback's status rather than the URL — which is what the check meant all along: "is an exchange in flight", not "has this page ever been a callback". The URL is still the authority when no callback has been claimed at all, where redirecting away from unconsumed parameters would be unsafe.

  It will not loop, either. A recoverable failure is retried once per tab; beyond that, and for any refusal the authorization server issues explicitly, AppShell stops rather than redirecting the user back for the same answer. The outcome is classified from the resulting auth state rather than from whether the callback threw, because two failure paths — a server `error` and a state mismatch — return normally after recording the error.

  That makes `guardComponent` where a failed sign-in becomes visible: a guard that only renders a spinner will spin indefinitely, so render `useAuth().error` and offer a retry. See the authentication guide.

  The stale parameters themselves remain in the URL after a failure until the cleanup is fixed upstream (tailor-platform/auth-public-client#139) — app-shell no longer misbehaves because of them, but deliberately does not reimplement the library's URL cleanup.

## 1.12.0

### Minor Changes

* 6171c84: Add a `render` escape hatch to `DescriptionCard` fields, so custom rendering no longer requires a new built-in field type.

  ```tsx
  <DescriptionCard
    data={orderData}
    title="Order"
    fields={[
      { key: "orderNumber", label: "Order Number" }, // default text
      { key: "status", label: "Status", type: "badge" }, // preset
      {
        key: "deliveryBreakdown",
        label: "Delivery",
        render: (data) => <PieChart data={data.deliveryBreakdown} />,
      },
    ]}
  />
  ```

  `render` receives the whole `data` object — the same shape as `render` on DataTable's `Column`, which takes the whole row. Destructure the keys you need, and a field can be derived from several at once:

  ```tsx
  {
    key: "total",
    label: "Balance Due",
    render: ({ total, amountPaid, currency }) => (
      <Money amount={total - amountPaid} currency={currency} />
    ),
  }
  ```

  Semantics match DataTable's `render`: it always wins over `type`, and its return value replaces the built-in output entirely (so `meta` — copy button, truncation, badge maps, the `–` placeholder — is not applied). `key` is still required; it identifies the field and is what `emptyBehavior` tests, but it is not resolved into a value for `render`. A custom renderer still runs when the value at `key` is empty; `emptyBehavior: "hide"` is checked first.

  `DescriptionCard` is now generic over the shape of `data`, inferred from the `data` prop, so everything `render` reaches for keeps its declared type. This is backward compatible — `DescriptionCardProps` defaults to `Record<string, unknown>`. To declare a fields array separately, parameterise it so `render` callbacks stay typed:

  ```tsx
  const fields: DescriptionCardProps<Order>["fields"] = [...];
  ```

* 08c29d6: Add expandable detail rows to `DataTable`. Pass `rowExpansion` to `useDataTable` and each row gets a chevron column (auto-pinned to the left edge, after the selection column) that reveals a full-width detail panel beneath the row — nothing new to compose in JSX.

  ```tsx
  const table = useDataTable<Order>({
    columns,
    data,
    control,
    rowExpansion: {
      render: (row) => <OrderLineItems orderId={row.id} />,
      canExpand: (row) => row.lineItemCount > 0,
      getLabel: (row) => row.orderNumber, // → "Expand row INV-1001"
    },
  });
  ```

  Rows must have a string or number `id` (the same constraint as row selection); rows without one render no chevron. Several rows can be open at once, and expansion survives page changes — `collapseAllRows()` resets it. Pass `expandedIds` + `onChange` inside `rowExpansion` to control expansion yourself; the type requires them together, so a half-configured controlled table is a compile error rather than inert chevrons.

  Also fixes `onSelectionChange` firing twice per toggle under React StrictMode. It was dispatched from inside a state updater, which StrictMode intentionally double-invokes to surface impurity, so handlers doing real work (fetches, analytics, history entries) ran twice in development. It is now dispatched from the event handler and fires exactly once. No signature change; if you added your own de-duplication to work around this, it is no longer needed.

* b5289fc: Re-export react-router's `Navigate`, so apps no longer need `react-router` as a direct dependency for declarative redirects.

  ```tsx
  import { Navigate } from "@tailor-platform/app-shell";

  if (!allowed) return <Navigate to="/dashboard" replace />;
  ```

  See [Declarative Redirects](https://github.com/tailor-platform/app-shell/blob/main/docs/concepts/routing-navigation.md#declarative-redirects) for when to prefer the route-level `redirectTo()` guard instead.

* fd2f4bc: Refactor `DateField` / `DatePicker` to follow the same composition model as `Field`, `Select`, `Combobox`, and `Autocomplete`.

  The date controls are now **control-first**: field chrome moved out of the control props and into `Field.Root` composition. They also interoperate correctly with `Form` / `Field.Root` label wiring, `onFormSubmit` value collection, and submit-time validation for required and out-of-range default values.

  Breaking changes:

  * `label`, `description`, and `errorMessage` were removed from `DateField` / `DatePicker`; compose them with `Field.Root`, `Field.Label`, `Field.Description`, and `Field.Error` instead.
  * `hideTimeZone` was removed; it was previously accepted by the prop types but had no effect.

  `isInvalid` still remains a top-level prop for externally-controlled invalid styling, and the semantic date props (`isRequired`, `isDisabled`, `isReadOnly`, `minValue`, `maxValue`, `isDateUnavailable`) remain top-level and aligned with `Calendar`.

  Before:

  ```tsx
  <DatePicker
    label="Delivery date"
    description="When should we ship your order?"
    minValue={today(getLocalTimeZone())}
    errorMessage={error}
    isInvalid={!!error}
  />
  ```

  After:

  ```tsx
  <Field.Root invalid={!!error}>
    <Field.Label>Delivery date</Field.Label>
    <DatePicker
      aria-label="Delivery date"
      minValue={today(getLocalTimeZone())}
    />
    <Field.Description>When should we ship your order?</Field.Description>
    <Field.Error match={!!error}>{error}</Field.Error>
  </Field.Root>
  ```

  Standalone usage still works with accessible naming:

  ```tsx
  <DateField aria-label="Invoice date" />
  ```

* fa587b2: Bridge `--alert-*` tokens into Tailwind's theme as `--color-alert-*`

  The `--alert-*` design tokens (`neutral` / `success` / `warning` / `error` / `info` × `background` / `foreground` / `foreground-muted` / `border`) are now exposed through `@theme inline`, matching how `--status-*` is already bridged.

  Application code can now use ordinary color utilities for callouts, banners, and status-highlighted rows:

  ```tsx
  // Before — arbitrary values, no autocomplete, silent failure on a typo
  <div className="bg-[color:var(--alert-info-background)] text-[color:var(--alert-info-foreground)]" />

  // After
  <div className="bg-alert-info-background text-alert-info-foreground" />
  ```

  This is purely additive — existing arbitrary-value usage keeps working, and the generated CSS is unchanged.

* 1a768e1: Add `DateRangePicker` and `RangeCalendar` components with a `{ start, end }` range value (exported as `DateRange`). Selection follows the react-aria model: the first calendar pick anchors the range and keeps the popover open, the highlight live-extends to the hovered/focused day, and the second pick completes it — picking backwards swaps the endpoints, while a range typed in reverse is flagged invalid instead of swapped.

  Like `DateField` / `DatePicker`, they are standalone composite controls that also compose inside `Field.Root` (label / description / error / form validation). A single combined proxy input is registered as the one Field control (empty until both ends are complete, so `isRequired` blocks a partial range); `name` gives that combined input a name for native POST (`start/end`, with a wrapping `Field.Root` name taking precedence), while `startName` / `endName` emit two plain hidden inputs for classic form POST.

  ```tsx
  import {
    DateRangePicker,
    Field,
    type DateRange,
  } from "@tailor-platform/app-shell";

  const [range, setRange] = useState<DateRange | null>(null);

  // standalone
  <DateRangePicker
    aria-label="Billing period"
    value={range}
    onChange={setRange}
  />;

  // composed
  <Field.Root name="period">
    <Field.Label>Billing period</Field.Label>
    <DateRangePicker />
    <Field.Error match="customError" />
  </Field.Root>;
  ```

### Patch Changes

* 8b72b55: Document how to remove the `@theme` bridge workaround, which silently breaks dark mode on 1.7+.

  Apps that pasted the `@theme inline` block, `@custom-variant dark (&:is(.dark *))`, and a copy of the palette into their entry CSS (the workaround while `styles` shipped without the bridge, 1.5.0–1.6.1) keep those definitions winning over AppShell's own palette, because the default palette is imported inside `layer(theme.defaults)` and consumer CSS is unlayered. The build succeeds with no warning, but surfaces added since the copy render light-mode colours in dark mode.

  Adds `docs/migrations.md`, a curated list of breaking changes and the steps each one requires, newest first — separate from the changelog so upgraders and AI agents have one narrow place to look. The first entry covers detecting and removing this workaround, including the requirement to be on 1.7.0 or later first, since the workaround is load-bearing before that.

  That page now ships with the package. The published tarball contains only `dist/**` and `skills/**` — no `docs/`, no `CHANGELOG.md` — so a consumer app previously had no migration record available locally at all. `docs/migrations.md` is generated into the bundled `app-shell-patterns` skill as `references/migrations.md` (with relative links rewritten to repo URLs), and the skill now names upgrades and post-version-bump styling breakage among its triggers, so coding agents reach it from `node_modules`. `packages/core/README.md` links it for the human path, since the README is the only human-readable file npm publishes.

  `docs/concepts/styling-theming.md` and the bundled `app-shell-patterns` skill now document `:root` / `:root.dark` as the override form to use. A bare `.dark` override silently loses against the branded palettes (`cream`, `bloom`), which are imported unlayered and define their dark values on `:root.dark`.

* 2a3f5e6: Polish the built-in sidebar search entry so it looks more like a compact text field.

  The search affordance now shows the platform-specific keyboard shortcut (`⌘K` on Apple platforms, `Ctrl+K` elsewhere) and uses subtler spacing and typography.

* 45218cc: Fix the bundled `app-shell-patterns` skill, whose `design-system.md` documented a token system that does not exist in the package. Agents read it as canonical and emitted classes like `bg-surface-1`, `text-fg-default`, and `bg-danger`, which produce no CSS at all — a silent failure with no error or warning.

  Tokens, dark mode (`.dark` on `<html>`), elevation, z-index, and the `styles` import now match the shipped CSS, and the fabricated spacing, typography, motion, and icon scales are gone in favour of stock Tailwind. Also drops references to `Icon` and `Stat`, which aren't exported, and to a `Sheet` `contentClassName` prop that doesn't exist.

  Documentation only — no runtime or CSS changes.

## 1.11.0

### Minor Changes

* af7bd0f: Make `Sheet` omit its backdrop automatically when `modal={false}` so non-modal sheets no longer dim or block the page.

  ```tsx
  <Sheet.Root modal={false}>
    <Sheet.Content>...</Sheet.Content>
  </Sheet.Root>
  ```

### Patch Changes

* 8cdb5cd: DataTable filter and column UI fixes:

  * **Filter placement & style**: `DataTable.Filters` now renders the **Add filter** trigger on the **left** by default (was right-aligned), with active chips flowing to its right, and the trigger is **icon-only by default** (the label is kept as an `aria-label`). Pass `addIconOnly={false}` to show the "Add filter" text label. The add-filter popover now anchors to the left edge of the trigger.
  * **Pinned columns**: closed a sub-pixel gap between adjacent frozen columns where scrolling rows could bleed through — column offsets are now measured with fractional widths so pinned columns sit flush.
  * **Column settings popup**: added a search box at the top that filters the **Scrollable** column list by name, and that list now scrolls within a height cap while the **Fixed left** / **Fixed right** zones and the Show/Hide-all footer stay pinned and always fully visible — so the popup stays within the viewport even with many columns. Drag-to-reorder and drag-between-zones keep working while searching. The popup width is capped so long column names truncate.
  * **Add-filter panel**: the field picker now has a **search box** to quickly find a field, and the field column hugs the field-name width (up to a cap) so names aren't needlessly truncated while the value editor keeps its width.
  * **Truncated names**: long field/column names in the add-filter and column-settings pickers carry a native `title` so the full text shows on hover.

* 492c2bb: Upgrade AppShell to React Router v8 and raise the minimum supported `react` / `react-dom` version to `19.2.7`.

* 09fcaa8: Update the internal Base UI dependency to v1.6.0.

## 1.10.1

### Patch Changes

* adf2119: Fix `DataTable` empty/error-state message not being vertically centered — it now
  centers in the reserved area instead of sitting near the top. The message was
  positioned with `position: sticky`, whose offset only applies while scrolling,
  so in the common (non-scrolling) case it stayed at the top of the cell; it now
  uses `vertical-align: middle`.
* f45aa47: Raise the bundled `react-router` dependency to the latest v7 release.

  This picks up the current v7 security and hardening fixes while avoiding the breaking changes in React Router v8.

## 1.10.0

### Minor Changes

* 73d0c0a: Add a built-in error state to `Combobox.Async`, `Autocomplete.Async`, and `Select.Async`

  When an async fetcher throws or rejects, the components now render an inline error state in the popover — a "Couldn't load results." message plus a **Retry** button that re-runs the last fetch — instead of silently falling back to the misleading "No results." empty state. This makes failed fetches distinguishable from genuinely-empty results without any consumer code.

  The debounce/abort lifecycle is handled centrally: aborted/superseded requests are ignored, and outages are de-duped so typing during an outage doesn't stack repeated announcements.

  Three new props on each `.Async` component:

  | Prop           | Type                       | Default                    | Description                                                        |
  | -------------- | -------------------------- | -------------------------- | ------------------------------------------------------------------ |
  | `errorText`    | `string`                   | `"Couldn't load results."` | Message shown in the popover when the fetcher fails                |
  | `retryText`    | `string`                   | `"Retry"`                  | Label for the retry button                                         |
  | `onFetchError` | `(error: unknown) => void` | -                          | Called once per outage when a fetch fails (logging/error tracking) |

  The `Combobox.useAsync` / `Autocomplete.useAsync` / `Select.useAsync` hooks now also expose `error` and a `retry()` function and accept an `onFetchError` option, for consumers building custom compositions with `Parts`.

* 16c1046: Add a built-in `/__appinfo` page to `AppShell` for exposing app metadata and the current AppShell version.

  ```tsx
  <AppShell
    title="My App"
    appInfo={{
      metadata: [
        { label: "Environment", value: "staging" },
        { label: "Release", value: "2026.07.16" },
      ],
    }}
  />
  ```

  The page stays out of AppShell's built-in auto-generated sidebar navigation, appears in the Command Palette as a page entry, and includes a copy button for the rendered app information.

* 35ab98a: DataTable: sticky/pinned columns and user column settings

  * **Pinned columns** — add `pin: "left" | "right"` to a `Column` to freeze it during horizontal scroll (sticky offsets are measured from the rendered layout; `width` is optional but recommended for stable sizing). The selection column auto-pins left and the row-actions column auto-pins right, with a subtle freeze shadow at the frozen edge once content scrolls under it.
  * **Column settings** — pass `columnSettings` to `DataTable.Toolbar` to render a built-in "Columns" control (top-right) that lets users show/hide columns, reorder them (drag), and change pinning by dragging a column between the Fixed left / Scrollable / Fixed right zones.
  * **Persisted column layout** — pass a stable `tableId` to `useDataTable` to persist each user's column visibility, order, and pinning to `localStorage` (per-user preference; not stored in the URL). Omit for in-memory-only layout.
  * `Table.Root` now accepts an optional `containerRef` for its scroll container.

* b32f003: Redesign `DataTable.Filters` for a faster, more direct filtering experience.

  * **Add-filter panel**: replaces the old popover + nested selects with a single popover laid out in up to three columns — **field ▸ condition ▸ value**. The condition column appears for fields with more than one operator; single-operator fields (enum, uuid) go straight to the value. Values are drafted and committed with an **Apply**/**Update** button, and the panel stays open so several filters can be added in a row. A per-field **Clear** and a sticky **Clear all filters** are built in.
  * **Segmented filter chips**: each active filter renders as `field │ operator │ value │ ✕`. The operator segment opens a searchable dropdown to switch the condition; the value segment opens the type-specific editor. Long values are truncated.
  * **Date & time use app-shell's own components**: single date → inline `Calendar`; single datetime → inline calendar + a "Choose time" picker; `date`/`datetime` **between** → one inline calendar with **From / To** tabs; `time` → native time input. (Swaps to the dedicated date-range / datetime pickers 1:1 once those land.)
  * Friendlier operator labels (`is`, `is not`, `is between`, `is any of`, …), multi-select enum values summarized as "N items" (localized), an inline error for reversed `between` ranges, and a consistent primary-colored checkbox across every filter surface.
  * **New `slot` prop** on `DataTable.Filters` (`"all"` | `"chips"` | `"add"`) to render the chips and the **Add filter** trigger separately for custom toolbar layouts (e.g. trigger in a header row, chips on the row below).

* 19bc874: Add `header` to DataTable columns so consumers can fully customize header UI while keeping the built-in header behavior when `header` is omitted.

  ```tsx
  column({
    label: "Amount",
    sort: { field: "amount", type: "number" },
    header: (ctx) =>
      ctx.sortable ? (
        <button type="button" onClick={ctx.activateSort}>
          {ctx.label}{" "}
          {ctx.sortDirection === "Asc"
            ? "▲"
            : ctx.sortDirection === "Desc"
            ? "▼"
            : null}
        </button>
      ) : (
        ctx.label
      ),
  });
  ```

  `header` is a typed render function. Non-sortable columns receive `{ label, sortable: false }`; sortable columns also receive `sortDirection` and `activateSort()`. Custom headers own their click surface and sort indicator, while the default header keeps the built-in sort button and hit area.

* 7832718: Add standalone `Checkbox` component

  * New `Checkbox` — a styled boolean control wrapping Base UI's checkbox. Supports controlled (`checked`) and uncontrolled (`defaultChecked`) use, an `indeterminate` state, and an optional inline `label`. Integrates with `Field` and React Hook Form for label association, `disabled`, and invalid/error state exactly like `Input`/`Select` (no bespoke `error` prop) — drive it via `Controller` with `onCheckedChange`/`inputRef`. The invalid state is styled off both `data-invalid` (AppShell `Field.Root`) and `aria-invalid` (shadcn-style `FormControl`), so it fits either form stack.
  * DataTable now uses `Checkbox` internally for row selection, the header select-all (indeterminate), the enum and case-sensitive filter controls, and the column-settings visibility toggles — replacing the previously hand-rolled, slightly inconsistent checkbox styling with one shared control.

### Patch Changes

* 7a9e958: Fix DataTable row-selection highlight. Selecting a row now tints the **whole** row, not just the pinned selection/actions cells. The row sets `data-state="selected"` (which `Table.Row` keys its selected background off of) in addition to the existing `aria-selected`; previously only the pinned cells — which carry their own `group-aria-selected:bg-muted` — were highlighted.

## 1.9.0

### Minor Changes

* 423ae75: Add an `xs` (16px) size to `Avatar`

  `Avatar.Root` now accepts `size="xs"` for a 16px circle, extending the existing `sm` / `default` / `lg` scale:

  | `size`    | circle |
  | --------- | ------ |
  | `xs`      | 16px   |
  | `sm`      | 24px   |
  | `default` | 28px   |
  | `lg`      | 40px   |

  `xs` is intended for compact/inline contexts and single-glyph or icon content; two-letter initials will be cramped at this size. Purely additive — the default size is unchanged.

* 6f767f5: Add QuickBooks-style keyboard shortcuts to `DateField` / `DatePicker`

  When any date segment is focused, the field now supports whole-date navigation (all case-insensitive):

  * `t` — today
  * `m` / `h` — first / last day of the entered month (or the current month when no date is entered)
  * `y` / `r` — first / last day of the entered year
  * `w` / `k` — first / last day of the week (locale-aware week start)
  * `-` — previous day; `=` / `+` — next day. Both step across month **and** year boundaries (e.g. 1 Jan − 1 day → 31 Dec of the prior year). `+` works whether or not Shift is held.
  * `/` — commit the current segment as-is and advance to the next (e.g. typing `1` then `/` means "January", not the start of `1x`)
  * `Alt+↓` — open the calendar popover (`DatePicker` only)

  A 1–2 digit year is also expanded to the 2000s on blur (`26` → `2026`).

  Both `DateField` and `DatePicker` now accept an optional `firstDayOfWeek` prop to override the locale's week start for the `w`/`k` shortcuts (previously `DatePicker`-only).

  The shortcuts also work **while the calendar popover is open** — there they move the highlighted day (like the arrow keys), and `Enter` confirms. Targets are clamped to `minValue`/`maxValue` in both the field and the calendar, so a shortcut can't jump to an out-of-range date; unavailable days can be highlighted but not confirmed.

* 0817cf1: AppShell now bundles and injects a small default favicon set instead of a single 32×32 icon. When no `favicon` prop is passed (and the host page declares no `<link rel="icon">`), AppShell renders 16×16 and 32×32 PNG tab icons plus a 180×180 Apple touch icon — all embedded as data URIs, so no asset-copy step is needed. The Apple touch icon covers "Add to Home Screen" on both iOS and Android; the legacy `.ico` and PWA `android-chrome-*` icons are intentionally omitted to keep the bundle small (this is not a PWA).

  Behavior for consumers is unchanged: passing `favicon` still replaces the whole set with your single href, and an existing host-page favicon is still respected.

* 2497a2d: Add `useOpenCommandPalette()` for opening the built-in command palette from application code.

  ```tsx
  const openCommandPalette = useOpenCommandPalette();

  openCommandPalette();
  openCommandPalette({ search: "PO: alice" });
  ```

* 57a3870: Add composable `Timeline` primitives for building time-based layouts, including axis guides/levels, row backgrounds, intervals, and dependency links.

  * `Timeline.Root` defines the shared start/end range.
  * `Timeline.Viewport` renders the axis, decorations, scrolling area, and link layer.
  * `Timeline.Row` defines one timeline lane and owns row height/background.
  * `Timeline.Interval` positions content across a time range.
  * `Timeline.Link` draws dependency lines between timeline items.

  ```tsx
  import { Timeline } from "@tailor-platform/app-shell";

  <Timeline.Root start={0} end={100}>
    <Timeline.Viewport
      axis={{
        guides: [{ at: 0 }, { at: 50 }, { at: 100 }],
        levels: [
          {
            kind: "spans",
            items: [
              { start: 0, end: 50, label: "Phase 1" },
              { start: 50, end: 100, label: "Phase 2" },
            ],
          },
        ],
      }}
    >
      <Timeline.Row height={40}>
        <Timeline.Interval start={10} end={35}>
          <div className="h-full rounded-md bg-primary" />
        </Timeline.Interval>
      </Timeline.Row>
    </Timeline.Viewport>
  </Timeline.Root>;
  ```

  `Tooltip.Content` also now accepts `noArrow` for popover-like timeline labels and custom overlays.

### Patch Changes

* ca1c8c7: Raise the `@tailor-platform/auth-public-client` dependency floor from `^0.5.0` to `^0.5.1` so fresh installs cannot resolve the broken `0.5.0` release.
* 6e61cc2: Fix `DateField` / `DatePicker` not validating typed input against `minValue`, `maxValue`, or `isDateUnavailable`. A date entered by typing (or via a keyboard shortcut) that fell outside the allowed range was silently accepted. It's now flagged invalid (`aria-invalid` + a built-in message) while the value still flows through `onChange` — matching how the calendar already behaves and the react-aria validation contract.

  * Keyboard shortcuts (`t`, `m`, `y`, …) no longer clamp their target to the boundary; like typing, an out-of-range result is surfaced as invalid instead of being silently coerced.
  * `isDateUnavailable` now also drives field validation (e.g. weekends or specific blackout dates typed into the field are flagged), not just calendar selection.
  * Consumer `errorMessage` still takes precedence over the built-in messages.

## 1.8.0

### Minor Changes

* a4f735c: Add DateField, DatePicker, and Calendar components (@internationalized/date + Base UI implementation)

  Introduces three accessible date-input components, implemented on `@internationalized/date` (value layer) and Base UI (`Popover`) with hand-rolled segmented-input and calendar-grid behaviour:

  * `DateField` — segmented date/time input with label, description, and error message
  * `DatePicker` — date field with a popover calendar
  * `Calendar` — standalone calendar grid

  All three accept `LocalizedString` labels/descriptions and resolve locale + timezone from the AppShell context. The `@internationalized/date` value types (`CalendarDate`, `CalendarDateTime`, `ZonedDateTime`, …) and helpers (`parseDate`, `getLocalTimeZone`, …) are re-exported from `@tailor-platform/app-shell`.

  New AppShell context hooks:

  * `useResolvedLocale()` — full BCP-47 locale (e.g. `"en-GB"`) plus the language code
  * `useTimeZone()` — returns a `TimeZone` object with `.value` (IANA string), `.today()`, and `.now()` bound to the configured timezone

  AppShell now accepts an optional `timeZone` prop.

  > This is the **`@internationalized/date` + Base UI** variant — the lighter foundation tracked in the design proposal (§9). Net-new dependency is just `@internationalized/date` (~11 KB gz); Base UI is already in the bundle. Public API and accessibility contract are identical to the react-aria variant.
  >
  > **Known limitation:** the segmented input is built from `role="spinbutton"` elements that aren't `contentEditable`, so on-screen-keyboard typing on touch devices is limited — the calendar popover is the touch-friendly path (desktop keyboard entry works fully). The APG behaviour is unit-tested but not yet screen-reader-audited.

* ef5c788: DataTable now scrolls internally: add `fill` prop to `Layout` to pin page chrome and scroll only the table rows.

  ```tsx
  <Layout fill>
    <Layout.Header title="Products" />
    <Layout.Column>
      <DataTable.Root value={table}>
        <DataTable.Toolbar>…</DataTable.Toolbar>
        <DataTable.Table />
        <DataTable.Footer>
          <DataTable.Pagination />
        </DataTable.Footer>
      </DataTable.Root>
    </Layout.Column>
  </Layout>
  ```

  With `fill`, the page title, table toolbar, column header row (sticky), and footer stay visible at all heights — only the rows region scrolls vertically. Without `fill`, pages grow and scroll as before. Tables short enough to fit render without a scrollbar or layout shift.

  **Behavior change:** the AppShell layout is now viewport-bounded (`h-svh` instead of `min-h-svh`), so page content scrolls inside the content area rather than on the document. Code relying on `window`/document scroll position should target the content area instead.

  Also fixes the empty/error state reserving `pageSize`-worth of height — it is now capped at 5 rows, so large page sizes no longer produce a huge blank region below "No data".

* ef5c788: Add `useAppShellScrollContainer()` — a supported handle to the content scroll container

  Now that the shell is viewport-bounded (`h-svh`) and page content scrolls inside the content area rather than on the document, consumers that previously relied on `window`/document scroll need a stable way to reach the element that actually scrolls.

  `useAppShellScrollContainer()` returns a ref to that element:

  ```tsx
  const scrollRef = useAppShellScrollContainer();
  useEffect(() => {
    const el = scrollRef.current;
    if (!el) return;
    const onScroll = () =>
      setProgress(el.scrollTop / (el.scrollHeight - el.clientHeight));
    el.addEventListener("scroll", onScroll, { passive: true });
    return () => el.removeEventListener("scroll", onScroll);
  }, [scrollRef]);
  ```

  Use it wherever you would previously have reached for `window.scrollY`, a `window` `scroll` listener, `window.scrollTo(...)`, or an `IntersectionObserver` with the default viewport root.

  * On a `<Layout fill>` page the element does not scroll (its children manage their own scrolling).
  * Outside a `SidebarLayout` the ref's `current` is always `null`.
  * The container also carries a `data-appshell-scroll-container` attribute for non-React access (CSS, tests, `document.querySelector`).

* aa9306a: Add a `header` slot to `SidebarLayout` and a `SidebarLayout.DefaultHeader` building block

  `SidebarLayout` now accepts a full-region `header?: ReactNode` prop, mirroring the existing `sidebar` slot. It defaults to the built-in header (`SidebarLayout.DefaultHeader`), so existing usage is unchanged.

  To extend the built-in header (e.g. add a notification bell or user menu) without reconstructing the trigger and breadcrumb, use `SidebarLayout.DefaultHeader` with its `actions` slot:

  ```tsx
  <SidebarLayout
    header={
      <SidebarLayout.DefaultHeader
        actions={[
          <NotificationBell key="bell" />,
          <AppearanceSwitcher key="appearance" />,
        ]}
      />
    }
  />
  ```

  * `DefaultHeader`'s `actions` prop (single node or array) controls the entire right-hand cluster, laid out in a horizontal, vertically-centered row.
  * `actions` **defaults to `[<AppearanceSwitcher />]`**, and **passing `actions` replaces the whole cluster including the switcher** — include `<AppearanceSwitcher />` explicitly to keep it. This keeps the API a single slot instead of accumulating one-off props.
  * `DefaultHeader` is available as `SidebarLayout.DefaultHeader` and as a top-level `DefaultHeader` export.
  * `DefaultSidebar` is now also exposed as `SidebarLayout.DefaultSidebar` for symmetry; the top-level `DefaultSidebar` export is retained for backwards compatibility.

  This provides an official, composable extension point for the top bar, replacing fragile consumer workarounds that queried the header DOM and injected a React portal.

* 078130e: Add a `size` prop to `Tabs` and make `capsule` icon-only tabs square

  `Tabs.Root` now accepts `size?: "xs" | "sm" | "default" | "lg"` (default `"default"`), mirroring `Button`'s height tiers. It sets a **minimum** height on the `capsule` variant — taller content still grows — so a capsule track sits flush next to a `Button`:

  | `size`    | capsule track | matches Button |
  | --------- | ------------- | -------------- |
  | `xs`      | 28px          | `size="xs"`    |
  | `sm`      | 32px          | `size="sm"`    |
  | `default` | 36px          | default        |
  | `lg`      | 40px          | `size="lg"`    |

  Two `capsule` fixes from the same change:

  * The list no longer hard-locks to `h-10` (40px); its height derives from the tab size floor.
  * A tab whose only child is an icon now renders **square** (`min-width` follows `min-height`), instead of the previous wider-than-tall, shrunken look — ideal for icon-only view toggles.

  The default `capsule` height moves from 40px to 36px to align with `Button`'s default height. `size` only affects the `capsule` variant; `line` and `default` are unchanged.

### Patch Changes

* eeb10ab: Remove the `stream` option from `useAIChat()` and `AIGatewayChatRequest`.

  AppShell now selects the appropriate transport (streaming vs JSON) automatically based on the model. Passing `stream` is no longer needed.

## 1.7.0

### Minor Changes

* 7f33506: Allow the standalone `Select`, `Combobox`, and `Autocomplete` (including their `.Async` variants) to receive an accessible name via `aria-label`, `aria-labelledby`, and `id`. Previously these props were silently dropped, leaving the combobox with only its current value as an accessible name — a WCAG 4.1.2 issue for filters and toolbars used outside a `Form`. The props are now forwarded to the underlying trigger/input.

  ```tsx
  // Announced as "Direction filter, combobox" instead of just its value
  <Select
    items={items}
    value={value}
    onValueChange={setValue}
    aria-label="Direction filter"
  />

  // Or point at a visible label
  <span id="dir-label">From</span>
  <Combobox items={items} aria-labelledby="dir-label" />
  ```

### Patch Changes

* ff30974: Fix `@tailor-platform/app-shell/styles` so consumer Tailwind utilities like `bg-card`, `border-border`, and `text-muted-foreground` resolve again without requiring `theme.css`.

  `theme.css` remains a no-op compatibility shim, while `styles` now restores the Tailwind theme bridge and keeps the precompiled AppShell component CSS importable from a single entrypoint.

## 1.6.1

### Patch Changes

* 147aacf: Fix Vitest and other Node-evaluated test setups that import `@tailor-platform/app-shell` by keeping the package's JS entry free of CSS imports.

  `@tailor-platform/app-shell/styles` continues to ship the default AppShell styles and bundled Inter font assets. Applications should import that stylesheet explicitly, as shown in the docs and examples.

## 1.6.0

### Minor Changes

* 820b75b: Add `DocumentProgressCard` — a generic, presentational card for a document's lifecycle/fulfilment state: an optional headline percentage, a stacked progress bar, and a status legend driven by arbitrary `segments`. It's domain-agnostic, so it stretches to any status breakdown (shipped / cancelled / pending, PO received / returned / yet-to-receive, etc.).

  ```tsx
  import { DocumentProgressCard } from "@tailor-platform/app-shell";

  <DocumentProgressCard
    title="Shipment status"
    percent={60}
    segments={[
      { label: "Shipped", value: 30, color: "green" },
      { label: "Returned", value: 3, color: "red" },
      { label: "Pending", value: 17, color: "neutral" },
    ]}
  />;
  ```

  Each segment is `{ label, value, color }`. Pass an explicit `percent`, an optional `total` (leave a value larger than the segment sum to render an unfilled track remainder), and an optional `legend` override for when the legend should differ from the bar (e.g. overlapping buckets). Percentage and any domain-specific breakdown are derived in the consumer — see the docs for a purchase-order fulfilment recipe.

* d1cac39: Add `Grid` — a generic, presentational CSS-Grid layout primitive for arranging arbitrary children into equal or custom-width columns, with responsive reflow, gap control, auto-fit, and optional `Grid.Item` spanning. Complements `Layout` (page scaffold) by handling content-level grids.

  ```tsx
  import { Grid } from "@tailor-platform/app-shell";

  // Responsive KPI grid: 1 → 2 → 4 columns
  <Grid columns={{ initial: 1, sm: 2, lg: 4 }} gap={4}>
    <Card.Root>…</Card.Root>
  </Grid>

  // Auto-fitting gallery — no breakpoints needed
  <Grid minChildWidth={240} gap={6}>{items}</Grid>

  // Custom column widths + spanning
  <Grid columns="280px 1fr" gap={6}>
    <Grid.Item colSpan={2}>Wide</Grid.Item>
  </Grid>
  ```

  Props: `columns`, `rows`, `gap`/`gapX`/`gapY` (defaults to `3` / 12px), `minChildWidth`, `flow`, `align`, `justify`. `Grid.Item` supports `colSpan`, `rowSpan`, `colStart`, `colEnd` — all responsive.

* 2beb757: Add `align?: "left" | "center" | "right"` to `Table.Head` and `Table.Cell` so raw table primitives can align numeric and status columns without relying on consumer Tailwind utility overrides.

  ```tsx
  <Table.Head align="right">Amount</Table.Head>
  <Table.Cell align="right">123</Table.Cell>

  <Table.Head align="center">Status</Table.Head>
  <Table.Cell align="center">Active</Table.Cell>
  ```

* 116d2cc: Add a low-level AI Gateway client and a simple text-only chat hook for AppShell.

  ```tsx
  import { createAIGatewayClient, useAIChat } from "@tailor-platform/app-shell";

  const aiClient = createAIGatewayClient({ gatewayUri, authClient });
  const { messages, sendMessage, stop } = useAIChat({
    client: aiClient,
    model: "gpt-5-mini",
  });
  ```

* ae2396b: Add `useURLCollectionVariables` for wiring collection state (filters, sort, page size) to the URL query string in a single call. It seeds initial state from the current router search params and writes changes back as the user filters, sorts, or pages.

  ```tsx
  const { variables, control } = useURLCollectionVariables({
    tableMetadata,
    params: { pageSize: 20 },
  });
  ```

  For cases that need URL persistence without react-router's `useSearchParams` (e.g. a custom binding), the pure `withURLCollectionState(options, [searchParams, setSearchParams])` decorator is also exported and can be composed with `useCollectionVariables` directly.

  `useCollectionVariables` now reports state updates through `onParamsChange` using the same `params` shape it accepts.

### Patch Changes

* 40e0f1c: Restore the `@tailor-platform/app-shell/theme.css` export as a no-op compatibility shim.

  Apps that still import `@tailor-platform/app-shell/theme.css` alongside `@tailor-platform/app-shell/styles` now keep building while the real theme tokens continue to come from `styles`.

## 1.5.0

### Minor Changes

* 00f9aa7: Manage the browser tab from AppShell — title and favicon.

  * **Title**: AppShell now keeps `document.title` in sync with the active route as `"<page> · <title>"`, where `<page>` is the current breadcrumb leaf (including any `useOverrideBreadcrumb` override, so detail pages show their record name automatically) and `<title>` is the `title` prop passed to `<AppShell>`. Works for every page with no per-page wiring; when no `title` is set the tab shows just the page name.
  * **Favicon**: new `favicon` prop on `<AppShell>` sets the document favicon (any `<link rel="icon">` href — a public-path URL or a data URI). When omitted it defaults to the bundled Tailor favicon, so apps get correct branding out of the box.

  Both are rendered declaratively (React 19 hoists `<title>`/`<link rel="icon">` into `<head>`), so it works in client-only apps, streaming SSR, and Server Components.

  If your app already updates `document.title` manually, you can drop that wiring and let AppShell own the tab title. A host-page `<link rel="icon">` can remain in place unless you explicitly pass the new `favicon` prop.

* 5353303: Introduce theming support — **ColorTheme** axis, static **theme palettes** via CSS imports, a new `AppearanceSwitcher` component, and bundled Inter variable fonts.

  #### ColorTheme (end-user preference, persisted)

  `ColorTheme` (`"light" | "dark" | "system"`) is the end-user color mode preference. Applied to `<html>` as `.light` / `.dark` class.

  * `<AppShell defaultColorTheme="system">` sets the initial preference; user choice is persisted to localStorage.
  * `useTheme()` hook returns `{ theme, resolvedTheme, setTheme }`.

  #### Theme Palettes (static CSS imports)

  Each palette (`default`, `cream`, `bloom`) ships both light and dark variants.
  Select a palette by importing its CSS file — no prop needed:

  ```ts
  import "@tailor-platform/app-shell/themes/cream";
  ```

  The default palette is included automatically via `@tailor-platform/app-shell/styles`.

  #### AppearanceSwitcher

  * New `<AppearanceSwitcher />` component for toggling color theme (light / dark / system).

### Patch Changes

* 3d48b24: Remove `loader` from file-based page definitions (`Page.appShellPageProps`). This removes an accidentally exposed incomplete API and makes `guards` the single source of page-level route behavior in file-based routing.
* 3138c6a: Fix DataTable checkbox vertical alignment. Remove unnecessary wrapper div and `translate-y-[2px]` hack so checkboxes align correctly with row content via `align-middle`.
* 5353303: Set explicit `--accent` values per palette and mode, reorganise palette CSS into numbered tiers with a `_template.css` authoring guide, add `--alert-*` semantic tokens to the default palette, and wire `Alert` variants to those tokens (including lighter dark-mode foregrounds).
* Updated dependencies \[3d48b24]
  * @tailor-platform/app-shell-vite-plugin@0.2.3

## 1.4.1

### Patch Changes

* f176477: Fix cursor consistency across `Button` and `Badge`:

  * **`Button`**: restore the pointer cursor. Tailwind v4 dropped the Preflight
    rule that gave `button`/`[role="button"]` a `cursor: pointer`, so the base
    `Button` showed the default arrow cursor while components that hardcode
    `astw:cursor-pointer` (e.g. `ActionPanel`) did not. Added `astw:cursor-pointer`
    to the `buttonVariants` base classes so all `Button` instances are consistent.
    Disabled buttons keep the default cursor via the existing
    `astw:disabled:pointer-events-none`.
  * **`Badge`**: pin `astw:cursor-default`. A `Badge` is non-interactive but
    renders a `<div>` with no cursor of its own, so it inherited `cursor: pointer`
    from clickable ancestors (e.g. a `DataTable` row with `onClickRow`). Explicitly
    setting the default cursor stops a badge from signalling clickability.

## 1.4.0

### Minor Changes

* 5a251fd: Add `Alert` compound component with `neutral`, `success`, `warning`, `error`, and `info` variants. Each variant renders a contextual icon automatically.

  ```tsx
  import { Alert } from "@tailor-platform/app-shell";

  <Alert.Root variant="success">
    <Alert.Title>Saved</Alert.Title>
    <Alert.Description>Your changes have been saved.</Alert.Description>
  </Alert.Root>;
  ```

* 49f10e3: Improve Sheet component customizability:

  * Add `size` prop to `Sheet.Content` for width variations (`sm`, `md`, `lg`, `xl`, `full`)
  * Add `action` prop to `Sheet.Header` for placing action buttons to the right of the title
  * Increase `Sheet.Title` font size to `text-lg` for better visibility
  * Move close button to the left side of the header, with title inline next to it
  * Header now has a bottom border, Footer has a top border for visual separation

  ```tsx
  <Sheet.Root side="right">
    <Sheet.Trigger render={<Button />}>Open</Sheet.Trigger>
    <Sheet.Content size="lg">
      <Sheet.Header action={<Button size="sm">Save</Button>}>
        <Sheet.Title>Edit Record</Sheet.Title>
      </Sheet.Header>
    </Sheet.Content>
  </Sheet.Root>
  ```

### Patch Changes

* 58b76ce: Add `info` and `subtle-info` badge variants for informational or in-progress status labels (blue palette, matching the existing `outline-info` dot color). Also extend the primitives demo to show all five outline variants (previously only `outline-success` was rendered).

  ```tsx
  <Badge variant="info">New</Badge>
  <Badge variant="subtle-info">In Progress</Badge>
  ```

* 98270c5: Add optional `variant` prop to `ActionItem` for the `ActionPanel` component. Use `variant: "destructive"` to style dangerous actions (e.g., delete) with red text and hover background.

## 1.3.0

### Minor Changes

* 902fad2: Add `Tabs` compound component for tab-based navigation, backed by Base UI's Tabs primitive.

  ```tsx
  import { Tabs } from "@tailor-platform/app-shell";

  <Tabs.Root defaultValue="overview">
    <Tabs.List>
      <Tabs.Tab value="overview">Overview</Tabs.Tab>
      <Tabs.Tab value="projects">Projects</Tabs.Tab>
    </Tabs.List>
    <Tabs.Panel value="overview">Overview content</Tabs.Panel>
    <Tabs.Panel value="projects">Projects content</Tabs.Panel>
  </Tabs.Root>;
  ```

* 2197c3f: Add array badge support to DataTable and DescriptionCard with shared `BadgeList` rendering and overflow popover.

  ```tsx
  // DataTable — badge column with array accessor
  column({
    ...infer("tags"),
    type: "badge",
    typeOptions: {
      badgeVariantMap: { Premium: "warning", Office: "outline-info" },
      maxVisible: 2,
    },
  })

  // DescriptionCard — array badges with maxVisible
  <DescriptionCard
    data={{ tags: ["urgent", "fragile", "international"] }}
    fields={[{
      key: "tags",
      label: "Tags",
      type: "badge",
      meta: {
        badgeVariantMap: { urgent: "error", fragile: "warning", international: "outline-info" },
        maxVisible: 2,
      },
    }]}
  />
  ```

  Additional changes:

  * Unify badge variant resolution into shared `resolveBadgeVariant()` utility with `"outline-neutral"` as the default variant (previously `"neutral"` in DataTable)
  * Export `BadgeVariant` and `BadgeOptions` types from the public API
  * `inferColumns()` no longer sets a default `render` function — columns without an explicit `type` or `render` now display `—` for null/empty values (aligns with typed-column behavior)
  * Deprecate `BadgeVariantType` in favor of `BadgeVariant`

### Patch Changes

* 4998df4: Fix and improve `DescriptionCard` component:

  * Fix relative date formatting producing incorrect output for future dates (negative time diff)
  * Add i18n label support for relative date strings
  * Use react-router `<Link>` for internal navigation in link and reference fields instead of plain `<a>` tags

* b70e3d5: Updated @base-ui/react (1.4.1 -> 1.5.0)

* 99f6b6d: Updated graphql (^16.13.2 -> ^16.14.0)

## 1.2.0

### Minor Changes

* 8a09b26: Add `align: "left" | "right"` to `DataTable` `Column`. When set to `"right"`, the header label, body cell, and loading-skeleton bar are right-aligned together — eliminating the inline `<span className="text-right">` wrappers callers were adding inside `render` for numeric columns (Amount, Score, Total).

  `align` is **auto-defaulted to `"right"` for `type: "number"` and `type: "money"`** so the common case Just Works without extra config. Other types default to `"left"`. Pass `"left"` explicitly to opt a numeric column out.

  ```tsx
  // Auto-aligned right — no `align` needed
  column({
    label: "Total",
    type: "money",
    accessor: (row) => row.total,
    typeOptions: { currency: "USD" },
  });

  // Explicit alignment for a custom-render column
  column({
    label: "Amount",
    align: "right",
    render: (row) => formatMoney(row.amount),
  });
  ```

* b644bdb: Add `truncate: boolean` to `DataTable` `Column`. When set, the cell content is truncated with an ellipsis on overflow, and an app-shell `<Tooltip>` is auto-wired to reveal the full value on hover when the cell value is a stringifiable primitive. The tooltip resolves through the same precedence rule the built-in `type` renderers use — `accessor` first, then `row[col.id]` — so `inferColumns` consumers get the tooltip for free without an explicit accessor. Pair `truncate` with `width` on neighboring columns to anchor row width, since truncate cells use `max-w-0` to stay shrinkable.

  ```tsx
  column({
    label: "Description",
    render: (row) => row.description,
    accessor: (row) => row.description,
    truncate: true,
  });

  // Or with `inferColumns`, no explicit `accessor` needed — the inferred
  // column pins `id` to the field name so the tooltip resolves automatically:
  column({ ...infer("description"), truncate: true });
  ```

  `inferColumns` now also pins `id` to the metadata field name (previously omitted). This makes the cell renderer's `row[col.id]` fallback resolve cleanly and stabilizes the React key / column-visibility identifier across re-renders.

* 4c89923: Add `defaultOpen` and `collapsible` props to `SidebarLayout` for controlling sidebar behavior.

  ```tsx
  // Sidebar closed by default on desktop
  <SidebarLayout defaultOpen={false} />

  // Non-collapsible sidebar (always visible, toggle buttons hidden)
  <SidebarLayout collapsible={false} />
  ```

* c4fbfa2: Add `type` and `typeOptions` to `DataTable` `Column` for built-in cell rendering. Set `type` to `text`, `number`, `money`, `date`, `badge`, or `link` to skip writing a `render` function for the common cases. `render` stays required for untyped columns and becomes an optional override when `type` is set.

  `Column<TRow>` is a discriminated union on `type`, so wrong-shape options are a compile error rather than silently ignored at runtime — and `type: "link"` requires `typeOptions.href`.

  ```tsx
  column({
    label: "Total",
    accessor: (row) => row.total,
    type: "money",
    typeOptions: { currency: "USD" },
  });

  column({
    label: "Status",
    accessor: (row) => row.status,
    type: "badge",
    typeOptions: {
      badgeVariantMap: { active: "success", draft: "neutral" },
      badgeLabelMap: { active: "Active", draft: "Draft" },
    },
  });
  ```

### Patch Changes

* c4fbfa2: Narrow `Column.accessor`'s return type per built-in `type` so the typed cell renderers reject values they can't display. Returning an array or a plain object from a `text` / `number` / `money` / `date` / `badge` / `link` accessor is now a compile error instead of silently rendering `[object Object]` or a stringified list. `null` and `undefined` are still allowed and continue to render the `—` placeholder. Columns without a `type` retain the loose `unknown` return type — they pair with `render` to draw whatever shape they like.

  ```tsx
  column({
    label: "Tags",
    type: "text",
    // ^ compile error: text accessor cannot return an array.
    accessor: (row) => row.tags,
  });
  ```

* eecff8e: Add `subtle-success`, `subtle-warning`, and `subtle-error` badge variants for low-emphasis status labels.

  ```tsx
  <Badge variant="subtle-success">Matched</Badge>
  <Badge variant="subtle-warning">Needs Attention</Badge>
  <Badge variant="subtle-error">Needs Review</Badge>
  ```

## 1.1.1

### Patch Changes

* d4d15f5: Add `DescriptionCard` badge field support for `meta.sentenceCaseBadges = false` so apps can opt out of the default sentence-case badge labels.

## 1.1.0

### Minor Changes

* 9654369: Fix root page (`/`) showing `"/"` as its title in `SidebarItem` and breadcrumb.

  The root page is now treated as a first-class page (module) so that title, icon, and guards are resolved consistently. `DefaultSidebar` and `CommandPalette` now include the root page when it is defined. When no title is set, the fallback is localized `"Home"` / `"ホーム"`.

* 39a8521: Change `useDataTable()` to use single-column sorting by default and add a `sort` option for configuring sorting behavior.

  Before:

  ```tsx
  const table = useDataTable({
    columns,
    data,
    control,
  });
  ```

  After:

  ```tsx
  const table = useDataTable({
    columns,
    data,
    control,
    sort: { multiple: true },
  });
  ```

  Use `sort: false` to disable sorting entirely.

* c2a50b9: Add row count and selection info to `DataTable.Pagination`.

  * When `total` is provided: shows `"X row(s)"`
  * When rows are selected with `total`: shows `"Y of X row(s) selected"`
  * When rows are selected without `total`: shows `"Y row(s) selected"`

* 642aa1e: Add case-sensitivity control for string filters in `DataTable.Filters`. String filters are now case-insensitive by default (using Tailor Platform's `regex` operator with `(?i)` prefix). A "Case sensitive" checkbox allows users to opt into exact-case matching.

  The `Filter` type and `CollectionControl.addFilter` now accept an optional `caseSensitive` property to control this behavior programmatically.

* a3d0170: Add "between" filter mode to `DataTable.Filters` for numeric and date/time columns, allowing users to filter by a range with min and max bounds.

### Patch Changes

* 2a860d9: Fix DataTable filter types for `datetime` and `time` fields. Previously these were incorrectly mapped to the `date` filter type, causing wrong input formats. Each temporal type now uses its proper HTML input type (`datetime-local`, `date`, `time`) and format handling.

* 125aee2: Fix a `Select.Async` bug where reopening the dropdown after the first async load could leave the popup invisible while the page stayed scroll-locked.

  This could happen after options were fetched once, the dropdown was closed, and then opened again. The fix cancels in-flight requests on close and avoids the Base UI modal and anchored alignment paths that were leaving the async popup in that broken reopen state.

* 681333f: Remove `next-themes` dependency by using the internal `ThemeProvider` context for the Sonner toast theming.

* 826bd97: Updated @base-ui/react (^1.3.0 -> ^1.4.1)

## 1.0.2

### Patch Changes

* 27bb5df: Remove `richColors` prop from the `Toaster` component. Toast notifications will no longer use color-coded styling for success, error, warning, and info variants.
* Updated dependencies \[ee7f7c7]
  * @tailor-platform/app-shell-vite-plugin@0.2.2

## 1.0.1

### Patch Changes

* 598bc90: Fix cursor-based pagination in `DataTable`.

  * Fix "Previous" button not working correctly when the GraphQL server returns unreliable `hasPreviousPage` (common with `first + after` queries per the Relay spec)
  * Fix navigating back after jumping to the last page incorrectly returning to page 1
  * Fix "Next" button remaining enabled past the last page when `total` is known

* 4aaf5ab: Fix "Go to Last Page" pagination alignment. When total items aren't evenly divisible by page size, `goToLastPage` now requests `last: total % pageSize` instead of `last: pageSize`, so the last page boundaries match forward pagination.

## 1.0.0

### Major Changes

* 3f31e8a: Add `DataTable` compound component. Also introduces `@tailor-platform/app-shell-sdk-plugin` — a companion SDK plugin that generates `tableMetadata` from TailorDB type definitions for use with `createColumnHelper`.

  ## DataTable

  * Sortable columns (click header to cycle Asc → Desc → off)
  * Filter chips with per-type editors (string, number, date, enum, boolean, uuid)
  * Cursor-based pagination with optional total-aware First/Last navigation
  * Per-row action menu (kebab menu)
  * Multi-row checkbox selection (current page only)
  * Loading, error, and empty states
  * Metadata-driven column inference via `createColumnHelper` and `inferColumns`

  ### Example with urql (Relay Cursor Connection GraphQL API)

  ```tsx
  import { gql, useQuery } from "urql";
  import {
    DataTable,
    useDataTable,
    useCollectionVariables,
    createColumnHelper,
  } from "@tailor-platform/app-shell";

  const LIST_JOURNALS = gql`
    query ListJournals(
      $after: String
      $before: String
      $first: Int
      $last: Int
      $order: [JournalOrderInput]
      $query: JournalQueryInput
    ) {
      journals(
        after: $after
        before: $before
        first: $first
        last: $last
        order: $order
        query: $query
      ) {
        edges {
          node {
            id
            contents
            authorID
          }
        }
        pageInfo {
          endCursor
          hasNextPage
          hasPreviousPage
          startCursor
        }
        total
      }
    }
  `;

  const { column } = createColumnHelper<{
    id: string;
    contents: string;
    authorID: string;
  }>();

  const columns = [
    column({ field: "id", label: "ID", type: "uuid" }),
    column({ field: "authorID", label: "Author", type: "string" }),
    column({ field: "contents", label: "Contents", type: "string" }),
  ];

  function JournalsPage() {
    // variables: { query, order, pagination } — maps directly to GraphQL variables.
    // control: holds filter/sort/pagination state and methods (addFilter, setSort, nextPage, …).
    //          Passing it to useDataTable wires UI interactions (column clicks, filter chips,
    //          pagination buttons) to state updates, which re-derive variables and re-run the query.
    const { variables, control } = useCollectionVariables({
      params: { pageSize: 20 },
    });

    // pagination holds { first, after? } (forward) or { last, before? } (backward).
    const [result] = useQuery({
      query: LIST_JOURNALS,
      variables: {
        first: variables.pagination.first,
        after: variables.pagination.after,
        last: variables.pagination.last,
        before: variables.pagination.before,
        query: variables.query,
        order: variables.order,
      },
    });

    const table = useDataTable({
      columns,
      data: result.data
        ? {
            rows: result.data.journals.edges.map((e) => e.node),
            pageInfo: result.data.journals.pageInfo,
            total: result.data.journals.total,
          }
        : undefined,
      loading: result.fetching,
      control,
    });

    // DataTable.Root + DataTable.Table are the only required sub-components.
    // DataTable.Toolbar / DataTable.Filters / DataTable.Pagination are opt-in sensible defaults.
    // If they don't fit, use useDataTableContext() to build your own sub-components —
    // it exposes the full DataTable state (rows, columns, sort, pagination, selection, etc.)
    // from the nearest DataTable.Root.
    return (
      <DataTable.Root value={table}>
        <DataTable.Toolbar>
          <DataTable.Filters />
        </DataTable.Toolbar>
        <DataTable.Table />
        <DataTable.Footer>
          <DataTable.Pagination pageSizeOptions={[10, 20, 50]} />
        </DataTable.Footer>
      </DataTable.Root>
    );
  }
  ```

  `useCollectionVariables` is intentionally decoupled from DataTable and any other UI component. The hook owns only the query state and exposes plain `variables` — how those variables are rendered is entirely up to the consumer. This means future collection-based views such as Kanban boards can adopt the same hook without modification, and any custom component you build can use a GraphQL cursor-based API as its backend with minimal wiring.

  ## sdk-plugin (`@tailor-platform/app-shell-sdk-plugin`)

  `tableMetadata` is what bridges your TailorDB schema to the DataTable. It tells `inferColumns` how to render and filter each field — for example, which fields get a date picker, which get an enum dropdown (and with what options), and which are numeric. Without it, you would need to declare all of this manually per column.

  The metadata is generated at SDK code-gen time from your TailorDB type definitions. Register the plugin in `tailor.config.ts` and run `tailor-sdk generate`:

  ```ts
  import { definePlugins } from "@tailor-platform/sdk";
  import { appShellPlugin } from "@tailor-platform/app-shell-sdk-plugin";

  export const plugins = definePlugins(
    appShellPlugin({
      dataTable: {
        metadataOutputPath: "src/generated/app-shell-datatable.generated.ts",
      },
    })
  );
  ```

  The generated file exports `tableMetadata`, `tableNames`, and `TableName`. Pass `tableMetadata` to `inferColumns` to get type-safe column definitions with filter editors automatically configured:

  ```ts
  import { tableMetadata } from "@/generated/app-shell-datatable.generated";
  import { createColumnHelper } from "@tailor-platform/app-shell";

  const { column, inferColumns } = createColumnHelper<Order>();
  const infer = inferColumns(tableMetadata.order);

  const columns = [
    column(infer("title")), // string column → text filter
    column(infer("status")), // enum column  → dropdown filter with generated values
    column(infer("createdAt")), // datetime column → date picker filter
  ];
  ```

  ### Typed query variables with `tableMetadata`

  When using typed GraphQL documents (e.g. `TypedDocumentNode` from `@graphql-typed-document-node/core` or codegen-generated types), urql and other GraphQL clients enforce strict types on the `variables` object passed to `useQuery`. In that case, passing `tableMetadata` to `useCollectionVariables` is **required** — it is what narrows `variables.query` and `variables.order` from `unknown` to the precise types expected by the generated document.

  Without `tableMetadata`, `variables.query` is typed as `Record<string, Record<string, unknown>> | undefined`, which will not satisfy the stricter generated variable types and will cause a TypeScript error at the `useQuery` call site.

  Use `sdk-plugin` to generate `tableMetadata` and pass it to `useCollectionVariables`:

  ```ts
  const { variables, control } = useCollectionVariables({
    tableMetadata: tableMetadata.order, // required for typed documents
    params: { pageSize: 20 },
  });

  // variables.query is now BuildQueryVariables<typeof tableMetadata.order>
  // variables.order is now { field: OrderableFieldName; direction: "Asc" | "Desc" }[]
  // Both satisfy the types generated by GraphQL codegen.
  const [result] = useQuery({
    query: LIST_ORDERS, // TypedDocumentNode — variables are fully type-checked
    variables: {
      ...variables.pagination,
      query: variables.query,
      order: variables.order,
    },
  });
  ```

## 0.36.0

### Minor Changes

* e2a6f81: Add `Attachment` component and `useAttachment` hook for ERP attachment workflows with drag-and-drop upload, image/file previews, and per-item `Download`/`Delete` actions.

  Use `useAttachment` to manage upload/delete state locally and flush operations to your backend on submit via `applyChanges`. Spread the returned `props` directly onto `<Attachment />`.

  ```tsx
  import { Attachment, useAttachment } from "@tailor-platform/app-shell";
  import type { AttachmentOperation } from "@tailor-platform/app-shell";

  const { props, applyChanges } = useAttachment({
    initialItems: existingAttachments,
    accept: "image/*,.pdf",
  });

  async function handleSubmit() {
    // The component is agnostic to backend shape — run all operations in parallel.
    await applyChanges((operations) =>
      Promise.all(
        operations.map((op) => {
          if (op.type === "upload") return uploadToServer(op.file);
          if (op.type === "delete") return deleteFromServer(op.item.id);
        })
      )
    );
  }

  <Attachment {...props} uploadLabel="Upload" onDownload={handleDownload} />;
  ```

## 0.35.1

### Patch Changes

* 3b11ca4: Fix CommandPalette and DefaultSidebar not showing top-level pages that have no child pages.

  When using file-based routing with a flat page structure (e.g. `pages/dashboard/page.tsx` with no sub-pages), those pages were silently excluded from the CommandPalette and the DefaultSidebar auto-generation. They now appear correctly as navigable entries.

* 0d8d87e: Add top-padding in Card component"

* 8c0eed5: Adjust `Table` cell padding so the first column uses 24px left inset and the last column uses 24px right inset (middle columns unchanged). Update `Card.Header` titles to `text-lg` to align with `DescriptionCard`, `ActivityCard`, and `ActionPanel`.

* e841014: Enable richColors in toast

## 0.35.0

### Minor Changes

* d284d6a: Add `searchSources` prop to `AppShell` to wire async, prefix-based search into the CommandPalette. Each source declares a short `prefix` (e.g. `"ORD"`) and an async `search` function. When the user types that prefix followed by `:`, the palette switches into search mode: Actions and Pages sections are hidden and only results from that source are shown.

  The empty-input state of the palette now includes a **Search Modes** section that lists every registered source, so users can discover and activate a mode with a single click instead of remembering the prefix syntax.

  `DefaultSidebar` always renders a **Search** entry that opens the palette (Cmd+K also works globally), because routes and registered actions are always searchable regardless of whether any `searchSources` are configured.

  ```tsx
  import { AppShell, type SearchSource } from "@tailor-platform/app-shell";

  const searchSources: readonly SearchSource[] = [
    {
      prefix: "ORD",
      title: "Orders",
      search: async (query, { signal }) => {
        const results = await api.searchOrders(query, { signal });
        return results.map((o) => ({
          key: o.id,
          label: o.number,
          path: `/orders/${o.id}`,
        }));
      },
    },
  ];

  <AppShell searchSources={searchSources}>
    <SidebarLayout sidebar={<DefaultSidebar />} />
  </AppShell>;
  ```

### Patch Changes

* 5dc2d7f: Dependencies updated

  * Updated react (^19.2.4 -> ^19.2.5)
  * Updated react-dom (^19.2.4 -> ^19.2.5)

* 202f046: Updated react-router (^7.14.0 -> ^7.14.1)

* 307c4ef: Updated lucide-react (^1.7.0 -> ^1.8.0)

* b5e4352: Fixed a bug where placing a guard component between `AuthProvider` and `AppShell` could block `AppShell` from mounting, preventing the authentication flow from ever starting and leaving the app stuck in an unauthenticated state.

## 0.34.0

### Minor Changes

* 0dac517: Add contextual action registration for CommandPalette via `useRegisterCommandPaletteActions` hook. `ActionPanel` actions are now automatically registered to the CommandPalette, making them discoverable and triggerable via keyboard shortcut.

  ```tsx
  import { useRegisterCommandPaletteActions } from "@tailor-platform/app-shell";

  function MyPage() {
    useRegisterCommandPaletteActions("My Page", [
      { key: "save", label: "Save", onSelect: handleSave },
    ]);
  }
  ```

* c6afaca: Add `CsvImporter` component — a guided, multi-step CSV import flow with drag-and-drop upload, interactive column mapping, Standard Schema validation, inline cell editing, and async server-side validation support.

  Key features:

  * **Drag & drop upload** with file size limit enforcement
  * **Auto column matching** via aliases and fuzzy header detection
  * **Standard Schema validation** with built-in `csv.string()`, `csv.number()`, `csv.boolean()`, `csv.date()`, and `csv.enum()` validators that handle coercion and validation in one step
  * **Inline error correction** — users can fix validation errors directly in the review table before importing
  * **Async `onValidate`** callback for server-side checks (e.g. uniqueness constraints)
  * **Built-in i18n support** — English and Japanese labels included out of the box

  ```tsx
  import {
    CsvImporter,
    useCsvImporter,
    csv,
    type CsvCellIssue,
  } from "@tailor-platform/app-shell";

  const { open, props } = useCsvImporter({
    schema: {
      // Each column defines a mapping target for CSV headers
      columns: [
        {
          // Becomes the object key in parsed row data
          key: "name",
          // Display label shown in the mapping UI
          label: "Name",
          // Must be mapped to a CSV header before proceeding
          required: true,
          // Alternative CSV header names for auto-matching
          aliases: ["product_name"],
          // Standard Schema validator — coerces and validates in one step
          schema: csv.string({ min: 1 }),
        },
        {
          key: "price",
          label: "Price",
          schema: csv.number({ min: 0 }), // Coerces the raw CSV string to a number and rejects NaN
        },
        {
          key: "active",
          label: "Active",
          schema: csv.boolean(), // Recognises "true"/"1"/"yes" and "false"/"0"/"no" (case-insensitive)
        },
      ],
    },

    // Async callback invoked after schema validation passes.
    // Use it for server-side checks such as uniqueness or foreign-key lookups.
    onValidate: async (rows) => {
      // Async API request that returns CsvCellIssue[] — shown inline in the review table
      return await validateOnServer(rows);
    },

    // Called when the user confirms the import after resolving all errors.
    // `event` contains the final rows, mappings, corrections, and summary stats.
    onImport: async (event) => {
      // buildRows() returns typed rows inferred from the schema definition.
      // e.g. { name: string; price: number; active: boolean }[]
      const rows = await event.buildRows();
      await saveToBackend(rows);
    },
  });

  // open() opens the import drawer
  <Button onClick={open}>Import CSV</Button>

  // Renders a multi-step flow CSV importer component in drawer
  <CsvImporter {...props} />
  ```

### Patch Changes

* 6a39f50: Updated react-router (^7.13.1 -> ^7.14.0)

* dc4b24b: Updated lucide-react (^0.577.0 -> ^1.7.0)

* 3dd41da: Improve authentication initialization

  * Avoids React strict mode double-invocation issues by running auth side effects outside of React's lifecycle
  * OAuth redirections are now handled before component rendering, eliminating unnecessary UI renders during the callback flow

* Updated dependencies \[01984ee]
  * @tailor-platform/app-shell-vite-plugin@0.2.1

## 0.33.0

### Minor Changes

* 6f5c23f: **Breaking:** `AsyncFetcherFn` now receives `string | null` instead of `string` as the `query` parameter.

  The fetcher is called with `null` when the user has not typed anything (e.g. the dropdown was just opened or the input was cleared). Return initial/default items for `null`, or return an empty array to show nothing until the user starts typing.

  `useAsync` also now returns an `onOpenChange` handler that triggers `fetcher(null)` on the first open, so `Combobox.Async` shows initial items immediately when the dropdown opens.

  ```tsx
  // Before
  const fetcher = async (query: string, { signal }) => { ... };

  // After
  const fetcher = async (query: string | null, { signal }) => {
    const res = await fetch(`/api/items?q=${query ?? ""}`, { signal });
    return res.json();
  };
  ```

* 7917328: Add `useOverrideBreadcrumb` hook for dynamically overriding breadcrumb titles from within page components. This is useful for displaying data-driven titles (e.g., record names) instead of static route-based titles.

  With `defineResource`:

  ```tsx
  import { useOverrideBreadcrumb } from "@tailor-platform/app-shell";

  defineResource({
    path: ":id",
    component: () => {
      const { data } = useQuery(GET_ORDER, { variables: { id } });

      // Update breadcrumb with the order name
      useOverrideBreadcrumb(data?.order?.name);

      return <OrderDetail />;
    },
  });
  ```

  With file-based routing (`pages/orders/[id]/page.tsx`):

  ```tsx
  import { useOverrideBreadcrumb, useParams } from "@tailor-platform/app-shell";

  const OrderDetailPage = () => {
    const { id } = useParams();
    const { data } = useQuery(GET_ORDER, { variables: { id } });

    // Update breadcrumb with the order name
    useOverrideBreadcrumb(data?.order?.name);

    return <div>...</div>;
  };

  export default OrderDetailPage;
  ```

* 58f8024: Fix guards defined via `appShellPageProps` being silently ignored in file-based routing. Guards now correctly produce route loaders for both root and non-root pages.

### Patch Changes

* 1cad50d: Fix portal-based components (`Menu`, `Select`, `Combobox`, `Autocomplete`, `Tooltip`) rendering behind the sidebar by establishing a stacking context on each portal container.

  Centralize all z-index values into CSS custom properties (`--z-sidebar`, `--z-sidebar-rail`, `--z-popup`, `--z-overlay`) defined in `globals.css`.

* afec4f7: Updated graphql (^16.13.0 -> ^16.13.2)

## 0.32.0

### Minor Changes

* 3c1e939: Add `ActivityCard` APIs for both simple and advanced use cases:

  * Standalone API (`<ActivityCard />`) for quick timeline rendering with sensible defaults
  * Compound API (`ActivityCard.Root` / `.Items` / `.Item`) for fully custom item rendering (icons, links, buttons, badges, mixed item kinds)

  ## Standalone API

  ```tsx
  import { ActivityCard } from "@tailor-platform/app-shell";

  <ActivityCard
    items={items}
    title="Updates"
    maxVisible={6}
    overflowLabel="more"
    groupBy="day"
  />;
  ```

  ## Compound API

  ```tsx
  import { ActivityCard, Badge } from "@tailor-platform/app-shell";
  import type { ActivityCardBaseItem } from "@tailor-platform/app-shell";

  interface MyItem extends ActivityCardBaseItem {
    kind: "approval" | "update";
    label?: string;
    message?: string;
  }

  <ActivityCard.Root items={items} title="Updates" groupBy="day">
    <ActivityCard.Items<MyItem>>
      {(item) =>
        item.kind === "approval" ? (
          <ActivityCard.Item indicator={<ApprovedIcon />}>
            <p>{item.label}</p>
            <Badge variant="default">Complete</Badge>
          </ActivityCard.Item>
        ) : (
          <ActivityCard.Item>
            <p>{item.message}</p>
            <a href="#">View changes</a>
          </ActivityCard.Item>
        )
      }
    </ActivityCard.Items>
  </ActivityCard.Root>;
  ```

  Each item must satisfy `ActivityCardBaseItem` (`id` + `timestamp`). Items without an `indicator` render a default timeline node. The `indicator` prop accepts any `ReactNode` (avatars, icons, etc.).

* 3c1e939: Add `Avatar` (Base UI): `Avatar.Root`, `Avatar.Image`, and `Avatar.Fallback` with `size` variants (`sm`, `default`, `lg`) and exported `avatarVariants` and `AvatarProps`. `ActivityCard` uses this shared avatar; export `ActivityCardItem` from the package root for typed activity lists.

  ```tsx
  import { Avatar } from "@tailor-platform/app-shell";

  export function UserAvatar() {
    return (
      <Avatar.Root>
        <Avatar.Image src="/user.png" alt="" />
        <Avatar.Fallback>AB</Avatar.Fallback>
      </Avatar.Root>
    );
  }
  ```

* 693d8aa: Add `xs` size variant to `Button` component — a compact extra-small button (`h-7`, `text-xs`) for inline actions within cards and tight layouts.

  ```tsx
  <Button size="xs" variant="outline">
    Resubmit
  </Button>
  ```

* 497be49: Add `Card` compound component (`Card.Root`, `Card.Header`, `Card.Content`) as a general-purpose container with consistent styling. Existing card-style components (`DescriptionCard`, `MetricCard`, `ActionPanel`) now use `Card` internally.

  ```tsx
  import { Card } from "@tailor-platform/app-shell";

  <Card.Root>
    <Card.Header title="Order Details" description="Summary of order #1234" />
    <Card.Content>
      <p>Content goes here</p>
    </Card.Content>
  </Card.Root>;
  ```

* ea4b256: Add `Form`, `Fieldset`, and `Field` components for building validated forms.

  ### `Form`

  A form element with consolidated error handling and validation. Supports `onFormSubmit` for type-safe parsed form values, and `onSubmit` for native `FormEvent` access. External errors (e.g. API responses) can be fed via the `errors` prop and are automatically routed to matching `Field.Error` components.

  ```tsx
  <Form onFormSubmit={(values) => save(values)}>
    <Field.Root name="email">
      <Field.Label>Email</Field.Label>
      <Field.Control type="email" required />
      <Field.Error match="typeMismatch">Enter a valid email.</Field.Error>
    </Field.Root>
    <button type="submit">Save</button>
  </Form>
  ```

  ### `Fieldset`

  A compound component (`Fieldset.Root`, `Fieldset.Legend`) for grouping related fields with a shared legend for accessible form sectioning.

  ```tsx
  <Fieldset.Root>
    <Fieldset.Legend>Billing details</Fieldset.Legend>
    <Field.Root name="company">
      <Field.Label>Company</Field.Label>
      <Field.Control />
    </Field.Root>
  </Fieldset.Root>
  ```

  ### `Field`

  A compound component (`Field.Root`, `Field.Label`, `Field.Control`, `Field.Description`, `Field.Error`, `Field.Validity`) that groups all parts of a form field and manages its validation state.

  `Field.Root` creates a Field context boundary. All child sub-components (`Field.Label`, `Field.Control`, `Field.Description`, `Field.Error`, `Field.Validity`) and any Base UI-backed AppShell component (e.g. Select, Combobox, Autocomplete) placed inside `Field.Root` automatically connect to this context — inheriting label association (`htmlFor`), `aria-describedby`, disabled state, and validation state (`invalid`, `dirty`, `touched`).

  `Field.Control` is a styled `<input>` that shares its base styles with the `Input` component. It can be omitted when using another AppShell input component (e.g. Select, Combobox, Autocomplete) as a sibling — those components register themselves with the Field context automatically. It also supports native HTML constraint attributes (`required`, `type="email"`, `pattern`, etc.) for built-in validation.

  ```tsx
  <Field.Root name="email">
    <Field.Label>Email</Field.Label>
    <Field.Control type="email" required />
    <Field.Description>We'll never share your email.</Field.Description>
    <Field.Error match="typeMismatch">Please enter a valid email.</Field.Error>
  </Field.Root>
  ```

  #### Using another AppShell component as the control

  `Field.Control` can be omitted when using a Base UI-backed AppShell component (e.g. Select, Combobox). The component registers itself with the Field context automatically, inheriting label association and validation state.

  ```tsx
  <Field.Root name="country">
    <Field.Label>Country</Field.Label>
    <Select>
      <Select.Trigger>
        <Select.Value placeholder="Select a country" />
      </Select.Trigger>
      <Select.Popup>
        <Select.Item value="jp">Japan</Select.Item>
        <Select.Item value="us">United States</Select.Item>
      </Select.Popup>
    </Select>
    <Field.Error>Please select a country.</Field.Error>
  </Field.Root>
  ```

  #### Custom rendering with `Field.Validity`

  `Field.Validity` exposes the field's `ValidityState` via a render callback, allowing fully custom validation UI.

  ```tsx
  <Field.Root name="password">
    <Field.Label>Password</Field.Label>
    <Field.Control type="password" required minLength={8} />
    <Field.Validity>
      {(state) => (
        <ul>
          <li>{state.validity.valueMissing ? "❌" : "✅"} Required</li>
          <li>{state.validity.tooShort ? "❌" : "✅"} At least 8 characters</li>
        </ul>
      )}
    </Field.Validity>
  </Field.Root>
  ```

  ### React Hook Form + Zod integration

  `Field.Root` accepts `isTouched`, `isDirty`, `invalid`, and `error` props that align with RHF's `fieldState` shape, so you can spread `fieldState` directly. Use `Form`'s `onSubmit` prop to connect RHF's `handleSubmit`.

  ```tsx
  import { useForm, Controller } from "react-hook-form";
  import { zodResolver } from "@hookform/resolvers/zod";
  import { z } from "zod";

  const schema = z.object({ email: z.string().email() });

  function MyForm() {
    const { control, handleSubmit } = useForm({
      resolver: zodResolver(schema),
    });

    return (
      <Form onSubmit={handleSubmit((data) => save(data))}>
        <Controller
          name="email"
          control={control}
          render={({ field, fieldState }) => (
            <Field.Root {...fieldState}>
              <Field.Label>Email</Field.Label>
              <Field.Control {...field} />
              <Field.Error>{fieldState.error?.message}</Field.Error>
            </Field.Root>
          )}
        />
        <button type="submit">Save</button>
      </Form>
    );
  }
  ```

  The Field context co-exists with RHF — it only drives accessibility wiring (`htmlFor`, `aria-describedby`) and visual state (`data-invalid`, `data-dirty`, `data-touched`) without interfering with RHF's value management or validation lifecycle.

* 524d49a: Add `MetricCard` component for dashboard KPI summaries (title, value, optional trend and description).

  ```tsx
  import { MetricCard } from "@tailor-platform/app-shell";

  <MetricCard
    title="Net total payment"
    value="$1,500.00"
    trend={{ direction: "up", value: "+5%" }}
    description="vs last month"
  />;
  ```

* 135d5a9: Render module-level breadcrumb segments as non-clickable text when the module has no component.
  Modules defined without a `component` (group-only modules) now display their breadcrumb as plain text instead of a link, preventing navigation to non-existent pages.

### Patch Changes

* 6dec130: Add `color-scheme: dark` to the `.dark` selector in theme CSS so that native form controls (e.g. `<select>`) render correctly in dark mode on Windows.
* ae37125: Fix `breadcrumbTitle` not being propagated in file-based routing. The `breadcrumbTitle` set in `AppShellPageProps.meta` is now correctly reflected in breadcrumbs, matching the behavior of the `defineResource` API.
* 49e2e3a: Fix `DefaultSidebar` not applying active style when `basePath` is not specified. The sidebar now correctly normalizes URLs before comparing with the current pathname, ensuring the active highlight appears on the correct menu item.
* 10c0cd3: Add `min-h-0` to `SidebarInset` so that nested content areas can scroll independently instead of causing the entire page to scroll.

## 0.31.1

### Patch Changes

* e81fbd7: Updated react-router (^7.4.0 -> ^7.13.1)
* Updated dependencies \[01a2249]
  * @tailor-platform/app-shell-vite-plugin@0.2.0

## 0.31.0

### Minor Changes

* e7a1177: Add `Menu`, `Select`, `Combobox`, and `Autocomplete` components.

  ## New components

  ```tsx
  import {
    Menu,
    Select,
    Combobox,
    Autocomplete,
  } from "@tailor-platform/app-shell";
  ```

  ### Menu

  Dropdown menu with compound component API (`Menu.Root`, `Menu.Trigger`, `Menu.Content`, `Menu.Item`, etc.). Supports checkbox/radio items, grouped items, separators, and nested sub-menus via `Menu.SubmenuRoot` / `Menu.SubmenuTrigger`.

  ```tsx
  <Menu.Root>
    <Menu.Trigger>Open menu</Menu.Trigger>
    <Menu.Content>
      <Menu.Item>Edit</Menu.Item>
      <Menu.Item>Duplicate</Menu.Item>
      <Menu.Separator />
      <Menu.Item>Delete</Menu.Item>
    </Menu.Content>
  </Menu.Root>
  ```

  ### Select

  Single or multi-select dropdown. Pass `items` and get a fully assembled select out of the box. Also supports async data fetching via `Select.Async`.

  ```tsx
  <Select
    items={["Apple", "Banana", "Cherry"]}
    placeholder="Pick a fruit"
    onValueChange={(value) => console.log(value)}
  />
  ```

  ### Combobox

  Searchable combobox with single/multi selection. Pass `items` and get a fully assembled combobox with built-in filtering. Supports async data fetching via `Combobox.Async` and user-created items via `onCreateItem` prop.

  ```tsx
  <Combobox
    items={["Apple", "Banana", "Cherry"]}
    placeholder="Search fruits..."
    onValueChange={(value) => console.log(value)}
  />
  ```

  ### Autocomplete

  Text input with a suggestion list. The value is the raw input string, not a discrete item selection. Also supports async suggestions via `Autocomplete.Async`.

  ```tsx
  <Autocomplete
    items={["Apple", "Banana", "Cherry"]}
    placeholder="Type a fruit..."
    onValueChange={(value) => console.log(value)}
  />
  ```

  ### Low-level primitives via `.Parts`

  `Select`, `Combobox`, and `Autocomplete` each expose a `.Parts` namespace containing the styled low-level sub-components (e.g. `Root`, `Input`, `Content`, `Item`, `List`, etc.) and hooks (`useFilter`, `useAsync`, `useCreatable`) for building fully custom compositions when the ready-made component doesn't fit your needs.

  ```tsx
  const { Root, Trigger, Content, Item } = Select.Parts;
  ```

### Patch Changes

* 8e11a5e: Updated lucide-react (^0.562.0 -> ^0.577.0)

## 0.30.0

### Minor Changes

* a8c5dcf: Export primitive UI components (`Button`, `Input`, `Table`, `Dialog`, `Sheet`, `Tooltip`) and update `@base-ui/react` to v1.3.0.

  ## New components

  ```tsx
  import {
    Button,
    Input,
    Table,
    Dialog,
    Sheet,
    Tooltip,
  } from "@tailor-platform/app-shell";
  ```

  ### Button

  Styled button with variant (`default`, `outline`, `destructive`, etc.) and size options.

  ```tsx
  <Button variant="outline" size="sm">
    Click me
  </Button>
  ```

  ### Input

  Styled text input with consistent theming.

  ```tsx
  <Input placeholder="Enter your name" />
  ```

  ### Dialog

  Modal dialog with compound component API (`Dialog.Root`, `Dialog.Content`, etc.).

  ```tsx
  <Dialog.Root>
    <Dialog.Trigger render={<Button />}>Open</Dialog.Trigger>
    <Dialog.Content>
      <Dialog.Title>Confirm</Dialog.Title>
      <Dialog.Description>Are you sure?</Dialog.Description>
      <Dialog.Footer>
        <Dialog.Close render={<Button variant="outline" />}>
          Cancel
        </Dialog.Close>
        <Button>Confirm</Button>
      </Dialog.Footer>
    </Dialog.Content>
  </Dialog.Root>
  ```

  ### Sheet

  Slide-in panel backed by Drawer with native swipe-to-dismiss gesture support.

  ```tsx
  <Sheet.Root side="right">
    <Sheet.Trigger render={<Button />}>Open</Sheet.Trigger>
    <Sheet.Content>
      <Sheet.Title>Settings</Sheet.Title>
    </Sheet.Content>
  </Sheet.Root>
  ```

  ### Tooltip

  Hover/focus tooltip with configurable placement and delay via `Tooltip.Provider`.

  ```tsx
  <Tooltip.Root>
    <Tooltip.Trigger render={<Button />}>Hover me</Tooltip.Trigger>
    <Tooltip.Content>Help text</Tooltip.Content>
  </Tooltip.Root>
  ```

  ### Table

  Semantic HTML table with pre-styled header, body, and footer sub-components.

  ```tsx
  <Table.Root>
    <Table.Header>
      <Table.Row>
        <Table.Head>Name</Table.Head>
        <Table.Head>Email</Table.Head>
        <Table.Head>Role</Table.Head>
      </Table.Row>
    </Table.Header>
    <Table.Body>
      <Table.Row>
        <Table.Cell>Alice</Table.Cell>
        <Table.Cell>alice@example.com</Table.Cell>
        <Table.Cell>Admin</Table.Cell>
      </Table.Row>
    </Table.Body>
  </Table.Root>
  ```

  ## Other changes

  * `DescriptionCard`, `Layout`, and `Layout.Column` now accept an optional `style` prop for inline styles.
  * Fixed Dialog and Sheet overlay flashing on close animation.
  * Fixed missing `astw:` prefixes on sidebar utility classes that caused mobile sidebar UI bugs.

## 0.29.0

### Minor Changes

* fc59c8a: Add ActionPanel component for ERP-style action lists.

  **ActionPanel** — Card with a title and vertical list of actions (icon + label). Each row is a button triggered via `onClick`. The panel uses full width of its parent by default.

  ### Example

  ```tsx
  import { ActionPanel } from "@tailor-platform/app-shell";

  <ActionPanel
    title="Actions"
    actions={[
      {
        key: "create",
        label: "Create new invoice",
        icon: <ReceiptIcon />,
        onClick: () => openCreateModal(),
      },
      {
        key: "docs",
        label: "View documentation",
        icon: <DocIcon />,
        onClick: () => window.open("/docs", "_blank", "noopener,noreferrer"),
      },
    ]}
  />;
  ```

* 3e36ece: Allow modules and resources without a component for path-only definitions

  Modules and resources can now be defined without a `component`, both via `defineModule()`/`defineResource()` and file-based routing. This is useful when a directory exists solely to group child routes under a shared path prefix.

  Accessing a component-less path directly returns a 404 response, while child routes remain accessible as normal.

  ```tsx
  // Module without component — groups child resources under a shared path
  defineModule({
    path: "admin",
    meta: { title: "Admin" },
    resources: [
      defineResource({ path: "users", component: () => <Users /> }),
      defineResource({ path: "roles", component: () => <Roles /> }),
    ],
  });
  // /admin → 404
  // /admin/users → renders Users
  // /admin/roles → renders Roles

  // Resource without component — groups sub-resources under a namespace
  defineResource({
    path: "namespace",
    subResources: [
      defineResource({ path: "page-a", component: () => <div>Page A</div> }),
    ],
  });
  // /namespace → 404
  // /namespace/page-a → renders Page A
  ```

  For file-based routing, simply omit `page.tsx` from a directory:

  ```
  pages/
    admin/
      users/
        page.tsx   ← /admin/users renders this
      roles/
        page.tsx   ← /admin/roles renders this
      (no page.tsx for /admin itself → 404)
  ```

  Guards on component-less routes now execute correctly. Previously, guard loaders were silently ignored when no component was present. Now, guards such as `redirectTo()` will fire as expected, and if all guards return `pass()`, the route falls back to a 404.

* 565ae70: Add `Layout.Header` sub-component and `area` prop to `Layout.Column`.

  ## Motivation

  The current `Layout` component requires a `columns` prop that must exactly match the number of `Layout.Column` children, and embeds header concerns (`title`, `actions`) directly into the layout component. This coupling creates several issues:

  * **Redundant declaration** — The column count can be inferred from the number of `Layout.Column` children, making the `columns` prop unnecessary boilerplate.
  * **Limited column placement** — The 2-column template always treats the 1st column as main (flex) and the 2nd as a fixed sidebar. There is no way to express a "left sidebar + main content" layout.
  * **Mixed responsibilities** — `Layout` handles both page heading (title/actions) and column arrangement. Separating these into `Layout.Header` and `Layout.Column` makes each concern independently composable — for example, placing tabs between the header and columns.

  ## What's New

  * **`Layout.Header`**: Compose inside `Layout` for title, actions, and extra content (e.g. tabs) above columns.
  * **`Layout.Column` `area` prop**: Declare column roles (`left`, `main`, `right`) for area-based width templates, enabling layouts like left sidebar + main that were previously not possible.
  * **`columns` and `gap` props are deprecated**: Column count is auto-detected from children; use `className` for gap.
  * **No runtime breaking changes** — existing code continues to work as-is. Note: `columns` is now optional, so code that directly reads `LayoutProps["columns"]` as a non-optional type will need adjustment.

  ## Usage

  ```tsx
  // With Layout.Header (title, actions, and extra content such as tabs)
  <Layout className="gap-6">
    <Layout.Header title="Edit" actions={[<Button key="save">Save</Button>]}>
      <Tabs>...</Tabs>   {/* Renders below title/actions, above Columns */}
    </Layout.Header>
    <Layout.Column>Main content</Layout.Column>
    <Layout.Column>Side panel</Layout.Column>
  </Layout>

  // With area prop (Left + Main)
  <Layout>
    <Layout.Column area="left">Side nav</Layout.Column>
    <Layout.Column area="main">Main content</Layout.Column>
  </Layout>

  // With area prop (3 columns)
  <Layout>
    <Layout.Column area="left">Left panel</Layout.Column>
    <Layout.Column area="main">Main content</Layout.Column>
    <Layout.Column area="right">Right panel</Layout.Column>
  </Layout>

  // Existing API still works
  <Layout title="Edit" actions={[<Button key="save">Save</Button>]} columns={2}>
    <Layout.Column>Main content</Layout.Column>
    <Layout.Column>Side panel</Layout.Column>
  </Layout>
  ```

  ## Sub-components

  | Component       | Status   | Props                                                           |
  | --------------- | -------- | --------------------------------------------------------------- |
  | `Layout.Column` | Retained | `area?: "left" \| "main" \| "right"`, `className?`, `children?` |
  | `Layout.Header` | **New**  | `title?`, `actions?: ReactNode[]`, `children?: ReactNode`       |

  ## Children Rules

  * **`Layout.Header`** — At most one. If multiple are provided, only the first is rendered.
  * **`Layout.Column`** — 1–3 columns use position-based or area-based width templates. 4+ columns use equal-width (`repeat(N, 1fr)`).
  * **`area` prop** — When any column specifies `area`, all columns switch to area-based widths. Columns without `area` default to `1fr`.
  * **Anything else** — Silently filtered out (not rendered).

  ## Width Templates

  ### Position-based (no `area`, unchanged from current API)

  | Column Count | Responsive Behavior                        | Width Distribution                           |
  | ------------ | ------------------------------------------ | -------------------------------------------- |
  | 1            | Always stacked vertically                  | Full width                                   |
  | 2            | < 1024px: stacked / ≥ 1024px: side-by-side | 1st flex-1, 2nd fixed 280px                  |
  | 3            | < 1280px: stacked / ≥ 1280px: side-by-side | 1st fixed 320px, 2nd flex-1, 3rd fixed 280px |
  | 4+           | < 1280px: stacked / ≥ 1280px: side-by-side | All columns equal width (`repeat(N, 1fr)`)   |

  ### Area-based (with `area` prop)

  | Area    | Width       |
  | ------- | ----------- |
  | `left`  | Fixed 320px |
  | `main`  | flex-1      |
  | `right` | Fixed 280px |

  Responsive behavior is the same: 2 columns break at 1024px, 3+ columns break at 1280px.

## 0.28.0

### Minor Changes

* 4cb5295: Replaced `getAuthHeadersForQuery` with `auth-public-client` 0.5.0's built-in `fetch()` method.

  **Breaking change:** `EnhancedAuthClient.getAuthHeadersForQuery()` has been removed. Use `authClient.fetch` instead, which transparently handles DPoP proof generation and token refresh.

  **Migration:**

  ```diff
   const urqlClient = createClient({
     url: `${authClient.getAppUri()}/query`,
  -  fetchOptions: async () => {
  -    const headers = await authClient.getAuthHeadersForQuery();
  -    return { headers };
  -  },
  +  fetch: authClient.fetch,
   });
  ```

## 0.27.3

### Patch Changes

* 10cb588: Remove horizontal padding in Layout component
* 24f8eb1: Updated es-toolkit (^1.44.0 -> ^1.45.1)

## 0.27.2

### Patch Changes

* b01718f: Updated graphql (^16.12.0 -> ^16.13.0)
* ed5f14f: Fixed incorrect `types` path in `package.json` exports. The `"."` entry was pointing to `./dist/index.d.ts` which does not exist. Updated to `./dist/app-shell.d.ts` to match the actual build output.
* d0dc61b: Reorganized README and documentation structure for public-facing clarity. Added `docs/quickstart.md`, created NPM-facing `packages/core/README.md` with motivation and feature highlights, and ensured each documentation layer (root README, package READMEs, docs/) serves a distinct purpose.

## 0.27.1

### Patch Changes

* e1a12c8: Migrated internal UI primitives from Radix UI/shadcn to Base UI.

  **Updated dependencies:**

  * Removed: `@radix-ui/react-checkbox`, `@radix-ui/react-collapsible`, `@radix-ui/react-dialog`, `@radix-ui/react-dropdown-menu`, `@radix-ui/react-label`, `@radix-ui/react-navigation-menu`, `@radix-ui/react-popover`, `@radix-ui/react-separator`, `@radix-ui/react-slot`, `@radix-ui/react-tooltip`
  * Added: `@base-ui/react` (^1.2.0)

  This is an internal refactoring with no changes to the public API.

## 0.27.0

### Minor Changes

* a7f686f: Adds new Sidebar custom items API for flexible sidebar navigation customization.

  ## New Components

  * `SidebarItem` - Navigation item that auto-resolves title/icon from resource meta
  * `SidebarGroup` - Collapsible group for organizing navigation items
  * `SidebarSeparator` - Visual separator between sidebar sections
  * `WithGuard` - Conditional rendering wrapper based on guard functions

  ## New Hook

  * `usePageMeta` - Hook to access current page metadata (title, icon)

  ## Usage

  ```tsx
  import {
    SidebarLayout,
    DefaultSidebar,
    SidebarItem,
    SidebarGroup,
    SidebarSeparator,
  } from "@tailor-platform/app-shell";

  // Auto-resolved navigation from resource definitions (DefaultSidebar is used by default)
  <SidebarLayout />

  // Fully customized sidebar navigation
  <SidebarLayout
    sidebar={
      <DefaultSidebar>
        <SidebarItem to="/dashboard" />
        <SidebarSeparator />
        <SidebarGroup title="Products" icon={<Package />}>
          <SidebarItem to="/products/all" />
          <SidebarItem to="/products/categories" />
        </SidebarGroup>
        <SidebarItem to="https://docs.example.com" external />
      </DefaultSidebar>
    }
  />

  // Custom rendering with render prop
  <SidebarItem
    to="/tasks"
    render={({ title, icon, isActive }) => (
      <div className={isActive ? "active" : ""}>
        {icon} {title}
      </div>
    )}
  />
  ```

  ## WithGuard Component

  New `WithGuard` component for conditional rendering based on guard functions. Use it to control visibility of sidebar items or any other components.

  ```tsx
  import { WithGuard, pass, hidden } from "@tailor-platform/app-shell";

  // Define a guard function
  const isAdminGuard = ({ context }) =>
    context.currentUser.role === "admin" ? pass() : hidden();

  // Wrap components with WithGuard
  <DefaultSidebar>
    <SidebarItem to="/dashboard" />
    <WithGuard guards={[isAdminGuard]}>
      <SidebarGroup title="Admin" icon={<Shield />}>
        <SidebarItem to="/admin/users" />
      </SidebarGroup>
    </WithGuard>
  </DefaultSidebar>;

  // Curried guards for parameterized conditions
  const hasRole =
    (role: string) =>
    ({ context }) =>
      context.currentUser.role === role ? pass() : hidden();

  <WithGuard guards={[hasRole("manager")]}>
    <SidebarItem to="/reports" />
  </WithGuard>;

  // Use in page components for conditional UI
  const DashboardPage = () => (
    <div>
      <h1>Dashboard</h1>
      <WithGuard guards={[isAdminGuard]}>
        <AdminPanel />
      </WithGuard>
      <WithGuard guards={[hasRole("editor")]}>
        <EditButton />
      </WithGuard>
    </div>
  );
  ```

* e7fa8ec: Add file-based routing support via new Vite plugin

  File-based routing allows defining pages by placing components in a directory structure, eliminating the need for explicit `defineModule()` and `defineResource()` calls.

  ### Why file-based routing?

  **URL-First Design is Already the Norm** - Most projects naturally align their module/resource hierarchy with URL paths. A "purchasing" module at `/purchasing` with an "orders" resource at `/purchasing/orders` is the intuitive choice. The previous API required manually wiring up this structure even though the mapping was already implicit.

  **AI-Friendly Development** - By adopting file-based routing patterns pioneered by Next.js, AI tools can understand and navigate your codebase with less context. Code generation becomes more predictable and the established convention serves as shared knowledge between humans and AI.

  **Providing Rails, Not Just Flexibility** - The legacy `defineModule()`/`defineResource()` API gave flexibility but offered few conventions for directory structure, hierarchy management, or file naming. File-based routing provides an opinionated, battle-tested convention.

  Importantly, this is implemented as a Vite plugin layer on top of the existing programmatic API. Projects requiring non-standard routing can still use `defineModule()`/`defineResource()` directly.

  ### Backward Compatibility

  File-based routing is a **recommended opt-in** feature. The legacy declarative API (`defineModule()`/`defineResource()`) remains fully supported and will continue to work. You can choose either approach per project, though mixing both in the same application is not supported.

  ### Vite Plugin

  The new `@tailor-platform/app-shell-vite-plugin` package provides file-based routing support:

  ```typescript
  // vite.config.ts
  import { appShellRoutes } from "@tailor-platform/app-shell-vite-plugin";

  export default defineConfig({
    plugins: [
      react(),
      appShellRoutes(), // scans src/pages by default
    ],
  });
  ```

  Under the hood, the plugin:

  1. **Scans pages** - Finds `page.tsx` files in `src/pages` and builds a route tree
  2. **Generates virtual module** - Creates `virtual:app-shell-pages` with all discovered pages
  3. **Auto-injects pages** - Intercepts `@tailor-platform/app-shell` imports and wraps `AppShell` with `AppShell.WithPages(pages)`
  4. **Validates at build time** - Uses ts-morph AST analysis to validate `appShellPageProps`
  5. **Supports HMR** - Watches for page changes and triggers hot reload

  No manual wiring needed—just import `AppShell` as usual and pages are automatically available.

  ### Defining Pages

  ```tsx
  // src/pages/dashboard/page.tsx
  import type { AppShellPageProps } from "@tailor-platform/app-shell";

  const DashboardPage = () => <div>Dashboard</div>;

  DashboardPage.appShellPageProps = {
    meta: { title: "Dashboard" },
    guards: [authGuard],
  } satisfies AppShellPageProps;

  export default DashboardPage;
  ```

  ### Type-safe Routes (Optional)

  ```typescript
  // vite.config.ts
  appShellRoutes({ generateTypedRoutes: true });
  ```

  When enabled, the plugin generates `src/routes.generated.ts` containing:

  * `GeneratedRouteParams` type mapping all routes to their parameter types
  * `paths` helper with a type-safe `for()` method for building URLs
  * Module augmentation to register route types with app-shell

  ```tsx
  // Auto-generated: src/routes.generated.ts
  export type GeneratedRouteParams = {
    "/": {};
    "/dashboard": {};
    "/dashboard/orders/:id": { id: string };
  };
  export const paths = createTypedPaths<GeneratedRouteParams>();

  // Usage - TypeScript enforces correct params
  import { paths } from "./routes.generated";

  paths.for("/dashboard"); // ✓ OK
  paths.for("/dashboard/orders/:id", { id: "123" }); // ✓ OK → "/dashboard/orders/123"
  paths.for("/dashboard/orders/:id"); // ✗ Error: missing 'id'
  paths.for("/invalid-route"); // ✗ Error: route doesn't exist
  ```

  ### Breaking Change: Guard/Loader Cascade Behavior

  In the legacy `defineModule()`/`defineResource()` API, guards and loaders defined at the module level were automatically cascaded to all child resources. This automatic cascade behavior has been removed in both the legacy API and file-based routing—**guards and loaders are no longer automatically inherited**. Each resource or page must explicitly define its own guards and loaders.

  **Before (legacy API):**

  ```tsx
  defineModule({
    path: "/dashboard",
    guards: [authGuard], // Applied to all child resources automatically
    resources: [
      defineResource({ path: "/orders", element: <Orders /> }), // authGuard applied
      defineResource({ path: "/reports", element: <Reports /> }), // authGuard applied
    ],
  });
  ```

  **After (legacy API):**

  ```tsx
  defineModule({
    path: "/dashboard",
    guards: [authGuard],
    resources: [
      defineResource({
        path: "/orders",
        guards: [authGuard],
        element: <Orders />,
      }), // Must be explicitly defined
      defineResource({
        path: "/reports",
        guards: [authGuard],
        element: <Reports />,
      }), // Must be explicitly defined
    ],
  });
  ```

  Note: File-based routing, introduced in this release, also does not support guard/loader cascading. Each page must define its own guards and loaders explicitly:

  ```tsx
  // src/pages/dashboard/orders/page.tsx
  OrdersPage.appShellPageProps = {
    guards: [authGuard], // Must be explicitly defined
  } satisfies AppShellPageProps;

  // src/pages/dashboard/reports/page.tsx
  ReportsPage.appShellPageProps = {
    guards: [authGuard], // Must be explicitly defined
  } satisfies AppShellPageProps;
  ```

  **Rationale:** Explicit guard/loader definitions per resource/page improve code clarity and make it easier to understand the security requirements of each route at a glance.

  **Migration tip:** If you need the previous cascading behavior, compose your guards array explicitly:

  ```tsx
  // src/guards.ts
  export const requireAuth = [authGuard];
  export const requireAdmin = [authGuard, adminRoleGuard];

  // src/pages/dashboard/orders/page.tsx
  import { requireAuth } from "@/guards";

  OrdersPage.appShellPageProps = {
    guards: [...requireAuth, canViewOrders],
  } satisfies AppShellPageProps;

  // src/pages/admin/users/page.tsx
  import { requireAdmin } from "@/guards";

  UsersPage.appShellPageProps = {
    guards: [...requireAdmin],
  } satisfies AppShellPageProps;
  ```

  ## Breaking Change: Module without component requires guards

  As part of the ongoing effort to decouple navigation and routing (aligned with file-based routing), the automatic redirect behavior for modules without a `component` has been removed.

  Previously, a module without a `component` would automatically redirect to the first visible resource. However, in file-based routing, the resource hierarchy is determined ad-hoc by the vite-plugin based on directory structure, making this implicit redirect behavior inconsistent and unpredictable. To maintain consistency across both explicit and file-based routing, this behavior has been removed.

  If a module is defined without both `component` and `guards`, an error will be thrown at runtime. You must provide at least one of them.

  ```tsx
  // Before: automatic redirect to first visible resource
  defineModule({
    path: "reports",
    resources: [salesResource, usersResource],
  });

  // After: explicit redirect via guards
  defineModule({
    path: "reports",
    guards: [() => redirectTo("sales")],
    resources: [salesResource, usersResource],
  });

  // Error: defining a module without both component and guards will throw
  defineModule({
    path: "reports",
    resources: [salesResource, usersResource],
  }); // => throws an error
  ```

### Patch Changes

* 8c19779: Updated react-hook-form (^7.71.1 -> ^7.71.2)
* 50ddd5f: Updated tailwind-merge (^3.4.0 -> ^3.5.0)
* 1338776: Updated es-toolkit (^1.41.0 -> ^1.44.0)
* Updated dependencies \[e7fa8ec]
  * @tailor-platform/app-shell-vite-plugin@0.27.0

## 0.26.3

### Patch Changes

* 2170b9e: Updated oauth4webapi (^3.8.3 -> ^3.8.5)
* 5aef4ad: Update auth-public-client to 0.4.1
* 18f9b66: Updated react-hook-form (^7.54.2 -> ^7.71.1)

## 0.26.2

### Patch Changes

* 7fee07a: Updated @tanstack/react-table (^8.21.2 -> ^8.21.3)

## 0.26.1

### Patch Changes

* 3fe975b: Fix content area layout to properly fill remaining space

  Added `flex-1` and `min-h-0` to the content wrapper in SidebarLayout, allowing child pages to use `h-full` or `flex-1` to fill the remaining space after the header/breadcrumb. This eliminates the need for hacky `calc(100dvh - Xrem)` workarounds.

  Also added `overflow-hidden` to the sidebar-wrapper to enable proper scrolling within nested containers (e.g., kanban board lanes).

## 0.26.0

### Minor Changes

* 72bbcb6: Replace `@tailor-platform/auth-browser-client` with `@tailor-platform/auth-public-client` and add Suspense support

  ## Motivation

  The previous authentication implementation using `@tailor-platform/auth-browser-client` relied on HTTPOnly cookie-based session management. This caused authentication failures on browsers with strict privacy protections, particularly Safari with its Intelligent Tracking Prevention (ITP) feature, and Brave with its similar tracking prevention mechanisms. These browsers block or restrict cross-site cookies, which prevented the HTTPOnly cookies from being stored and sent properly, causing authentication to fail silently or users to be logged out unexpectedly.

  To address this cross-browser compatibility issue, we have migrated to `@tailor-platform/auth-public-client`, which uses DPoP (Demonstrating Proof of Possession) token binding with IndexedDB storage instead of cookies. This approach works reliably across all major browsers (including Safari 14+ and Brave) regardless of their privacy settings.

  ## Key Changes

  * **Cross-browser Compatibility**: Works reliably on Safari, Brave, and other browsers with strict privacy settings
  * **Suspense Support**: Added `useAuthSuspense` hook for React Suspense integration
  * **Module-level Client**: Auth client can now be created at module level and shared across the app

  ## Breaking Changes

  The underlying authentication package has been replaced with `@tailor-platform/auth-public-client` v0.3.1, which uses DPoP (Demonstrating Proof of Possession) token binding.

  ### AuthProvider API Changes

  * `AuthProvider` now requires a `client` prop created with `createAuthClient` from `@tailor-platform/app-shell`
  * The `apiEndpoint` prop has been removed - the client automatically uses the `appUri` provided during creation
  * You must use the wrapped `createAuthClient` from `@tailor-platform/app-shell` (not the original from `@tailor-platform/auth-public-client`)

  ### Hook Return Value Changes

  * **`useAuth`**: Now returns `{ isAuthenticated, error, isReady, login, logout, checkAuthStatus }` directly instead of `{ authState, ... }`
  * **`useAuthSuspense`**: Returns `{ isAuthenticated, error, login, logout, checkAuthStatus }` (no `isReady` since Suspense handles loading)

  ### Removed Exports

  * `DefaultUser` and `AuthRegister` types are no longer exported
  * `user` property removed from `AuthState` (see "Removed: Built-in User Fetching" below)

  ### Removed: Built-in User Fetching (meQuery)

  The previous implementation fetched user information internally using a simple `fetch` call to the `/query` endpoint. This design had several issues:

  1. **Caching conflicts**: When applications use GraphQL client libraries (urql, Apollo, etc.) with sophisticated caching mechanisms, having a separate internal fetch for user data creates inconsistencies and bypasses the cache.
  2. **Inflexibility**: Applications couldn't customize the user query or integrate it with their existing data fetching patterns.
  3. **Mixed responsibilities**: The auth provider was handling both authentication AND user data fetching, which are separate concerns.

  **The new design focuses solely on authentication responsibilities:**

  * Token management (access tokens, refresh tokens)
  * Login/logout flows
  * OAuth callback handling
  * Authentication state (`isAuthenticated`, `error`, `isReady`)

  **User information should now be fetched by your application** using your preferred GraphQL client library, which gives you:

  * Full control over caching behavior
  * Ability to customize the user query
  * Consistent data fetching patterns across your app
  * Better integration with your existing data layer

  ## Migration Guide

  ### Before (v0.22.0 and earlier)

  ```tsx
  import { AuthProvider, useAuth } from "@tailor-platform/app-shell";

  function App() {
    return (
      <AuthProvider
        apiEndpoint="https://xyz.erp.dev"
        clientId="your-client-id"
        redirectUri="https://your-app.com"
      >
        <MyComponent />
      </AuthProvider>
    );
  }

  function MyComponent() {
    const { authState, login, logout } = useAuth();

    if (authState.isLoading) return <div>Loading...</div>;
    if (!authState.isAuthenticated)
      return <button onClick={login}>Log In</button>;

    // User was available from authState
    return <div>Welcome, {authState.user?.email}!</div>;
  }
  ```

  ### After (v0.23.0+)

  ```tsx
  import {
    createAuthClient,
    AuthProvider,
    useAuth,
  } from "@tailor-platform/app-shell";

  // Create auth client outside component (module level)
  const authClient = createAuthClient({
    clientId: "your-client-id",
    appUri: "https://xyz.erp.dev",
    redirectUri: "https://your-app.com", // optional, defaults to window.location.origin
  });

  function App() {
    return (
      <AuthProvider client={authClient}>
        <MyComponent />
      </AuthProvider>
    );
  }

  function MyComponent() {
    // New: properties returned directly (not nested in authState)
    const { isAuthenticated, isReady, login, logout } = useAuth();

    if (!isReady) return <div>Loading...</div>;
    if (!isAuthenticated) return <button onClick={login}>Log In</button>;

    // User info should now be fetched separately using your GraphQL client
    return <UserProfile />;
  }

  // Fetch user info with your GraphQL client (e.g., urql)
  function UserProfile() {
    const [{ data }] = useQuery({ query: ME_QUERY });
    return <div>Welcome, {data?.me?.email}!</div>;
  }
  ```

  ## Usage Examples

  ### Basic Authentication

  ```tsx
  import {
    createAuthClient,
    AuthProvider,
    useAuth,
  } from "@tailor-platform/app-shell";

  const authClient = createAuthClient({
    clientId: "your-client-id",
    appUri: "https://xyz.erp.dev",
  });

  function App() {
    return (
      <AuthProvider client={authClient}>
        <MyComponent />
      </AuthProvider>
    );
  }

  function MyComponent() {
    const { isAuthenticated, isReady, login, logout } = useAuth();

    if (!isReady) return <div>Loading...</div>;
    if (!isAuthenticated) return <button onClick={login}>Log In</button>;

    return (
      <div>
        <p>Authenticated!</p>
        <button onClick={logout}>Log Out</button>
      </div>
    );
  }
  ```

  ### With Suspense

  ```tsx
  import { Suspense } from "react";
  import {
    createAuthClient,
    AuthProvider,
    useAuthSuspense,
  } from "@tailor-platform/app-shell";

  const authClient = createAuthClient({
    clientId: "your-client-id",
    appUri: "https://xyz.erp.dev",
  });

  function App() {
    return (
      <AuthProvider client={authClient}>
        <Suspense fallback={<div>Loading authentication...</div>}>
          <ProtectedContent />
        </Suspense>
      </AuthProvider>
    );
  }

  function ProtectedContent() {
    // isReady is guaranteed to be true here (Suspense handles loading)
    const { isAuthenticated, login, logout } = useAuthSuspense();

    if (!isAuthenticated) {
      return <button onClick={login}>Log In</button>;
    }

    return (
      <div>
        <p>Authenticated!</p>
        <button onClick={logout}>Log Out</button>
      </div>
    );
  }
  ```

  ### Initializing GraphQL Client with Auth Headers

  The new API makes it easy to share the auth client between `AuthProvider` and your GraphQL client, with less duplication:

  ```tsx
  import { createAuthClient, AuthProvider } from "@tailor-platform/app-shell";
  import { createClient, Provider } from "urql";

  // Create auth client at module level
  const authClient = createAuthClient({
    clientId: "your-client-id",
    appUri: "https://api.example.com",
  });

  // Create urql client - no need to repeat the URL!
  const urqlClient = createClient({
    url: `${authClient.getAppUri()}/query`,
    fetchOptions: async () => {
      // Simplified: no need to pass URL again
      const headers = await authClient.getAuthHeadersForQuery();
      return { headers };
    },
  });

  function App() {
    return (
      <AuthProvider client={authClient}>
        <Provider value={urqlClient}>
          <YourAppComponents />
        </Provider>
      </AuthProvider>
    );
  }
  ```

  ### Fetching User Information

  Since user fetching is no longer built-in, here's a recommended pattern:

  ```tsx
  import { useQuery, gql } from "urql";
  import { useAuth } from "@tailor-platform/app-shell";

  const ME_QUERY = gql`
    query Me {
      me {
        id
        email
        name
      }
    }
  `;

  function UserProfile() {
    const { isAuthenticated } = useAuth();
    const [{ data, fetching }] = useQuery({
      query: ME_QUERY,
      pause: !isAuthenticated, // Don't fetch if not authenticated
    });

    if (fetching) return <div>Loading user...</div>;
    if (!data?.me) return <div>Not logged in</div>;

    return <div>Welcome, {data.me.name}!</div>;
  }
  ```

## 0.25.0

### Minor Changes

* 6ff1478: Export `useToast` hook

  `useToast` is just a hook that returns sonner.

### Patch Changes

* 10b521d: Fix module redirect to skip hidden resources

  When a module has no `component` and redirects to its first resource, the redirect now correctly skips resources that are hidden by guards. If all resources are hidden, the module itself returns a 404.

  * Redirects to the first visible (non-hidden) resource instead of always redirecting to the first resource
  * Returns 404 when all resources in the module are hidden by guards

## 0.24.0

### Minor Changes

* ae8f732: Add `t.dynamic()` method for resolving i18n labels with dynamic keys

  The `useT` hook now returns a function with a `dynamic` method that allows resolving labels with runtime-constructed keys:

  ```tsx
  const t = labels.useT();

  const employeeType = "STAFF";
  t.dynamic(`employees.${employeeType}`, "Unknown"); // Returns the label or "Unknown" if not found
  ```

* 193afe9: Make `component` optional in `defineModule`

  * `defineModule` now accepts an optional `component` prop
  * When `component` is omitted, the module acts as a container for resources and automatically redirects to the first resource
  * `menuItemClickable` is set to `false` for modules without a component

  ```tsx
  // With component - renders the component at /dashboard
  defineModule({
    path: "dashboard",
    component: () => <DashboardPage />,
    resources: [...]
  });

  // Without component - redirects /reports to /reports/sales
  defineModule({
    path: "reports",
    resources: [
      defineResource({ path: "sales", ... }),
      defineResource({ path: "users", ... }),
    ]
  });
  ```

* 617c1ac: ## Route Guards and Context Data

  This release introduces a new route guards system and custom context data support, replacing the previous `accessControl` API.

  ### Motivation

  #### Route Guards

  Inspired by Angular Route Guards, this feature introduces a middleware-like pattern for route access control.

  * **Composable**: Guards can be combined in an array, promoting separation of concerns and reusability
  * **Semantic Constraints**: Guard results are limited to `pass`, `hidden`, or `redirect`, making behavior predictable and explicit
  * **Reusable**: Define guards once and share them across multiple routes

  #### Context Data

  Provides a type-safe dependency injection mechanism for passing data from the application root to guards and components.

  * **Type-Safe**: Module augmentation ensures `contextData` is fully typed throughout the application
  * **Centralized**: Manage API clients, user state, and feature flags in one place
  * **Testable**: Easy to mock and inject different contexts for testing

  ### Breaking Changes

  * **`accessControl` is replaced by `guards`**: The `accessControl` option in `defineModule` and `defineResource` has been replaced with a more flexible `guards` array.
  * **`RedirectConfig` and `redirectToResource` are removed**: Use `guards` with `redirectTo()` instead.

  ### New Features

  #### 1. Route Guards

  Guards are functions that control access to routes. They are executed in order, and the first non-`pass` result stops the chain.

  ```tsx
  import {
    defineResource,
    pass,
    hidden,
    redirectTo,
    type Guard,
  } from "@tailor-platform/app-shell";

  // Reusable guards
  const requireAuth: Guard = ({ context }) => {
    if (!context.currentUser) {
      return redirectTo("/login");
    }
    return pass();
  };

  const requireAdmin: Guard = ({ context }) => {
    if (context.currentUser.role !== "admin") {
      return hidden(); // Shows 404
    }
    return pass();
  };

  // Use guards in resource definition
  export const adminResource = defineResource({
    path: "admin/users/:id",
    component: AdminUserPage,
    guards: [
      requireAuth,
      requireAdmin,
      async ({ params, context }) => {
        // Check organization access
        const user = await context.apiClient.getUser(params.id);
        if (user.orgId !== context.currentUser.orgId) {
          return hidden();
        }
        return pass();
      },
    ],
  });
  ```

  #### 2. Custom Context Data

  Pass arbitrary data through `AppShellProps` and access it from guards and components.

  **Step 1: Define your context data type using module augmentation**

  ```typescript
  // types.d.ts
  declare module "@tailor-platform/app-shell" {
    interface AppShellRegister {
      contextData: {
        apiClient: ApiClient;
        currentUser: User | null;
        featureFlags: {
          enableNewUI: boolean;
        };
      };
    }
  }
  ```

  **Step 2: Pass context data to AppShell**

  ```tsx
  // App.tsx
  import { AppShell } from "@tailor-platform/app-shell";

  function App() {
    const apiClient = useApiClient();
    const currentUser = useCurrentUser();
    const featureFlags = useFeatureFlags();

    return (
      <AppShell
        modules={modules}
        contextData={{
          apiClient,
          currentUser,
          featureFlags,
        }}
      />
    );
  }
  ```

  **Step 3: Access context data in guards**

  ```tsx
  const myGuard: Guard = ({ context }) => {
    // `context` is fully typed based on your AppShellRegister
    if (context.featureFlags.enableNewUI) {
      return redirectTo("/new-dashboard");
    }
    return pass();
  };
  ```

  **Step 4: Access context data in components**

  ```tsx
  import { useAppShell } from "@tailor-platform/app-shell";

  function MyComponent() {
    const { contextData } = useAppShell();

    return <div>Welcome, {contextData.currentUser?.name}</div>;
  }
  ```

  ### Migration Guide

  **Before (accessControl):**

  ```tsx
  defineResource({
    path: "admin",
    component: AdminPage,
    accessControl: async ({ params }) => {
      const hasAccess = await checkAccess(params.id);
      return hasAccess ? { state: "visible" } : { state: "hidden" };
    },
  });
  ```

  **After (guards):**

  ```tsx
  defineResource({
    path: "admin",
    component: AdminPage,
    guards: [
      async ({ params }) => {
        const hasAccess = await checkAccess(params.id);
        return hasAccess ? pass() : hidden();
      },
    ],
  });
  ```

  **Before (redirectToResource):**

  ```tsx
  defineModule({
    path: "dashboard",
    component: redirectToResource("dashboard/overview"),
    resources: [...],
  });
  ```

  **After (guards with redirectTo):**

  ```tsx
  defineModule({
    path: "dashboard",
    component: () => null,
    guards: [() => redirectTo("dashboard/overview")],
    resources: [...],
  });
  ```

  ### New Exports

  * `Guard` - Guard function type
  * `GuardContext` - Context passed to guards (`params`, `searchParams`, `signal`, `context`)
  * `GuardResult` - Result type (`pass`, `hidden`, or `redirect`)
  * `pass()` - Helper to allow access
  * `hidden()` - Helper to deny access (404)
  * `redirectTo(path)` - Helper to redirect
  * `AppShellRegister` - Interface for module augmentation
  * `ContextData` - Inferred context data type

### Patch Changes

* 42daf85: Updated react-dom (^19.2.1 -> ^19.2.4)

## 0.23.0

### Minor Changes

* 3f42257: Add Layout component for responsive column layouts

  * `Layout` - Responsive column layout component with automatic responsive behavior
  * `Layout.Column` - Sub-component for wrapping individual column content
  * Support for 1, 2, and 3 column layouts with automatic responsive stacking
  * Optional `title` and `actions` props for built-in header with action buttons

  ```tsx
  import { Layout } from "@tailor-platform/app-shell";

  // Basic 2 Column Layout
  <Layout columns={2}>
    <Layout.Column>Main content</Layout.Column>
    <Layout.Column>Side panel</Layout.Column>
  </Layout>

  // With header title and action buttons
  <Layout
    columns={2}
    title="Page Title"
    actions={[
      <Button key="cancel" variant="secondary">Cancel</Button>,
      <Button key="save">Save</Button>,
    ]}
  >
    <Layout.Column>...</Layout.Column>
    <Layout.Column>...</Layout.Column>
  </Layout>
  ```

## 0.22.0

### Minor Changes

* b09e30d: Add DescriptionCard component for ERP document display

  * `DescriptionCard` - Card component for structured key-value information
  * `Badge` - Status badge component with semantic variants (success, warning, error, etc.)
  * 7 field types: text, badge, money, date, link, address, reference
  * Text truncation with tooltip: `meta: { truncateLines: 2 }`
  * Badge values auto-converted to sentence case (e.g., "CONFIRMED" → "Confirmed")
  * Responsive grid layout (4 → 3 → 2 → 1 columns)

  ```tsx
  import { DescriptionCard } from "@tailor-platform/app-shell";

  <DescriptionCard
    data={order}
    title="Order Summary"
    fields={[
      {
        key: "status",
        label: "Status",
        type: "badge",
        meta: { badgeVariantMap: { CONFIRMED: "outline-success" } },
      },
      { type: "divider" },
      { key: "note", label: "Notes", meta: { truncateLines: 2 } },
    ]}
  />;
  ```

## 0.21.1

### Patch Changes

* bc08996: Updated @radix-ui/react-navigation-menu (^1.2.5 -> ^1.2.14)

## 0.21.0

### Minor Changes

* 32f0c81: `accessControl` is introduced as the unified way to hide modules or resources when a feature flag or permission is missing.

  ```tsx
  // Example: permission-gated reports module
  export const reportsModule = defineModule({
    // ...
    accessControl: async ({ signal }) => {
      const ok = await fetch("/api/me/permissions?scope=reports", {
        signal,
      }).then((r) => r.ok);
      return { state: ok ? "visible" : "hidden" };
    },
  });

  // Example: resource-level access control
  const reportsListResource = defineResource({
    // ...
    accessControl: () => ({ state: "hidden" }),
  });

  // Example: rollout by tenant tier.
  const billingModule = defineModule({
    // ...
    accessControl: async () => {
      const plan = await getCurrentTenantPlan();
      return { state: plan === "enterprise" ? "visible" : "hidden" };
    },
  });
  ```

## 0.20.1

### Patch Changes

* 2418378: Improve CommandPalette UI with hierarchical path display

  * Display module/resource hierarchy as breadcrumb format (e.g., "Dashboard > Analytics")
  * Widen the dialog width for better readability
  * Show URL path below the breadcrumb in smaller text

* fb7e114: Updated @radix-ui/react-collapsible (^1.1.3 -> ^1.1.12)

## 0.20.0

### Minor Changes

* 1a2ee08: Add `CommandPalette` component for quick page navigation.

  The CommandPalette provides a keyboard-driven interface (Cmd+K / Ctrl+K) for searching and navigating between pages in your application. It automatically collects navigable routes from your module definitions and supports both English and Japanese locales.

  ## Features

  * Global keyboard shortcut: `Cmd+K` (Mac) / `Ctrl+K` (Windows)
  * Fuzzy search by page title or path
  * Keyboard navigation with arrow keys and Enter

  ## Usage

  The `CommandPalette` component is designed to be used within an `AppShell` context. It automatically reads module configurations and provides navigation capabilities.

  ```tsx
  import {
    AppShell,
    CommandPalette,
    SidebarLayout,
  } from "@tailor-platform/app-shell";

  const App = () => (
    <AppShell modules={modules} locale="en">
      <>
        <SidebarLayout />
        <CommandPalette />
      </>
    </AppShell>
  );
  ```

### Patch Changes

* d680b83: Updated oauth4webapi (^3.8.1 -> ^3.8.3)
* e6020ae: Updated lucide-react (^0.487.0 -> ^0.562.0)
* cda3d85: Updated @radix-ui/react-popover (^1.1.6 -> ^1.1.15)
* 7fcc21c: Updated @radix-ui/react-tooltip (^1.1.8 -> ^1.2.8)

## 0.19.0

### Minor Changes

* 1833c9c: Replace `BuiltinIdPAuthProvider` with new `AuthProvider` using `@tailor-platform/auth-browser-client`.

  The previous `BuiltinIdPAuthProvider` only supported authentication with Tailor Platform's built-in IdP system. With the new `AuthProvider` powered by `@tailor-platform/auth-browser-client`, you can now authenticate with any IdP configured in Tailor Platform's Auth service (e.g., Google, Okta, Auth0, etc.).

  # New APIs

  ## Component

  **`AuthProvider`** - New props:

  * `meQuery`: Custom GraphQL query to fetch the current authenticated user. If you override `AuthRegister["user"]`, make sure to have the fields match your custom user type.
  * `autoLogin`: Enable automatic login on initialization
  * `guardComponent`: Component to render while loading or unauthenticated

  ## Hook

  **`useAuth`** - New returns:

  * `authState`: Current auth state (`isLoading`, `isAuthenticated`, `user`)
  * `checkAuthStatus()`: Manually verify authentication status
  * `handleCallback()`: Handle OAuth callback

  ## Extending User Type with type safety

  By default, `authState.user` returned from `useAuth()` has the `DefaultUser` type, which includes the following fields:

  ```ts
  type DefaultUser = {
    id: string;
    email: string;
    name: string;
  };
  ```

  If your application needs additional user fields (e.g., roles, organization info, custom attributes), you can extend the user type using TypeScript's **module augmentation** feature. This ensures full type safety when accessing user properties throughout your application.

  ### Step 1: Define your custom user type

  Use the `AuthRegister` interface to declare your extended user type. This interface uses declaration merging to override the default user type globally.

  ```tsx
  // types/auth.d.ts (or any .ts/.tsx file in your project)
  declare module "@tailor-platform/app-shell" {
    interface AuthRegister {
      user: DefaultUser & {
        roles: Array<string>;
        organizationId: string;
        // Add any other custom fields your API returns
      };
    }
  }
  ```

  ### Step 2: Provide a matching `meQuery`

  The `meQuery` prop defines the GraphQL query used to fetch the authenticated user. **The fields in your query must match the fields defined in your custom user type.**

  ```tsx
  import {
    AppShell,
    AuthProvider,
    SidebarLayout,
  } from "@tailor-platform/app-shell";

  const App = () => (
    <AppShell>
      <AuthProvider
        apiEndpoint="..."
        clientId="..."
        meQuery={`
          query {
            me {
              id
              email
              name
              roles
              organizationId
            }
          }
        `}
      >
        <SidebarLayout />
      </AuthProvider>
    </AppShell>
  );
  ```

  ### Step 3: Access typed user data

  After the above setup, `authState.user` will be fully typed with your custom user type:

  ```tsx
  import { useAuth } from "@tailor-platform/app-shell";

  const MyComponent = () => {
    const { authState } = useAuth();

    // TypeScript knows these properties exist
    console.log(authState.user.roles); // Array<string>
    console.log(authState.user.organizationId); // string
    console.log(authState.user.email); // string (from DefaultUser)

    // ...
  };
  ```

  > **Note:** If you don't need custom user fields, you can skip this setup entirely. The default `meQuery` fetches `id`, `email`, and `name` automatically.

  # Migration

  Key changes:

  * `BuiltinIdPAuthProvider` is removed. Use `AuthProvider` instead.
  * `useBuiltinIdpAuth` is removed. Use `useAuth` instead.
  * Utility functions (`buildAuthorizationUrl`, `exchangeCodeForToken`, `prepareLogin`, `handleOAuthCallback`) are no longer exported.

  ```tsx
  // Before
  import {
    BuiltinIdPAuthProvider,
    useBuiltinIdpAuth,
  } from "@tailor-platform/app-shell";

  <BuiltinIdPAuthProvider apiEndpoint="..." clientId="...">
    {children}
  </BuiltinIdPAuthProvider>;

  const { login, logout } = useBuiltinIdpAuth();

  // After
  import { AuthProvider, useAuth } from "@tailor-platform/app-shell";

  <AuthProvider
    apiEndpoint="..."
    clientId="..."
    guardComponent={() => <Loading />}
  >
    {children}
  </AuthProvider>;

  const { login, logout, authState } = useAuth();
  ```

## 0.18.0

### Minor Changes

* 91bfc1f: Add `defineI18nLabels` function for internationalization support.

  `defineI18nLabels` defines internationalization labels for multiple locales with `en` as the required default locale, and returns an object with:

  * `useT`: A hook to get the translated label resolver function for use in React components
  * `t`: A function to get a `LocalizedString` for a specific label key, useful for `meta.title` in module/resource definitions

  Labels can be either static strings or dynamic functions that take props.

  ### Usage

  Define your i18n labels and export the returned `useT` hook:

  ```tsx
  // i18n-labels.ts
  import { defineI18nLabels } from "@tailor-platform/app-shell";

  export const labels = defineI18nLabels({
    en: {
      welcome: "Welcome to our app",
      greeting: (args: { name: string }) => `Hello, ${args.name}!`,
    },
    ja: {
      welcome: "アプリへようこそ",
      greeting: (args: { name: string }) => `こんにちは、${args.name}さん！`,
    },
  });

  // Export useT hook from the returned object
  export const useT = labels.useT;
  ```

  Use `useT` in components:

  ```tsx
  import { useT } from "./i18n-labels";

  const MyComponent = () => {
    const t = useT();

    return (
      <div>
        {/* Static label */}
        {t("welcome")}

        {/* Dynamic label with props (type-safe) */}
        {t("greeting", { name: "John" })}
      </div>
    );
  };
  ```

  Use `labels.t()` in resource definitions:

  ```tsx
  import { defineResource } from "@tailor-platform/app-shell";
  import { labels } from "./i18n-labels";

  const resource = defineResource({
    path: "example",
    meta: {
      // Static label
      title: labels.t("welcome"),
      // Dynamic label with props bound at definition time
      // title: labels.t("greeting", { name: "User" }),
    },
    component: ExampleComponent,
  });
  ```

* 096eb28: Add browser language detection to decide AppShell locale configuration

### Patch Changes

* d9e4e7c: Use vite as bundler

## 0.17.1

### Patch Changes

* 0cdda8f: Fix breadcrumb segment parsing

## 0.17.0

### Minor Changes

* 8092240: Deprecate `contentBorder` style prop
* 8092240: Flatten `configurations` key in AppShell component for simplicity
* 8092240: Rename `SidebarLayoutContainer` to `SidebarLayout`

## 0.16.0

### Minor Changes

* 9e0c17c: `Link` and `useNavigate` destinations should now be provided without the app's base-path prefix; the router applies the scope for you.

  ```tsx
  // basePath === "admin"

  // Before
  <Link to="/admin/dashboard" />;
  navigate("/admin/settings");

  // After
  <Link to="/dashboard" />;
  navigate("/settings");
  ```

### Patch Changes

* 9e0c17c: Remove next.js from peerDependecies

## 0.15.0

### Minor Changes

* 5b02e8a: Remove the implicit `/resources` prefix from generated module and resource routes.

  Consumers should update any hardcoded URLs and expectations to match the new base path structure.

### Patch Changes

* f34af20: Correct `AppShellProps` to accept `configurations.settingsResources` with the proper typing and remove the obsolete `configurations.settingsModules` prop.

  ```tsx
  <AppShell
    configurations={{
      modules,
      settingsResources: [settingsResource],
    }}
  >
    <SidebarLayoutContainer />
  </AppShell>
  ```

* f34af20: Accessing "/settings" path without settings resources will now go 404

  Previously, it gets runtime error caused by out-of-index array access

## 0.14.1

### Patch Changes

* 1cdd5e1: Update depepdencies for security vulnerabilities

## 0.14.0

### Minor Changes

* ca82334: Add configurable error boundaries
  * Add default error boundary that auto-applies to all routes
  * Support custom error boundaries at global, module, and resource levels
  * Add catch-all route for 404 handling

### Patch Changes

* 0a24505: Make `redirectUri` in `BuiltinIdPAuthProvider` optional

  It internally has been fallen back into `window.location.origin`, so should not be required for user experience

* 0a24505: Rename `idpEndpoint` prop in `BuiltinIdPAuthProvider` to `apiEndpoint` to properly tell what it expects to get from users.

## 0.13.0

### Minor Changes

* ec61cab: Add `redirectToResource` helper for declarative module redirection. Modules can now redirect to resources using `component: redirectToResource("path/to/resource")` instead of rendering a component. Redirection is handled efficiently via React Router loaders, avoiding unnecessary component rendering.

  **Example:**

  ```tsx
  import { defineModule, redirectToResource } from "@tailor-platform/app-shell";

  // Redirect to a resource instead of rendering a component
  export const dashboardModule = defineModule({
    path: "dashboard",
    component: redirectToResource("dashboard/overview"),
    resources: [overviewResource, analyticsResource],
  });

  // Also works for AppShell root component
  const appShellConfig: AppShellProps = {
    configurations: {
      rootComponent: redirectToResource("dashboard/overview"),
      modules: [dashboardModule],
    },
  };
  ```

  **Breaking Change**: `defaultResourceRedirectPath` prop in `defineModule` function is removed to keep API consistent. Use `redirectToResource` helper function instead.

### Patch Changes

* 35ae2eb: Promote Omakase-IMS Auth Patterns to AppShell

## 0.12.0

### Minor Changes

* 34715de: Add `rootComponent` prop in AppShell configuration

  The prop is expected to be used for overriding the root page in AppShell to show user-defined page like personalized dashboard, customized onboarding instruction, or something.

  ## Example

  ```tsx
  import {
    AppShell,
    AppShellProps,
    SidebarLayoutContainer,
  } from "@tailor-platform/app-shell";
  import { exampleModule } from "./resource/example";

  const App = () => {
    const appShellConfig: AppShellProps = {
      title: "AppShell",
      configurations: {
        modules: [exampleModule],

        /*
         * NEW: a prop to give a component to override the root page
         *
         * If nothing given, the default empty page would still be shown.
         * Use `useEffect` + `useNavigate` when initial page redirection is needed.
         */
        rootComponent: () => <div>Custom Root Component</div>,
      },
    };

    return (
      <AppShell {...appShellConfig}>
        <SidebarLayoutContainer />
      </AppShell>
    );
  };
  ```

### Patch Changes

* 58ed4a1: Add astw prefix to sr-only

## 0.11.1

### Patch Changes

* 5315366: Settings Modules

## 0.11.0

### Minor Changes

* 0c6312c: Module component can access module resources

### Patch Changes

* 225b4fd: Module component should be able to access the module's subResources

## 0.10.0

### Minor Changes

* af40df7: Add isLoading

### Patch Changes

* 675413d: Add isLoading to `BuiltinIdPAuthProvider`

## 0.9.4

### Patch Changes

* 93add79: Add logout function for BuiltinIdpAuthProvider

## 0.9.3

### Patch Changes

* f7a6fc6: Make redirect URI configurable in BuiltinIdPAuthProvider

## 0.9.2

### Patch Changes

* a33a031: Update packages

## 0.9.1

### Patch Changes

* 7fb8e40: - Force render on clientside to remove SSR console and node errors
  * Remove console error for nested buttons in DOM
  * Return `resolvedTheme` from `useTheme` hook to get the true theme to use when `system` theme is used

## 0.9.0

### Minor Changes

* 1ad6b3b: - Support module definition without a module-level component

  This can be done by providing a `defaultResourceRedirectPath` prop instead of a `component` in the `defineModule` call

## 0.8.2

### Patch Changes

* bbb2740: Support dynamic breadcrumb segment titles

## 0.8.1

### Patch Changes

* cbd605f: - Add `astw` prefix to tailwind classes to avoid global namespace clashes with consumer applications
  * Update padding around main content area

## 0.8.0

### Minor Changes

* b3c8e76: - Updates to Tailwind styles including classnames. `theme.css` is now exported for inclusion in consumer application tailwind `globals.css`
  * `defineResource`'s `meta.contentBorder` property now defaults to `false` if not provided
  * Removed the inset shadow for the sidebar-layout, and added a visual separator border to the sidebar
  * Move the sidebar icon inside the sidebar as per latest designs
  * Sidebar and Breadcrumb trail links now use react-router Link to ensure clientside navigation, if react-router context exists. (⚠️ Note this is untested in a non-react-router setting)

## 0.7.0

### Minor Changes

* 00ca998: Updates the style definition to bring over the class name and colours/other styles from frontend-platform-services: Console

  This file was used as a reference
  https://github.com/tailor-inc/platform-frontend-services/blob/main/apps/console/src/app/globals.css

  Todo in future: have these defined in just one place so we can use a centralised definition as base styles for multiple platforms

## 0.6.0

### Minor Changes

* c857b7e: Adds support for consumer applications to customize the UI

  * Customize icon for module:

    Optionally include an `icon` property within the defineModule meta property to render a custom icon, rather than using the default Table one.

    ```tsx
    defineModule({
    path: modulePath,
    component: ModulePageComponent,
    meta: {
        title: "Module Title",
        icon: <IconComponent />,
    },
    resources: [...],
    });
    ```

  * Make the content area border optional

    Removes the border around the content area if contentBorder is specified as `false`. (It defaults to true if unspecified)

    ```tsx
    defineResource({
      path: resourcePath,
      component: resourceComponent,
      meta: { contentBorder: false },
    });
    ```

  * Exports useTheme for consumers to get access to the theme being tracked by AppShell

    `import { useTheme } from "@tailor-platform/app-shell";`

## 0.5.0

### Minor Changes

* e9c56ae: Dark mode toggle
* 22fa03f: Design tweak: use built-in sidebar inset
* 54d8418: Fix breadcrumb labels

## 0.4.0

### Minor Changes

* 81cfb8c: Resource components can access title through props

  The value given to `meta.title` in a resource was rendered as the page title automatically, but this behaviour is removed by this change.

  Instead of that, the page title can be accessible through props given to the resoure component for more layout flexibility.

  ```tsx
  import {
    defineResource,
    ResourceComponentProps,
  } from "@tailor-platform/app-shell";

  const Page = (pageProps: ResourceComponentProps) => (
    <div>
      <h2 className="font-bold">{pageProps.title}</h2>
      <p className="pt-4">This is a page content</p>
    </div>
  );

  export const customPageResource = defineResource({
    path: "custom-page",
    component: Page,
    meta: {
      title: "Custom Page",
      category: "Examples",
    },
  });
  ```

* 2ce10bc: Module is a concept that groups multiple resources as a root.

  AppShell configuration accepts modules instead of resources with this change.

  ```diff
  <AppShell
    configurations={{
  -   resources: [someModule]
  +   modules: [someModule]
    }}
    {...otherProps}
  />
  ```

  Modules are defined with `defineModule` function, and it has `resources` property to give the child resources.

  ```tsx
  import { defineModule, defineResource } from "@tailor-platform/app-shell";

  const customPageModuleResource = defineResource({
    path: "sub",
    component: () => <p>This is a resource page</p>,
  });

  export const customPageModule = defineModule({
    path: "custom-page",
    component: () => <p>This is a module page</p>,
    resources: [customPageModuleResource],
  });
  ```

  A resource can also have multiple nested resources as deeply as needed recursively. `defineSubResource` function is oboleted.

  As of UI behaviour, the navigation shows only the first level of resources as sub items for the group that is a module.

## 0.3.0

### Minor Changes

* e724cd1: Upgrade tailwindcss to v4

## 0.2.0

### Minor Changes

* 22dc68c: Up until this release, AppShell did not support nested routes due to its limited routing implementation, but now it internally integrates react-router to support nested routes.

  It allows AppShell to be working as a standalone React application as well. A new app example that uses Vite instead of Next.js is added under `examples/vite-app`.

  AppShell is still usable as embedded Next.js route by levereging optional catch-all routes, but that's just an auxiliary interface.

  ### New functions

  To support nested routes, the following changes on functions to define resrouces are applied:

  #### `defineResource`

  A function to use the root-level resource that expects `title` and `category` as navigation metadata.

  ```tsx
  defineResource({
    path: "custom-page",
    component: () => <p>This is a custom page</p>,

    // Meta information
    meta: {
      title: "Custom Page",
      category: "Example",
    },
  });
  ```

  Behaviour on navigation UI: only the pages defined with `defineResource` function are the shown in navigation UI like sidebar items.

  #### `defineSubResource`

  A function to use the sub-level resource that expects only `title` as navigation metadata

  ```tsx
  defineResource({
    path: "custom-page",

    /*
     * (omitted...)
     */

    /*
     * Subresources works as the nested routes to the parent resource
     * Here defines the following two routes:
     * - /custom-page/sub-page
     * - /custom-page/sub-page/:id
     */
    subResources: [
      // Static route
      defineSubResource({
        path: "sub-page",
        component: () => (
          <p>This is a sub page</p>
        ),
        meta: {
          title: "Sub Page"
        }
      }),

      // Dynamic route
      defineSubResource({
        path: "sub-page/:id"
        component: () => (
          <p>This is is a sub page with dynamic parameter</p>
        )
      })
    ]
  })
  ```

  `defineSubResource` also accepts `subResources` as well to have nested children routes as many as you want.

## 0.1.0

### Minor Changes

* a9043b1: Initial release

---

---
url: https://docs.tailor.tech/app-shell/design-philosophy.md
description: The design principles and tradeoffs behind AppShell's architecture.
---

# Design Philosophy

AppShell makes deliberate tradeoffs — coupling over flexibility, convention over configuration, integration over composition. This page explains the reasoning behind those choices.

## Why a Framework, Not a Library Collection

ERP applications need authentication, routing, sidebar navigation, breadcrumbs, command palette, and permission guards. Each of these can be solved by an individual library. The hard part is not the individual pieces — it's keeping them in sync.

When you add a new page, the sidebar needs an entry. The breadcrumb trail needs updating. The command palette needs a new search result. The route guard needs to be evaluated. When you hide a page with a guard, it should disappear from *all* of those surfaces — not just the router.

With a library collection, you write and maintain this synchronization code yourself. With AppShell, a single `appShellPageProps` declaration on a page component drives all of these surfaces automatically:

```tsx
OrdersPage.appShellPageProps = {
  meta: {
    title: "Orders",
    icon: <OrdersIcon />,
  },
  guards: [authGuard],
};
```

The cost of this integration is not in the initial setup — it's in the ongoing maintenance. Every time you add, remove, or modify a page, a library-based approach requires manual updates across multiple surfaces. The bugs this produces — "guard is set to hidden but the command palette still shows it" — are silent and hard to test for. A framework eliminates this class of bugs entirely.

## Default Coupling, Opt-Out Exceptions

AppShell couples everything by default. A page appears in the sidebar, breadcrumbs, and command palette unless you explicitly opt out.

This is an intentional asymmetry. Opting out is expressed through the same mechanisms the framework already provides — for example, using a guard that returns `hidden` removes a page from the sidebar, breadcrumbs, and command palette all at once.

When you need finer control, AppShell provides a compositional layer. The sidebar, for instance, supports two modes: auto-generation (the default, driven entirely by module/resource definitions) and composition mode, where you build the sidebar structure explicitly using `SidebarItem`, `SidebarGroup`, and `SidebarSeparator` components. You can start with full auto-generation and gradually move to composition mode as your needs grow — without an all-or-nothing switch.

Opting *in* to coupling from a decoupled starting point — manually wiring sidebar entries, breadcrumb paths, and search results for every page — costs orders of magnitude more. The value of default coupling is not that exceptions never exist, but that expressing exceptions is trivial.

## Built for ERP, Not for Everything

AppShell targets applications where the majority of screens are CRUD — lists, detail views, create and edit forms. This is the reality of most ERP systems: even as they mature and add dashboards, approval workflows, and custom visualizations, the number of CRUD screens continues to grow (new master data entities, new transaction types).

For non-CRUD screens, AppShell stays out of the way. The framework manages the shell — routing, guards, layout, navigation — while page content is entirely yours. The ratio of "framework-managed" to "custom-built" shifts as a project matures, but the shell remains useful regardless of what's inside it.

If your application is primarily custom visualizations with little CRUD, or if you need a fully custom design system, AppShell's opinions will work against you. Use individual libraries instead.

## Opinionated UI, Not Headless

Frameworks like Refine and React Admin keep UI headless or pluggable to support any backend and any design. AppShell takes the opposite approach: it ships opinionated UI components — tables, forms, description cards, metric cards — that are designed for Tailor Platform ERP projects.

This tradeoff is viable because the scope is bounded. Tailor Platform projects agree upfront on what falls within standard UI and what requires custom implementation. AppShell optimizes for speed within that agreed boundary, rather than offering unbounded flexibility.

|                     | Refine / React Admin            | AppShell                                          |
| ------------------- | ------------------------------- | ------------------------------------------------- |
| **Backend**         | Any (data provider abstraction) | Tailor Platform                                   |
| **UI**              | Headless (bring your own)       | Opinionated (included)                            |
| **Navigation sync** | Routing only                    | Routing + sidebar + breadcrumbs + command palette |
| **Auth**            | Adapter-based (any IdP)         | Tailor Platform IdP direct                        |

## Vertical Integration as a Feature

AppShell is developed by the same team that builds Tailor Platform. This means:

* **Authentication evolves together.** When Tailor Platform changes its auth flow (e.g., adopting DPoP), AppShell ships the update. No waiting for a third-party adapter.
* **Breaking changes are coordinated.** Platform API changes and framework updates ship in lockstep, not as separate upgrade cycles.
* **Lock-in risk is scoped.** AppShell is already specific to Tailor Platform. The incremental lock-in from using it is minimal — you're not giving up backend portability you already don't have.

## Why a Framework, Not AI Skills

In an era of AI-assisted development, one might ask: why encode integration patterns in a framework when you could describe them in AI skill files or prompts?

The answer comes down to what guarantees correctness.

**Skills describe; frameworks enforce.** An AI skill can explain how to wire a sidebar entry to a route guard, but it cannot guarantee the wiring is correct. A framework, backed by TypeScript's type system, turns incorrect wiring into a compile-time error. The framework makes the *skill's job easier* — the skill only needs to teach "how to use AppShell," not "how to implement the integration that AppShell already handles."

**Integration crosses context boundaries.** Correctly implementing guard → routing → sidebar → command palette synchronization requires understanding all four systems simultaneously. AI skills work best when scoped to a single concern. Splitting integration logic across multiple skills risks losing cross-cutting consistency. An integration skill comprehensive enough to cover all the interactions essentially becomes a natural-language restatement of the framework — harder to maintain and impossible to type-check.

**Conventions reduce AI decision points.** File-based routing + `appShellPageProps` means "where does this page go?" and "what do I declare?" always have exactly one answer. This determinism is what lets AI agents work reliably across multiple projects without per-project context tuning.

AppShell's position: encode integration correctness in code and types. Use AI skills to teach *how to use* the framework, not to *replace* it.

---

---
url: https://docs.tailor.tech/app-shell/migrations.md
description: >-
  Breaking changes and required migration steps for AppShell upgrades, newest
  first
---

# Migrations

Every change that requires you to edit your application before or after upgrading, newest first.

This page is deliberately narrow. It is **not** a changelog — see [`packages/core/CHANGELOG.md`](./changelog) for the full release history including features and fixes. A change belongs here only if an app that does nothing will break, misbehave, or silently drift.

Each entry states which versions are affected, what breaks, how to detect it, and what to change. Entries stay here permanently; they are not pruned when they get old, because apps upgrade across arbitrary version gaps.

| Version       | Change                                                                                                                       |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| 1.12.0        | [`DateField` / `DatePicker` field chrome moved to `Field.Root`](#1120-datefield-datepicker-field-chrome-moved-to-fieldroot) |
| 1.11.0        | [React 19.2.7 and React Router v8 required](#1110-react-1927-and-react-router-v8-are-now-required)                           |
| 1.11.0        | [Non-modal `Sheet` renders no backdrop](#1110-non-modal-sheet-no-longer-renders-a-backdrop)                                  |
| 1.8.0         | [`stream` removed from `useAIChat()`](#180-stream-removed-from-useaichat)                                                    |
| 1.5.0 → 1.7.0 | [Remove the theme bridge workaround](#150-170-remove-the-theme-bridge-workaround)                                           |
| 1.5.0         | [`loader` removed from file-based pages](#150-loader-removed-from-file-based-page-definitions)                               |
| 1.3.0         | [Column inference and badge defaults changed](#130-column-inference-and-badge-defaults-changed)                              |
| 1.0.2         | [`Toaster` no longer accepts `richColors`](#102-toaster-no-longer-accepts-richcolors)                                        |
| before 1.0    | [Pre-1.0 breaking changes](#before-10)                                                                                       |

## 1.12.0: `DateField` / `DatePicker` field chrome moved to `Field.Root`

**Applies to:** apps passing `label`, `description`, `errorMessage`, or `hideTimeZone` to `DateField` or `DatePicker`.

The date controls now follow the same composition model as `Field`, `Select`, `Combobox`, and `Autocomplete`. Field chrome (`label`, `description`, `errorMessage`) has moved out of the control and into `Field.Root`. `hideTimeZone` is removed — it was accepted by the prop types but had no effect.

TypeScript will error on the removed props; delete them and compose with `Field.Root` instead.

Before:

```tsx
<DatePicker
  label="Delivery date"
  description="When should we ship your order?"
  minValue={today(getLocalTimeZone())}
  errorMessage={error}
  isInvalid={!!error}
/>
```

After:

```tsx
<Field.Root invalid={!!error}>
  <Field.Label>Delivery date</Field.Label>
  <DatePicker aria-label="Delivery date" minValue={today(getLocalTimeZone())} />
  <Field.Description>When should we ship your order?</Field.Description>
  <Field.Error match={!!error}>{error}</Field.Error>
</Field.Root>
```

`isInvalid` remains a top-level prop for externally-controlled invalid styling. Semantic date props (`isRequired`, `isDisabled`, `isReadOnly`, `minValue`, `maxValue`, `isDateUnavailable`) remain top-level and unchanged. Standalone usage still works with an accessible name:

```tsx
<DateField aria-label="Invoice date" />
```

## 1.11.0: React 19.2.7 and React Router v8 are now required

**Applies to:** every app upgrading to 1.11.0.

The minimum supported `react` and `react-dom` is raised to `19.2.7`, and AppShell moves to React Router v8. React 18 is no longer supported.

Upgrade `react` and `react-dom` to `>=19.2.7` in the same change. If your app imports from `react-router` directly, review the React Router v8 release notes for its own breaking changes — AppShell re-exports a subset (`useNavigate`, `useParams`, `useLocation`, and friends), and those are unaffected.

Note that 1.10.1 deliberately stayed on React Router v7 to pick up its security fixes while avoiding v8. Going 1.10.1 → 1.11.0 therefore crosses a router major.

## 1.11.0: non-modal `Sheet` no longer renders a backdrop

**Applies to:** apps using `<Sheet.Root modal={false}>`.

A non-modal sheet previously still rendered a backdrop, dimming and blocking the page behind it. It now omits the backdrop, which is what `modal={false}` implies. Nothing errors — the page behind simply stays undimmed and interactive.

If you relied on the dimming, drop `modal={false}` and use a modal sheet.

## 1.8.0: `stream` removed from `useAIChat()`

**Applies to:** apps passing `stream` to `useAIChat()`, or constructing an `AIGatewayChatRequest` by hand.

AppShell now selects streaming or JSON transport automatically from the model, so the option is gone. TypeScript errors on the removed property; delete it. There is no replacement.

## 1.5.0 → 1.7.0: remove the theme bridge workaround

**Applies to:** apps that pasted the `@theme inline` block, `@custom-variant dark`, and AppShell's palette into their entry CSS — the workaround for `styles` shipping without the Tailwind bridge.

**`styles` regained the bridge in 1.7.0.** On 1.5.0–1.6.1 the workaround is load-bearing, so upgrade to 1.7.0 or later *before* deleting any of it. Remove it earlier and every AppShell-token utility — `bg-card`, `bg-background`, `text-muted-foreground`, `border-border` — stops resolving, while `dark:` variants fall back to Tailwind's `prefers-color-scheme` default and stop tracking the `.dark` class.

From 1.7.0 the workaround is not merely redundant. It actively breaks dark mode, and the build succeeds with no warning:

* Your pasted `:root` and `.dark` blocks are unlayered, so they beat AppShell's layered default palette. Colours freeze at the values you copied, and any surface AppShell has added since has no dark value at all — so it renders light colours in dark mode: white text on white cards, unreadable disabled inputs.
* `@custom-variant dark (&:is(.dark *))` overrides AppShell's `&:where(.dark, .dark *)`. The `:is(.dark *)` form matches only *descendants* of `.dark`, so `dark:` utilities stop applying to the `.dark` element itself.

### Removing it

Delete from your entry CSS:

* the `@theme inline { … }` block,
* the `@custom-variant dark (…)` rule,
* every `:root` and `.dark` block copied from AppShell's palette — **all** of it, including the `*-foreground` pairs, `--status-*`, `--alert-*`, `--sidebar-*` and `--semantic-shadow-*`. The foregrounds are what leave text white on white, so a partial deletion reproduces the bug.
* any `@import "@tailor-platform/app-shell/theme.css"` (a no-op shim since 1.6.0, kept only so older apps keep building).

To find it, search every CSS file the app loads — not just the entry point, since `app/` and `styles/` are as common as `src/`:

```bash
grep -rnE "@theme inline|@custom-variant|app-shell/theme\.css|--(card|popover|muted|sidebar|destructive|accent)(-foreground)?:" --include="*.css" --exclude-dir=node_modules --exclude-dir=dist --exclude-dir=.next .
```

Excluding `node_modules` matters: AppShell's own palette files declare these tokens too, and they must not be touched. In your own CSS, hits are either the workaround, which goes, or deliberate overrides, which should take the `:root` / `:root.dark` form described in [Overriding tokens](concepts/styling-theming.md#overriding-tokens).

What remains is short — [`examples/vite-app/src/index.css`](https://github.com/tailor-platform/app-shell/blob/main/examples/vite-app/src/index.css) is a working reference for the shape (it also imports a branded palette, which is optional):

```css
@import "tailwindcss";
@import "@tailor-platform/app-shell/styles";

html,
body {
  margin: 0;
  padding: 0;
}
```

### Verifying

Toggle dark mode and confirm a real surface changes: inspect a `Card` and watch its computed `background-color` go from `rgb(255, 255, 255)` to `rgb(23, 23, 23)` on the default palette.

Reading the token directly also works — `getComputedStyle(document.documentElement).getPropertyValue("--card")` returns the winning declaration, so a stale copy shows up as its own value. Just compare against the authored notation: AppShell writes `rgba(23, 23, 23, 1)`, not `#171717`, and the computed value preserves that form.

## 1.5.0: `loader` removed from file-based page definitions

**Applies to:** file-based routing apps that set `loader` in `Page.appShellPageProps`.

`loader` was an incomplete API exposed by accident, and `guards` is now the single source of page-level route behaviour. Move any access checks into a guard, and any data loading into the page component or your data layer.

## 1.3.0: column inference and badge defaults changed

**Applies to:** apps using `inferColumns()`, or `DataTable`'s status badges.

Two changes that alter rendering without any error:

* `inferColumns()` no longer sets a default `render`. A column with neither an explicit `type` nor `render` now displays `—` for null and empty values, matching typed-column behaviour.
* Badge variant resolution moved into a shared helper whose default is `outline-neutral`. `DataTable` previously defaulted to `neutral`, so unstyled status badges change appearance.

Set `type` or `render` explicitly on any column whose previous rendering you want back, and pass an explicit variant where the old badge styling mattered. `BadgeVariantType` is deprecated in favour of `BadgeVariant`.

## 1.0.2: `Toaster` no longer accepts `richColors`

**Applies to:** apps passing `richColors` to `<Toaster>`.

The prop is removed, and toasts no longer colour-code the success, error, warning, and info variants. TypeScript errors on the prop; delete it.

## Before 1.0

Pre-1.0 releases changed the public API often, mostly around authentication and routing. If you are upgrading from a 0.x version, work through these in order — several supersede each other, so applying them out of sequence will not land you in the right place.

Each is summarised here; [`packages/core/CHANGELOG.md`](./changelog) carries the full before/after code for every one.

| Version | Change                                                                                                                                                                                                                                                                                                                                                                             |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 0.33.0  | `AsyncFetcherFn` receives `string \| null` instead of `string`. It is called with `null` when the user has typed nothing — return initial items, or an empty array to show nothing until they type.                                                                                                                                                                                |
| 0.28.0  | `EnhancedAuthClient.getAuthHeadersForQuery()` removed. Pass `fetch: authClient.fetch` to your GraphQL client instead; it handles DPoP proofs and token refresh transparently.                                                                                                                                                                                                      |
| 0.27.0  | Module-level `guards` and `loaders` no longer cascade to child resources — declare them on each resource or page. A module without a `component` no longer auto-redirects to its first visible resource and must declare `guards`, or it throws at runtime.                                                                                                                        |
| 0.26.0  | Authentication moved to `@tailor-platform/auth-public-client` with DPoP. `AuthProvider` requires a `client` from `createAuthClient`, `apiEndpoint` is gone, `useAuth` returns its fields directly rather than under `authState`, and built-in user fetching (`meQuery`, `AuthState.user`, `DefaultUser`, `AuthRegister`) is removed — fetch the user with your own GraphQL client. |
| 0.24.0  | `accessControl` replaced by the `guards` array on `defineModule`/`defineResource`. `RedirectConfig` and `redirectToResource` removed — use `guards` with `redirectTo()`.                                                                                                                                                                                                           |
| 0.19.0  | `BuiltinIdPAuthProvider` → `AuthProvider`, `useBuiltinIdpAuth` → `useAuth`. The `buildAuthorizationUrl`, `exchangeCodeForToken`, `prepareLogin`, and `handleOAuthCallback` utilities are no longer exported.                                                                                                                                                                       |
| 0.13.0  | `defaultResourceRedirectPath` removed from `defineModule` in favour of a `redirectToResource` helper — which 0.24.0 then removed in turn. Coming from 0.13.0 or earlier, go straight to the 0.24.0 form: `guards` with `redirectTo()`.                                                                                                                                             |
| 0.4.0   | `meta.title` no longer renders the page title automatically. The title is passed to the resource component via props (`ResourceComponentProps`); render it yourself.                                                                                                                                                                                                               |

---

---
url: https://docs.tailor.tech/app-shell/concepts/authentication.md
description: >-
  Set up OAuth2/OIDC authentication with Tailor Platform's Auth service using
  the AuthProvider component
---

# Authentication

AppShell provides built-in OAuth2/OIDC authentication through the `AuthProvider` component, which integrates seamlessly with Tailor Platform's Auth service. The provider supports any IdP configured in your Tailor Platform application (built-in IdP, Google, Okta, Auth0, etc.).

## Quick Start

First, create an auth client, then wrap your app with `AuthProvider`:

```tsx
import {
  createAuthClient,
  AuthProvider,
  AppShell,
  SidebarLayout,
} from "@tailor-platform/app-shell";

const authClient = createAuthClient({
  clientId: CLIENT_ID,
  appUri: TAILOR_PLATFORM_URL,
});

const App = () => (
  <AuthProvider client={authClient} autoLogin={true} guardComponent={() => <LoadingScreen />}>
    <AppShell modules={modules}>
      <SidebarLayout />
    </AppShell>
  </AuthProvider>
);
```

Find the above values in Tailor Console:

* **Tailor Platform URL** (`appUri`): Your application's base URL
  * Obtained from the Application Overview screen in Tailor Platform
  * Use the domain portion of the 'Accessing the API endpoint of this application' setting
  * Example: `"https://xyz.erp.dev"` (no `/query` suffix needed)

* **Client ID** (`clientId`): Authentication client identifier
  * Found in Application > Auth screen in your Tailor Platform console

The above code will:

* Automatically redirect unauthenticated users to the login page (if `autoLogin` is true)
* Show the `guardComponent` while loading or when unauthenticated
* Handle token management and session persistence automatically

## Authentication Hook

Use the `useAuth` hook to access authentication state and methods:

```tsx
import { useAuth } from "@tailor-platform/app-shell";

const UserProfile = () => {
  const { isReady, isAuthenticated, login, logout } = useAuth();

  if (!isReady) {
    return <div>Loading...</div>;
  }

  if (!isAuthenticated) {
    return <button onClick={login}>Sign In</button>;
  }

  return <button onClick={logout}>Sign Out</button>;
};
```

### Return Value

| Property          | Type                       | Description                                            |
| ----------------- | -------------------------- | ------------------------------------------------------ |
| `isAuthenticated` | `boolean`                  | Whether the user is currently authenticated            |
| `isReady`         | `boolean`                  | Whether the initial authentication check has completed |
| `error`           | `string \| null`           | Error message if authentication failed                 |
| `login`           | `() => Promise<void>`      | Initiates the login/redirect flow                      |
| `logout`          | `() => Promise<void>`      | Clears tokens and ends the session                     |
| `checkAuthStatus` | `() => Promise<AuthState>` | Re-checks auth status (always makes a network request) |

### Suspense-Compatible Hook

Use `useAuthSuspense` when you want React Suspense to handle the loading state:

```tsx
import { Suspense } from "react";
import { useAuthSuspense } from "@tailor-platform/app-shell";

function App() {
  return (
    <AuthProvider client={authClient}>
      <Suspense fallback={<div>Loading authentication...</div>}>
        <ProtectedContent />
      </Suspense>
    </AuthProvider>
  );
}

function ProtectedContent() {
  // isReady is guaranteed to be true here — Suspense handles the loading state
  const { isAuthenticated, login, logout } = useAuthSuspense();

  if (!isAuthenticated) {
    return <button onClick={login}>Log In</button>;
  }

  return <button onClick={logout}>Log Out</button>;
}
```

## Auth Client

Use `createAuthClient` to create an authentication client that you pass to `AuthProvider`. The client handles token management and provides an authenticated `fetch` method for use with GraphQL clients.

```tsx
import { createAuthClient } from "@tailor-platform/app-shell";

const authClient = createAuthClient({
  clientId: "your-client-id",
  appUri: "https://xyz.erp.dev",
});
```

### Using `authClient.fetch` with a GraphQL Client

Pass `authClient.fetch` directly to your GraphQL client (e.g., urql). It transparently handles DPoP proof generation and token refresh on every request. If the server rejects the grant outright, it ends the session rather than replaying a dead token — see [Session expiry](#session-expiry):

```tsx
import { createAuthClient, AuthProvider } from "@tailor-platform/app-shell";
import { createClient, Provider } from "urql";

const authClient = createAuthClient({
  clientId: "your-client-id",
  appUri: "https://xyz.erp.dev",
});

const urqlClient = createClient({
  url: `${authClient.getAppUri()}/query`,
  fetch: authClient.fetch,
});

function App() {
  return (
    <AuthProvider client={authClient} autoLogin={true}>
      <Provider value={urqlClient}>
        <YourAppComponents />
      </Provider>
    </AuthProvider>
  );
}
```

### Using `createAIGatewayClient` with AI Gateway

`createAIGatewayClient` reuses the same authenticated fetch path as the rest of AppShell. Requests go through `authClient.fetch`, so DPoP proof generation and token refresh stay in the auth layer.

```tsx
import { createAuthClient, createAIGatewayClient, useAIChat } from "@tailor-platform/app-shell";

const authClient = createAuthClient({
  clientId: "your-client-id",
  appUri: "https://xyz.erp.dev",
});

const aiClient = createAIGatewayClient({
  gatewayUri: "https://your-ai-gateway.example.com",
  authClient,
});

function ChatScreen() {
  const { messages, sendMessage, status, stop } = useAIChat({
    client: aiClient,
    model: "gpt-5-mini",
  });

  return (
    <div>
      {messages.map((message) => (
        <div key={message.id}>
          {message.role}: {message.content}
        </div>
      ))}

      <button onClick={() => void sendMessage("Hello")}>Send</button>
      <button onClick={stop} disabled={status !== "submitted" && status !== "streaming"}>
        Stop
      </button>
    </div>
  );
}
```

### `AuthClientConfig`

| Property      | Type     | Required | Description                                                |
| ------------- | -------- | -------- | ---------------------------------------------------------- |
| `clientId`    | `string` | Yes      | OAuth2 client ID from Tailor Platform console              |
| `appUri`      | `string` | Yes      | Your Tailor Platform application URL                       |
| `redirectUri` | `string` | No       | OAuth2 redirect URI (defaults to `window.location.origin`) |

### `EnhancedAuthClient` Methods

| Method / Property | Type           | Description                                                                                                      |
| ----------------- | -------------- | ---------------------------------------------------------------------------------------------------------------- |
| `getAppUri()`     | `() => string` | Returns the `appUri` used to create this client                                                                  |
| `fetch`           | `typeof fetch` | Authenticated fetch with built-in DPoP proof generation, token refresh, and session teardown on a rejected grant |

## `AuthProvider` Props

| Prop             | Type                    | Required | Description                                           |
| ---------------- | ----------------------- | -------- | ----------------------------------------------------- |
| `client`         | `EnhancedAuthClient`    | Yes      | Auth client created with `createAuthClient`           |
| `autoLogin`      | `boolean`               | No       | Automatically redirect unauthenticated users to login |
| `guardComponent` | `() => React.ReactNode` | No       | Rendered while loading or when not authenticated      |

## When the callback fails

A sign-in that comes back from the authorization server unsuccessfully — the user declined, the client is not permitted, the exchange failed — leaves `isAuthenticated` false with the reason on `useAuth().error`. The callback parameters are cleaned out of the URL on every outcome (since `auth-public-client` 0.6.1), preserving unrelated query parameters, the hash, and the router's history state.

With `autoLogin`, a failure that looks recoverable is retried once automatically. Beyond that, and for any refusal the authorization server issues explicitly, AppShell stops: sending the user straight back would ask the same question, get the same answer, and loop.

That makes the guard the place where a failed sign-in becomes visible. A guard that only ever renders a spinner will spin indefinitely in this case, so render the error and offer a way out:

```tsx
const AuthGate = () => {
  const { isReady, error, login } = useAuth();

  if (error) {
    return (
      <div>
        <p>Sign-in failed: {error}</p>
        <button onClick={() => login()}>Try again</button>
      </div>
    );
  }

  return isReady ? <LoginPrompt /> : <LoadingScreen />;
};
```

## Integration with AppShell

The authentication provider works seamlessly with AppShell's data layer, automatically handling:

* OAuth2 token management
* Authenticated fetch with DPoP proof generation
* Session persistence and token refresh
* Session teardown when the server rejects the grant
* Automatic redirects for protected routes (via `autoLogin`)

OAuth callback parameters (`code`, `state`) are automatically cleaned from the URL after a successful login — no dedicated callback page is needed.

## Session expiry

Access tokens are refreshed transparently, so a session normally outlives individual token lifetimes without the app doing anything.

When a refresh cannot succeed — the refresh token has expired, been revoked, or is otherwise rejected by the token endpoint — the auth client ends the session instead of retrying indefinitely. It clears stored tokens, sets `isAuthenticated` to `false`, and emits `logout` followed by `auth_state_changed`.

What the user sees follows from the props you already pass:

* With `autoLogin`, `AuthProvider` redirects to sign-in.
* With `guardComponent`, the guard renders in place of your app.
* With neither, `useAuth().isAuthenticated` flips to `false` and your own UI decides.

Not every failed refresh ends the session. A request timeout, a network failure, and a plain 5xx from the token endpoint all leave it intact, so a dropped connection does not sign users out.

The line is drawn on the shape of the response, not on how transient the underlying cause is. Any rejection the token endpoint returns as a 4xx carrying an `error` code ends the session — the sole exception is `use_dpop_nonce`. A server that reports overload as `400 {"error":"server_error"}` or `400 {"error":"temporarily_unavailable"}` will therefore sign users out, as will a 5xx that carries a `WWW-Authenticate` header. If you operate the token endpoint, prefer a bare 5xx for conditions you want treated as retryable.

To react to teardown yourself — clearing app-level caches, for instance — subscribe to the client's events:

```tsx
useEffect(() => {
  return authClient.addEventListener((event) => {
    if (event.type === "logout") {
      clearAppCaches();
    }
  });
}, [authClient]);
```

---

---
url: https://docs.tailor.tech/app-shell/concepts/file-based-routing.md
description: >-
  Define pages via directory structure using the Vite plugin instead of explicit
  module configuration
---

# File-Based Routing

File-based routing allows you to define pages by simply placing components in a directory structure, eliminating the need for explicit `defineModule()` and `defineResource()` calls.

## Overview

Instead of manually assembling module/resource hierarchies, you define pages as files in a `pages/` directory. The path is automatically derived from the directory structure.

```
src/pages/
├── page.tsx                  # / (root path)
├── purchasing/
│   ├── page.tsx              # /purchasing
│   └── orders/
│       ├── page.tsx          # /purchasing/orders
│       └── [id]/
│           └── page.tsx      # /purchasing/orders/:id
└── (admin)/                  # Grouping (not included in path)
    └── settings/
        └── page.tsx          # /settings
```

Directories **without** a `page.tsx` still contribute a path segment — navigating to that path returns a 404 while their children remain accessible:

```
src/pages/
├── admin/
│   ├── users/
│   │   └── page.tsx   # /admin/users → renders page
│   └── roles/
│       └── page.tsx   # /admin/roles → renders page
│   # no page.tsx for /admin → 404
```

Guards defined on a `page.tsx` apply to that exact path. Directories without `page.tsx` do not support guards — add guards to the individual child pages instead.

## Setup

### 1. Configure Vite Plugin

```typescript
// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { appShellRoutes } from "@tailor-platform/app-shell/vite-plugin";

export default defineConfig({
  plugins: [
    react(),
    appShellRoutes({
      entrypoint: "src/App.tsx", // recommended
    }),
  ],
});
```

#### Plugin Options

| Option                | Type                            | Default       | Description                                                                          |
| --------------------- | ------------------------------- | ------------- | ------------------------------------------------------------------------------------ |
| `pagesDir`            | `string`                        | `"src/pages"` | Directory containing page files                                                      |
| `logLevel`            | `"info" \| "debug" \| "off"`    | `"info"`      | Log level for plugin output                                                          |
| `entrypoint`          | `string`                        | `undefined`   | File that renders the AppShell component (relative to project root). See note below. |
| `generateTypedRoutes` | `boolean \| { output: string }` | `false`       | Generate a TypeScript file with type-safe route definitions                          |

> **`entrypoint` (recommended):** When specified, only imports from this file are intercepted and replaced with the pages-injected AppShell. All other files — including page components — import directly from the real package. Without this option, all user-code imports of `@tailor-platform/app-shell` are intercepted, which can cause TDZ (Temporal Dead Zone) errors in page components that also import from the package.

### 2. Use AppShell (No Configuration Needed)

```tsx
// App.tsx
import { AppShell, SidebarLayout, DefaultSidebar } from "@tailor-platform/app-shell";

const App = () => {
  return (
    <AppShell title="My App">
      <SidebarLayout sidebar={<DefaultSidebar />} />
    </AppShell>
  );
};
```

Pages are automatically discovered and injected—no `modules` prop required!

## Page Components

### Minimal Example

The simplest page is just a default-exported component:

```tsx
// src/pages/about/page.tsx
export default () => <div>About</div>;
```

### Full Example

Use `appShellPageProps` static field to configure page metadata and guards:

```tsx
// src/pages/dashboard/page.tsx
import type { AppShellPageProps } from "@tailor-platform/app-shell";
import { authGuard } from "../guards";
import { DashboardIcon } from "../icons";

const DashboardPage = () => {
  return <div>Dashboard Content</div>;
};

DashboardPage.appShellPageProps = {
  meta: {
    title: "Dashboard",
    icon: <DashboardIcon />,
  },
  guards: [authGuard],
} satisfies AppShellPageProps;

export default DashboardPage;
```

### AppShellPageProps Type

```typescript
type AppShellPageProps = {
  meta?: {
    title?: LocalizedString;
    icon?: ReactNode;
    breadcrumbTitle?: string | ((segment: string) => string);
  };
  guards?: Guard[];
};
```

## Path Conventions

| Directory Name | Converts To | Description                                    |
| -------------- | ----------- | ---------------------------------------------- |
| `orders`       | `orders`    | Static segment                                 |
| `[id]`         | `:id`       | Dynamic parameter                              |
| `[...slug]`    | `*slug`     | Catch-all — matches zero or more path segments |
| `(group)`      | (excluded)  | Grouping only (not in path)                    |
| `_lib`         | (ignored)   | Not routed (for shared logic)                  |

### Examples

```
src/pages/
├── users/
│   ├── page.tsx              # /users
│   └── [userId]/
│       └── page.tsx          # /users/:userId
├── (marketing)/
│   ├── campaigns/
│   │   └── page.tsx          # /campaigns (not /marketing/campaigns)
│   └── analytics/
│       └── page.tsx          # /analytics
└── _utils/
    └── helpers.ts            # Not routed (shared utilities)
```

## Guards

Guards are **not** automatically inherited from parent pages. Each page must explicitly define its own guards:

```tsx
// /dashboard/page.tsx
DashboardPage.appShellPageProps = {
  guards: [authGuard],
} satisfies AppShellPageProps;

// /dashboard/admin/page.tsx — must include authGuard explicitly
AdminPage.appShellPageProps = {
  guards: [authGuard, adminGuard],
} satisfies AppShellPageProps;
```

To share common guards across pages, compose them from a shared module:

```tsx
// src/guards.ts
export const requireAuth = [authGuard];
export const requireAdmin = [authGuard, adminGuard];

// src/pages/dashboard/orders/page.tsx
import { requireAuth } from "@/guards";

OrdersPage.appShellPageProps = {
  guards: [...requireAuth],
} satisfies AppShellPageProps;
```

## Typed Routes

Enable `generateTypedRoutes` in the Vite plugin to generate type-safe route helpers:

```typescript
// vite.config.ts
appShellRoutes({
  generateTypedRoutes: true,
});
```

This generates `src/routes.generated.ts` with a `paths` helper:

```tsx
import { paths } from './routes.generated';
import { Link } from '@tailor-platform/app-shell';

// Static routes
<Link to={paths.for("/dashboard")}>Dashboard</Link>

// Dynamic routes - params are type-checked
<Link to={paths.for("/dashboard/orders/:id", { id: orderId })}>Order</Link>

// TypeScript catches errors:
paths.for("/dashboard/orders/:id"); // Error: missing 'id'
paths.for("/invalid");              // Error: route doesn't exist
```

## Comparison with Legacy API

### Before: Explicit Hierarchy Assembly

```tsx
const orderDetailResource = defineResource({ path: ":id", component: OrderDetail });
const ordersResource = defineResource({
  path: "orders",
  component: OrdersList,
  subResources: [orderDetailResource],
});
const purchasingModule = defineModule({
  path: "purchasing",
  resources: [ordersResource],
});

<AppShell modules={[purchasingModule]} />;
```

### After: File-Based Pages

```tsx
// src/pages/purchasing/orders/[id]/page.tsx
const OrderDetailPage = () => <div>Order Detail</div>;
OrderDetailPage.appShellPageProps = {
  meta: { title: "Order Detail" },
} satisfies AppShellPageProps;
export default OrderDetailPage;
```

```tsx
// App.tsx - No configuration needed
<AppShell title="My App">
  <SidebarLayout sidebar={<DefaultSidebar />} />
</AppShell>
```

### Concept Mapping

| Legacy API              | File-Based                      | Notes                         |
| ----------------------- | ------------------------------- | ----------------------------- |
| `Module`                | —                               | First-level directory         |
| `Resource`              | —                               | Directory structure           |
| `defineModule()`        | —                               | Not needed                    |
| `defineResource()`      | —                               | Not needed                    |
| `path` property         | Directory name                  | Auto-derived                  |
| `component` property    | `page.tsx` default export       | File convention               |
| `meta` property         | `Page.appShellPageProps.meta`   | Static field                  |
| `guards` property       | `Page.appShellPageProps.guards` | Static field (no inheritance) |
| `subResources` property | Subdirectories                  | Auto-derived                  |

## Compatibility

File-based pages and explicit `modules` prop are **mutually exclusive**.

### Usage Patterns

```tsx
// ✅ Pattern 1: File-based pages with plugin (recommended)
// vite.config.ts has plugin configured
<AppShell title="My App">
  <SidebarLayout sidebar={<DefaultSidebar />} />
</AppShell>

// ✅ Pattern 2: Explicit modules without plugin (legacy)
<AppShell modules={[myModule]} title="My App">
  <SidebarLayout sidebar={<DefaultSidebar />} />
</AppShell>

// ✅ Pattern 3: Plugin enabled + modules prop (modules takes precedence)
// Even with plugin enabled, modules prop is used when provided
<AppShell modules={[myModule]} title="My App">
  <SidebarLayout sidebar={<DefaultSidebar />} />
</AppShell>

// ❌ Pattern 4: No plugin + no modules (runtime error)
<AppShell title="My App">
  {/* → Runtime error: No routes configured */}
</AppShell>
```

## Migration Guide

To migrate from `defineModule`/`defineResource` to file-based routing:

1. **Add Vite Plugin**

   ```typescript
   // vite.config.ts
   import { appShellRoutes } from "@tailor-platform/app-shell/vite-plugin";

   export default defineConfig({
     plugins: [react(), appShellRoutes({ entrypoint: "src/App.tsx" })],
   });
   ```

2. **Create pages directory structure**
   * Map each module to a top-level directory
   * Map each resource to a subdirectory with `page.tsx`
   * Use `[param]` for dynamic segments

3. **Move component and metadata**

   ```tsx
   // Before: defineResource({ path: "orders", component: Orders, meta: {...} })

   // After: src/pages/orders/page.tsx
   const OrdersPage = () => <Orders />;
   OrdersPage.appShellPageProps = { meta: {...} };
   export default OrdersPage;
   ```

4. **Remove `modules` prop** from `<AppShell>` once all pages are migrated

---

---
url: https://docs.tailor.tech/app-shell/concepts/modules-and-resources.md
description: >-
  Learn how to structure your AppShell application using modules and resources
  for automatic routing, navigation, and breadcrumbs
---

# Modules and Resources

AppShell renders sidebar navigation, breadcrumbs, and handles routing based on a structured configuration of modules and resources (and sub-resources, sub-sub-resources, and so on).

Modules and Resources both share core interface. Of interest:

* `path: string` - the path segment
* `component: (props: ResourceComponentProps) => ReactNode` - the component to render when the router navigates to that module/resource (optional — omitting it causes the path to return a 404 while child routes remain accessible)
* `guards?: Guard[]` - optional array of guard functions to control access based on permissions or feature flags

A trivial `modules` example:

```tsx
import { defineModule, defineResource, pass, hidden } from "@tailor-platform/app-shell";

const appShellPropModule = [
  defineModule({
    path: "purchasing",
    component: PurchasingLandingPage,
    resources: [
      defineResource({
        path: "orders",
        component: OrdersPage,
        subResources: [
          defineResource({
            path: ":id",
            component: OrderDetailPage,
          }),
        ],
      }),
      defineResource({
        path: "invoices",
        component: PurchaseInvoicesPage,
        // ...
      }),
    ],
  }),
  defineModule({
    path: "sales",
    component: SalesLandingPage,
    resources: [
      defineResource({
        path: "invoices",
        component: SalesInvoicesPage,
        // ...
      }),
      // ...
    ],
  }),
  // Module without component - /dashboard returns 404, child routes remain accessible
  defineModule({
    path: "dashboard",
    resources: [
      defineResource({
        path: "overview",
        component: DashboardOverview,
      }),
      defineResource({
        path: "analytics",
        component: DashboardAnalytics,
      }),
    ],
  }),
  // Module with guards for access control
  defineModule({
    path: "reports",
    component: ReportsPage,
    resources: [reportsListResource],
    guards: [
      async ({ context, signal }) => {
        const ok = await fetch("/api/me/permissions?scope=reports", {
          signal,
        }).then((r) => r.ok);
        return ok ? pass() : hidden();
      },
    ],
  }),
];
```

Produces the following navigation menu:

```
› Purchasing
  - Orders
  - Invoices
› Sales
  - Invoices
  ...
› Reports  (only visible if user has reports permission)
```

Modules show as top-level menu items and resources are the sub-menu items. Sub-resources do not show up on the side navigation menu, but will be available via other navigation and show in breadcrumbs.

In the example above, clicking the 'Orders' menu item above will take you to `/{basePath}/purchasing/orders` and render the OrdersPage page. If you browse, either by direct request or via client-side navigation to `/{basePath}/purchasing/orders/1234`, AppShell will render OrderDetailPage with 'id' available via useParams

Providing a `component` for a Module is optional. If omitted, navigating directly to the module path returns a 404 response while its child resources remain fully accessible. This is useful when a path segment exists solely to group child routes under a shared URL prefix with no landing page of its own.

When a module has no `component`, its breadcrumb segment is rendered as plain non-clickable text (instead of a link), preventing navigation to a page that does not exist.

The same applies to resources: a `defineResource()` call without a `component` makes the resource path itself return 404 while its `subResources` remain accessible.

Guards on component-less modules and resources execute correctly. For example, a `redirectTo()` guard will fire as expected. If all guards return `pass()`, the route falls back to a 404 (since there is no component to render).

> Read more about [client-side navigation](routing-navigation) in AppShell apps

## Route Guards

Both modules and resources support `guards` - an array of functions that control access based on permissions, feature flags, or any other criteria. Guards are executed in order and provide:

* Composability: Combine multiple guards for complex access logic
* Reusability: Share common guards across routes
* Semantic constraints: Clear `pass()`, `hidden()`, or `redirectTo()` results

See the [Guards documentation](../api/guards/overview) for full details.

### Guard Examples

**Permission-based access:**

```tsx
import { defineModule, pass, hidden } from "@tailor-platform/app-shell";

const reportsModule = defineModule({
  path: "reports",
  component: ReportsPage,
  resources: [reportsListResource],
  guards: [
    async ({ context }) => {
      const ok = await fetch("/api/me/permissions?scope=reports").then((r) => r.ok);
      return ok ? pass() : hidden();
    },
  ],
});
```

**Feature flag based:**

```tsx
import { pass, hidden } from "@tailor-platform/app-shell";

const betaFeaturesModule = defineModule({
  path: "beta",
  component: BetaFeaturesPage,
  resources: [newFeatureResource],
  guards: [
    async ({ context }) => {
      const enabled = await checkFeatureFlag("beta-features");
      return enabled ? pass() : hidden();
    },
  ],
});
```

**Tenant tier based:**

```tsx
import { pass, hidden } from "@tailor-platform/app-shell";

const billingModule = defineModule({
  path: "billing",
  component: BillingPage,
  resources: [billingResources],
  guards: [
    async ({ context }) => {
      const plan = await getCurrentTenantPlan();
      return plan === "enterprise" ? pass() : hidden();
    },
  ],
});
```

**Resource-level guards:**

```tsx
import { pass, hidden } from "@tailor-platform/app-shell";

defineResource({
  path: "admin-settings",
  component: AdminSettingsPage,
  guards: [
    async ({ context }) => {
      const user = await getCurrentUser();
      return user.role === "admin" ? pass() : hidden();
    },
  ],
});
```

**Reusable guards:**

```tsx
import { type Guard, pass, hidden, redirectTo } from "@tailor-platform/app-shell";

// Define reusable guards
const requireAuth: Guard = ({ context }) => {
  if (!context.currentUser) {
    return redirectTo("/login");
  }
  return pass();
};

const requireAdmin: Guard = ({ context }) => {
  if (context.currentUser?.role !== "admin") {
    return hidden();
  }
  return pass();
};

// Use in multiple resources
defineResource({
  path: "admin/users",
  component: AdminUsersPage,
  guards: [requireAuth, requireAdmin],
});
```

When a module or resource is hidden via guards, it will:

* Not appear in navigation menus
* Not be accessible via direct URL navigation
* Not appear in CommandPalette search results

---

---
url: https://docs.tailor.tech/app-shell/concepts/routing-navigation.md
description: >-
  Learn how to navigate between pages using React Router hooks and components
  re-exported from AppShell
---

# Routing and Navigation

AppShell owns the router. It builds the route tree from your modules and resources, constructs the router, and renders the `RouterProvider` itself. Your pages render *inside* that router.

## Your app should not depend on `react-router`

**Do not add `react-router` to your application's dependencies.** Import everything you need for routing from `@tailor-platform/app-shell` instead.

This is not a style preference — it is what keeps your app working:

```tsx
// ✅ Do this
import { useNavigate, Link } from "@tailor-platform/app-shell";

// ❌ Not this
import { useNavigate, Link } from "react-router";
```

React Router keeps its state in React context, and context identity belongs to a *module instance*. If your app resolves its own copy of `react-router` — a different version to the one AppShell resolved — the bundle ends up with two copies and therefore two unrelated routers. AppShell's own navigation keeps working, so the app looks fine at a glance, while every hook and component you imported yourself throws:

```
useNavigate() may be used only in the context of a <Router> component.
```

TypeScript cannot see this, so the build passes and the failure only appears at runtime. Under pnpm, an app that has not declared `react-router` cannot import it at all, which is the intended outcome: the rule enforces itself.

If you already have a direct dependency, the fix is to delete it and change the import paths. The APIs are identical — they are the same functions, re-exported.

## What AppShell gives you

Everything you need to *consume* the router AppShell created:

**Location and route matching**

* `useLocation` — the current location object
* `useParams` — dynamic route parameters
* `useSearchParams` — read and update the query string
* `useMatch` — test whether a path matches the current location
* `useResolvedPath` — resolve a relative path against the current route

**Navigating**

* `useNavigate` — navigate programmatically
* `useNavigation` — the in-flight navigation, for pending UI
* `Link` — a client-side link
* `NavLink` — a link that knows when it is active, for nav menus
* `Navigate` — redirect declaratively during render

**Guarding unsaved work**

* `useBlocker` — intercept an in-app navigation away from unsaved changes
* `useBeforeUnload` — the same for closing or reloading the tab

**Errors**

* `useRouteError` — read the error inside an error boundary

Types come with them: `Location`, `NavigateFunction`, `NavigateOptions`, `To`, `Params`, `PathMatch`, `LinkProps`, `NavLinkProps`, `Navigation`, `Blocker`, and `BlockerFunction`.

### What it deliberately does not give you

**Router construction** — `createBrowserRouter`, `RouterProvider`, `BrowserRouter`, `MemoryRouter`, `Routes`, `Route`. AppShell builds the router from your modules and resources; a second one nested inside it is the bug this page is about. To control routing in tests, use the [`/testing` entry point](#testing) rather than building your own router.

**Data-router APIs** — `useLoaderData`, `Form`, `useSubmit`, `useFetcher`, `useActionData`, `useRevalidator`. AppShell does not wire up React Router's data layer, so these have nothing to talk to. Load data in the page component or your own data layer. (AppShell exports its own `Form`, which is part of the [form system](../components/form) and unrelated to React Router's.)

Missing something you need? Ask for it to be added here rather than adding a direct `react-router` dependency — that is the trade this rule makes, and requests are the mechanism that keeps it honest.

### One caveat

A third-party library that itself depends on `react-router` can still pull in a second copy. That is rare, and outside what AppShell can control. If routing starts throwing the error above, look for a duplicate — under pnpm, `pnpm why react-router`.

## Testing

Test helpers live in a separate entry point, `@tailor-platform/app-shell/testing`. Memory routing is kept out of the main entry because an app that shipped it would render correctly while the URL bar silently stopped tracking navigation — the `AppShell` you import from `@tailor-platform/app-shell` always uses browser routing, and pins it off regardless of what you pass.

### Pages and integration tests

Because AppShell owns the router, a test mounts AppShell rather than building a router. The `AppShell` exported from `/testing` is the same shell, and additionally accepts `memory` with `initialEntries` so it starts at a known URL without touching `window.location`:

```tsx
import { render, screen } from "@testing-library/react";
import { AppShell } from "@tailor-platform/app-shell/testing";
import { SidebarLayout } from "@tailor-platform/app-shell";

render(
  <AppShell memory initialEntries={["/orders/A42"]} modules={modules}>
    <SidebarLayout />
  </AppShell>,
);

expect(await screen.findByText("Order A42")).toBeDefined();
```

`initialEntries` is the history stack to start with — the last entry is the current location. Each render owns its history, so tests do not leak navigation state into one another.

### Unit tests

A component that calls `useNavigate` or renders a `<Link>` needs a router above it, but mounting a whole AppShell for that is heavy. `TestRouter` provides just the router context:

```tsx
import { TestRouter } from "@tailor-platform/app-shell/testing";

render(
  <TestRouter initialEntries={["/orders/A42"]}>
    <SaveButton />
  </TestRouter>,
);
```

**If the component reads the route**, pass `path`. A router on its own matches nothing, so `useParams()` comes back empty even when `initialEntries` holds a URL that looks like it should match:

```tsx
render(
  <TestRouter path="/orders/:id" initialEntries={["/orders/A42"]}>
    <OrderBadge /> {/* useParams() -> { id: "A42" } */}
  </TestRouter>,
);
```

The same applies to `useMatch` and to relative `<Link>` targets. Compose your own providers — a GraphQL client, say — around `TestRouter` as needed.

Reach for `TestRouter` when the component under test is the subject; mount `AppShell memory` when the routing itself is.

## Example

```tsx
import { useNavigate, useParams, useLocation, Link } from "@tailor-platform/app-shell";

const MyComponent = () => {
  const navigate = useNavigate();
  const { id } = useParams();
  const location = useLocation();

  const handleClick = () => {
    // Navigate programmatically
    navigate("/dashboard/overview");
  };

  return (
    <div>
      <p>Current path: {location.pathname}</p>
      <p>Route param ID: {id}</p>

      {/* Client-side link */}
      <Link to="/products">View Products</Link>

      <button onClick={handleClick}>Go to Dashboard</button>
    </div>
  );
};
```

## Declarative Redirects

`Navigate` redirects as a render result, which avoids the `useEffect` + `navigate()` pattern (that pattern renders the old page for a frame before it redirects):

```tsx
import { Navigate, useAppShellData } from "@tailor-platform/app-shell";

const AdminPage = () => {
  const { currentUser } = useAppShellData();

  if (currentUser?.role !== "admin") {
    return <Navigate to="/dashboard" replace />;
  }

  return <AdminDashboard />;
};
```

Pass `replace` when the redirect should not leave the abandoned route in history — otherwise the browser Back button lands the user right back on it, and bounces them forward again.

### Choosing between `Navigate` and `redirectTo()`

Both redirect, but they run at different points:

|                                                | Runs                                     | Use for                                                                                            |
| ---------------------------------------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------- |
| [`redirectTo()`](../api/guards/redirect-to) | Route guard, before the component mounts | Route-level access control — the preferred option when the decision can be made from guard context |
| `Navigate`                                     | During render, from inside a component   | Decisions that depend on component state, hooks, or fetched data                                   |

Reach for `redirectTo()` first: it never mounts the component. `Navigate` is the fallback for cases a guard cannot express — notably [`WithGuard`](../components/with-guard), which does not support `redirectTo()`.

## Breadcrumbs

AppShell automatically generates breadcrumbs from your module and resource hierarchy. Each path segment corresponds to a breadcrumb item, using the `title` (or `meta.breadcrumbTitle`) defined in `defineModule` / `defineResource`.

### Static Breadcrumb Titles

Set a fixed breadcrumb title via `meta.breadcrumbTitle`:

```tsx
defineResource({
  path: ":id",
  meta: {
    breadcrumbTitle: (segment) => `Order #${segment}`,
  },
  component: OrderDetailPage,
});
// Breadcrumb shows: "Orders > Order #12345"
```

### Dynamic Breadcrumb Titles

Use the `useOverrideBreadcrumb` hook to replace a breadcrumb segment with a data-driven value from within the rendered page component:

```tsx
import { useOverrideBreadcrumb } from "@tailor-platform/app-shell";

defineResource({
  path: ":id",
  component: () => {
    const { data } = useQuery(GET_ORDER, { variables: { id } });

    // Breadcrumb updates reactively once data loads
    useOverrideBreadcrumb(data?.order?.name);

    return <OrderDetail />;
  },
});
```

While `title` is `undefined` (e.g., loading), the override is cleared and the static title is shown. The override is automatically cleaned up on unmount.

See [useOverrideBreadcrumb](../api/use-override-breadcrumb) for the full API reference.

## Command Palette for Quick Navigation

AppShell includes a `CommandPalette` component that provides keyboard-driven quick navigation to any page in your application.

### Features

* **Keyboard Shortcut**: `Cmd+K` (Mac) or `Ctrl+K` (Windows/Linux)
* **Fuzzy Search**: Search by page title or path
* **Hierarchical Display**: Shows module > resource breadcrumbs
* **Keyboard Navigation**: Use arrow keys and Enter to navigate
* **Multilingual**: Supports English and Japanese locales

### Setup

The CommandPalette is built into `AppShell` and rendered automatically:

```tsx
import { AppShell, SidebarLayout } from "@tailor-platform/app-shell";

const App = () => (
  <AppShell modules={modules} locale="en">
    <SidebarLayout />
  </AppShell>
);
```

The CommandPalette automatically:

* Collects all navigable routes from your module definitions
* Respects guards (modules/resources returning `hidden()` won't appear)
* Updates when navigation items change
* Adapts to the current locale

### User Experience

1. User presses `Cmd+K` / `Ctrl+K` anywhere in the app
2. Command palette dialog opens with fuzzy search
3. User types to filter pages (e.g., "order detail")
4. Navigate results with arrow keys
5. Press Enter to navigate to selected page

No configuration needed - it just works!

## Type-Safe Navigation with Generated Routes

When using file-based routing with the vite-plugin, you can enable automatic generation of type-safe route helpers. This provides compile-time checking for route paths and their parameters.

### Setup

Enable `generateTypedRoutes` in your vite config:

```ts
// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { appShellRoutes } from "@tailor-platform/app-shell/vite-plugin";

export default defineConfig({
  plugins: [
    react(),
    appShellRoutes({
      pagesDir: "src/pages",
      // Enable with default output path ("src/routes.generated.ts")
      generateTypedRoutes: true,
      // Or customize output path:
      // generateTypedRoutes: { output: "src/my-routes.ts" },
    }),
  ],
});
```

This generates a `src/routes.generated.ts` file containing type definitions for all your routes.

### Generated File

The generated file exports a `paths` helper with a type-safe `for()` method:

```ts
// src/routes.generated.ts (auto-generated)
import { createTypedPaths } from "@tailor-platform/app-shell";

type RouteParams = {
  "/": {};
  "/dashboard": {};
  "/orders": {};
  "/orders/:id": { id: string };
  "/orders/:orderId/items/:itemId": { orderId: string; itemId: string };
};

export const paths = createTypedPaths<RouteParams>();

export type { RouteParams };
```

### Usage

```tsx
import { useNavigate } from "@tailor-platform/app-shell";
import { paths } from "./routes.generated";

const MyComponent = () => {
  const navigate = useNavigate();

  // ✅ Static route - no params needed
  const goToDashboard = () => {
    navigate(paths.for("/dashboard"));
  };

  // ✅ Dynamic route - params required and type-checked
  const goToOrder = (orderId: string) => {
    navigate(paths.for("/orders/:id", { id: orderId }));
  };

  // ✅ Multiple params
  const goToOrderItem = (orderId: string, itemId: string) => {
    navigate(paths.for("/orders/:orderId/items/:itemId", { orderId, itemId }));
  };

  // ✅ Query string passthrough
  const goToOrderWithTab = (orderId: string) => {
    navigate(paths.for("/orders/:id?tab=details", { id: orderId }));
  };

  // ✅ Dynamic query values via template literal
  const goToOrderWithDynamicQuery = (orderId: string, tab: string) => {
    navigate(paths.for(`/orders/:id?tab=${tab}`, { id: orderId }));
  };

  // ❌ TypeScript error: missing required params
  // navigate(paths.for("/orders/:id"));

  // ❌ TypeScript error: invalid path
  // navigate(paths.for("/invalid/path"));

  return <button onClick={goToDashboard}>Go to Dashboard</button>;
};
```

### Opt-In Design

This feature is opt-in. If you don't enable `generateTypedRoutes`, you can continue building paths dynamically:

```tsx
// Still works without typed routes
navigate(`/orders/${orderId}`);
```

### HMR Support

The generated file is automatically regenerated when:

* A new `page.tsx` is added
* A `page.tsx` is deleted
* The dev server starts

---

---
url: https://docs.tailor.tech/app-shell/concepts/sidebar-navigation.md
description: >-
  Learn how to customize sidebar navigation with auto-generation or composition
  mode
---

# Sidebar Navigation

AppShell provides flexible sidebar navigation with two modes:

* **Auto-generation mode**: Automatically generates navigation from module/resource definitions
* **Composition mode**: Full control over sidebar structure using declarative components

## Quick Start

### Auto-generation Mode (Default)

The simplest way to use the sidebar - navigation items are automatically generated from your module definitions:

```tsx
import { AppShell, SidebarLayout } from "@tailor-platform/app-shell";

const App = () => (
  <AppShell modules={modules}>
    <SidebarLayout />
  </AppShell>
);
```

### Composition Mode

For full control over sidebar structure, pass children to `DefaultSidebar` via the `sidebar` prop:

```tsx
import {
  AppShell,
  SidebarLayout,
  DefaultSidebar,
  SidebarItem,
  SidebarGroup,
  SidebarSeparator,
} from "@tailor-platform/app-shell";
import { Package, Settings } from "lucide-react";

const App = () => (
  <AppShell modules={modules}>
    <SidebarLayout
      sidebar={
        <DefaultSidebar>
          <SidebarItem to="/dashboard" />
          <SidebarSeparator />
          <SidebarGroup title="Products" icon={<Package />}>
            <SidebarItem to="/products/all" />
            <SidebarItem to="/products/categories" />
          </SidebarGroup>
          <SidebarItem to="/settings" icon={<Settings />} />
        </DefaultSidebar>
      }
    />
  </AppShell>
);
```

***

## Components

### SidebarItem

A navigation item that automatically resolves title and icon from resource definitions.

#### Props

| Prop       | Type        | Required | Description                                                           |
| ---------- | ----------- | -------- | --------------------------------------------------------------------- |
| `to`       | `string`    | Yes      | Target URL. External URLs (http://...) are rendered as external links |
| `title`    | `string`    | No       | Override title. When omitted, auto-resolved from resource meta        |
| `icon`     | `ReactNode` | No       | Override icon. When omitted, auto-resolved from resource meta         |
| `external` | `boolean`   | No       | Opens link in new tab with external link icon                         |
| `render`   | `function`  | No       | Custom render function for full UI control                            |

#### Examples

```tsx
// Auto-resolved from resource meta
<SidebarItem to="/dashboard" />

// Override title and icon
<SidebarItem to="/" title="Home" icon={<Home />} />

// External link
<SidebarItem to="https://docs.example.com" external />

// Custom rendering with render prop
<SidebarItem
  to="/tasks"
  render={({ title, icon, isActive }) => (
    <div className={isActive ? "font-bold" : ""}>
      {icon}
      <span>{title}</span>
      <Badge>5</Badge>
    </div>
  )}
/>
```

#### Render Prop

When using the `render` prop, you receive `SidebarItemRenderProps`:

| Property   | Type                     | Description                                     |
| ---------- | ------------------------ | ----------------------------------------------- |
| `title`    | `string`                 | Resolved title (from override or resource meta) |
| `url`      | `string`                 | Target URL                                      |
| `icon`     | `ReactNode \| undefined` | Resolved icon                                   |
| `isActive` | `boolean`                | Whether this item is currently active           |

***

### SidebarGroup

A collapsible group for organizing navigation items.

#### Props

| Prop          | Type              | Required | Description                                    |
| ------------- | ----------------- | -------- | ---------------------------------------------- |
| `title`       | `LocalizedString` | Yes      | Group title (supports i18n)                    |
| `icon`        | `ReactNode`       | No       | Group icon                                     |
| `to`          | `string`          | No       | When specified, title becomes a clickable link |
| `defaultOpen` | `boolean`         | No       | Initial expanded state. Default: `true`        |
| `children`    | `ReactNode`       | Yes      | Child items (SidebarItem, SidebarGroup, etc.)  |

#### Examples

```tsx
// Basic group
<SidebarGroup title="Products" icon={<Package />}>
  <SidebarItem to="/products/all" />
  <SidebarItem to="/products/categories" />
</SidebarGroup>

// Clickable group header
<SidebarGroup title="Settings" icon={<Settings />} to="/settings">
  <SidebarItem to="/settings/profile" />
  <SidebarItem to="/settings/security" />
</SidebarGroup>

// Initially collapsed
<SidebarGroup title="Archives" defaultOpen={false}>
  <SidebarItem to="/archives/2024" />
  <SidebarItem to="/archives/2023" />
</SidebarGroup>

// Nested groups
<SidebarGroup title="Products" icon={<Package />}>
  <SidebarItem to="/products/all" />
  <SidebarGroup title="Archives" defaultOpen={false}>
    <SidebarItem to="/products/archives/2024" />
    <SidebarItem to="/products/archives/2023" />
  </SidebarGroup>
</SidebarGroup>
```

#### i18n Support

Group titles support localized strings:

```tsx
import { defineI18nLabels } from "@tailor-platform/app-shell";

const labels = defineI18nLabels({
  en: { products: "Products" },
  ja: { products: "製品" },
});

<SidebarGroup title={labels.t("products")} icon={<Package />}>
  <SidebarItem to="/products/all" />
</SidebarGroup>;
```

***

### SidebarSeparator

A visual divider between sidebar sections.

#### Props

This component takes no props.

#### Example

```tsx
<DefaultSidebar>
  <SidebarItem to="/dashboard" />
  <SidebarSeparator />
  <SidebarItem to="/settings" />
</DefaultSidebar>
```

***

### DefaultSidebar

The main sidebar container that supports both auto-generation and composition modes.

#### Props

| Prop       | Type        | Required | Description                             |
| ---------- | ----------- | -------- | --------------------------------------- |
| `header`   | `ReactNode` | No       | Custom header content                   |
| `footer`   | `ReactNode` | No       | Custom footer content                   |
| `children` | `ReactNode` | No       | When provided, enables composition mode |

#### Examples

```tsx
// Auto-generation mode
<DefaultSidebar />

// With custom header and footer
<DefaultSidebar
  header={<Logo />}
  footer={<UserMenu />}
/>

// Composition mode with custom navigation
<DefaultSidebar header={<Logo />}>
  <SidebarItem to="/dashboard" />
  <SidebarGroup title="Products">
    <SidebarItem to="/products/all" />
  </SidebarGroup>
</DefaultSidebar>
```

***

## Hooks

### usePageMeta

A hook to retrieve page metadata (title, icon) for a given URL path.

#### Signature

```typescript
const usePageMeta: (path: string) => PageMeta | null;

type PageMeta = {
  title: string;
  icon?: ReactNode;
};
```

#### Parameters

| Parameter | Type     | Description                                       |
| --------- | -------- | ------------------------------------------------- |
| `path`    | `string` | URL path to find meta for (e.g., "/products/all") |

#### Returns

* `PageMeta` - Object containing `title` and optional `icon` if found
* `null` - For external links or when path is not found

#### Example

```tsx
import { usePageMeta } from "@tailor-platform/app-shell";

const MyComponent = () => {
  const pageMeta = usePageMeta("/products/all");

  if (!pageMeta) {
    return <span>Unknown Page</span>;
  }

  return (
    <div>
      {pageMeta.icon}
      <span>{pageMeta.title}</span>
    </div>
  );
};
```

***

## Access Control

### Auto-generation Mode

In auto-generation mode, `guards` defined in `defineModule`/`defineResource` are automatically evaluated. Modules/resources that return `hidden()` will not appear in the sidebar.

```tsx
import { defineModule, defineResource, pass, hidden } from "@tailor-platform/app-shell";

const adminModule = defineModule({
  path: "admin",
  meta: { title: "Admin" },
  // If this guard returns hidden(), the module won't appear in sidebar
  guards: [({ context }) => (context.currentUser.role === "admin" ? pass() : hidden())],
  resources: [
    defineResource({
      path: "users",
      meta: { title: "Users" },
      component: () => <div>Users</div>,
    }),
  ],
});

// Used with auto-generation mode
<DefaultSidebar />;
```

### Composition Mode

In composition mode, use the `WithGuard` component to control visibility of sidebar items. This allows you to reuse the same guard logic used in route definitions.

```tsx
import { WithGuard, pass, hidden } from "@tailor-platform/app-shell";

// Define a guard function
const isAdminGuard = ({ context }) => (context.currentUser.role === "admin" ? pass() : hidden());

<DefaultSidebar>
  <SidebarItem to="/dashboard" />

  {/* Wrap items with WithGuard for conditional visibility */}
  <WithGuard guards={[isAdminGuard]}>
    <SidebarGroup title="Admin" icon={<Shield />}>
      <SidebarItem to="/admin/users" />
      <SidebarItem to="/admin/settings" />
    </SidebarGroup>
  </WithGuard>
</DefaultSidebar>;
```

#### Curried Guards

For parameterized guards, use the curried pattern:

```tsx
// Define a curried guard factory
const hasRole =
  (role: string) =>
  ({ context }) =>
    context.currentUser.role === role ? pass() : hidden();

<DefaultSidebar>
  <WithGuard guards={[hasRole("admin")]}>
    <SidebarItem to="/admin" />
  </WithGuard>

  <WithGuard guards={[hasRole("manager")]}>
    <SidebarItem to="/reports" />
  </WithGuard>
</DefaultSidebar>;
```

> **Note**: Route-level access control (e.g., redirects) still works via `guards` in `defineResource`, even in composition mode. `WithGuard` only controls visibility—it does not prevent navigation to protected routes.

***

## Migration from Auto-generation

If you're currently using auto-generated navigation and want to customize it:

1. **Keep auto-generation for most items**, add custom items where needed:

```tsx
// Before: Pure auto-generation
<DefaultSidebar />

// After: Composition with similar structure
<DefaultSidebar>
  <SidebarItem to="/dashboard" />
  <SidebarItem to="/products" />
  <SidebarSeparator />
  <SidebarItem to="https://docs.example.com" title="Documentation" external />
</DefaultSidebar>
```

2. **Title and icon are auto-resolved** from your resource definitions, so you don't need to specify them unless you want to override.

3. **External links** can now be added directly in the sidebar.

---

---
url: https://docs.tailor.tech/app-shell/concepts/styling-theming.md
description: >-
  Learn how to style your AppShell application using Tailwind CSS v4 and
  customize the theme
---

# Styling and Theming

Styling is done using Tailwind CSS v4. AppShell exports `@tailor-platform/app-shell/styles`, which includes the default palette and CSS variables.

To configure your application, import AppShell styles from your global CSS or top-level Tailwind CSS file:

```css
@import "tailwindcss";
@import "@tailor-platform/app-shell/styles";
```

That is the whole setup. `styles` ships the palette (light **and** dark), the Tailwind v4 `@theme inline` bridge, and the `dark` custom variant, so your entry CSS should declare none of them itself. A copy of any of them in your own CSS overrides AppShell's and silently breaks dark mode.

If you want a branded palette, import exactly one theme file after `styles`:

```css
@import "tailwindcss";
@import "@tailor-platform/app-shell/styles";
@import "@tailor-platform/app-shell/themes/bloom";
```

After including this, your application's Tailwind utilities will resolve against the active AppShell tokens.

E.g.

```tsx
<div className="text-muted-foreground bg-muted">...</div>
```

Note, many of these are default Tailwind colors, but there are some differences. If you omit this, much of the UI will look the same, but we will lose some of the Tailor-preferred colors.

## Semantic color utilities

Beyond the standard shadcn/Tailwind names (`background`, `muted`, `primary`, …), AppShell bridges two semantic token families into Tailwind's color namespace, so they work with any color utility (`bg-`, `text-`, `border-`, `ring-`, …) and appear in editor autocomplete.

**Status** — flat colors, typically for badges and indicators:

| Utility suffix     | Token                |
| ------------------ | -------------------- |
| `status-default`   | `--status-default`   |
| `status-neutral`   | `--status-neutral`   |
| `status-completed` | `--status-completed` |
| `status-attention` | `--status-attention` |
| `status-danger`    | `--status-danger`    |

```tsx
<span className="bg-status-attention">Pending review</span>
```

**Alert** — grouped sets for callouts, banners, and highlighted rows. Each of the five variants (`neutral`, `success`, `warning`, `error`, `info`) provides four slots:

| Slot               | Utility example                    | Use for                    |
| ------------------ | ---------------------------------- | -------------------------- |
| `background`       | `bg-alert-info-background`         | Callout fill               |
| `foreground`       | `text-alert-info-foreground`       | Primary text and icons     |
| `foreground-muted` | `text-alert-info-foreground-muted` | Secondary/description text |
| `border`           | `border-alert-info-border`         | Callout border             |

```tsx
<div className="rounded-lg border px-4 py-3 bg-alert-info-background text-alert-info-foreground border-alert-info-border">
  <p className="font-medium">Heads up</p>
  <p className="text-alert-info-foreground-muted">
    This is the same palette the built-in Alert uses.
  </p>
</div>
```

These are the tokens the [`Alert`](../components/alert) component uses internally — reach for them when you need the same callout treatment somewhere `Alert` doesn't fit. All twenty resolve in both light and dark mode, and branded palettes inherit them from the default palette.

> Prefer these named utilities over arbitrary-value syntax like `bg-[color:var(--alert-info-background)]`. Both produce identical CSS, but a typo in an arbitrary value fails silently — the element simply renders unstyled — whereas a misspelled utility class is caught by editor tooling.

Note that the `background` and `border` slots are already semi-transparent (a ~10% and ~20% tint respectively). An opacity modifier therefore compounds rather than replaces: `bg-alert-info-background/50` yields roughly 5% alpha, not 50%. Set the background with an unmodified utility, or reach for the underlying accent color if you need a specific opacity.

## A note on AppShell component class names

AppShell components use Tailwind utility classes for their styling. Tailwind classes are generated at build-time, so stylesheet for AppShell components is already built and is separate to the Tailwind stylesheet generated for your application.

In CSS, the order of style-definition affects the final styles which are computed for an element. Tailwind takes this into account when generating its stylesheet, however because it does not know that there's already a Tailwind-generated stylesheet included in the browser (AppShell's styles), there would be incorrect ordering of style definitions, and clashes can (though do not always) occur.

To avoid this situation, and to ensure correct style resolution, AppShell components use a class prefix "astw" (AppShell TailWind) to avoid clashes.

This is important to note for developing in AppShell.

## Color Themes (Light / Dark / System)

AppShell supports three color modes: `light`, `dark`, and `system` (follows the OS setting).

Set the initial mode via the `defaultColorTheme` prop on `<AppShell>`. The user's selection is persisted to `localStorage` and restored on subsequent visits:

```tsx
<AppShell defaultColorTheme="system" modules={modules}>
  {/* ... */}
</AppShell>
```

Use the [`useTheme`](../api/use-theme) hook to read or change the theme at runtime:

```tsx
import { useTheme } from "@tailor-platform/app-shell";

function ThemeToggle() {
  const { theme, resolvedTheme, setTheme } = useTheme();
  return (
    <button onClick={() => setTheme(resolvedTheme === "dark" ? "light" : "dark")}>
      Switch to {resolvedTheme === "dark" ? "light" : "dark"} mode
    </button>
  );
}
```

Drop the pre-built [`AppearanceSwitcher`](../components/appearance-switcher) component anywhere in your layout for a ready-made light/dark/system toggle:

```tsx
import { AppearanceSwitcher } from "@tailor-platform/app-shell";

<AppearanceSwitcher />;
```

## Theme Palettes

AppShell ships three palettes, each with light and dark variants:

| Palette   | CSS import                                                     |
| --------- | -------------------------------------------------------------- |
| `default` | Included automatically via `@tailor-platform/app-shell/styles` |
| `cream`   | `@tailor-platform/app-shell/themes/cream`                      |
| `bloom`   | `@tailor-platform/app-shell/themes/bloom`                      |

Select a palette by importing its CSS file — no prop needed. Import it in your global CSS **after** `@tailor-platform/app-shell/styles`:

```css
@import "tailwindcss";
@import "@tailor-platform/app-shell/styles";
@import "@tailor-platform/app-shell/themes/cream"; /* overrides default palette */
```

Only import one palette at a time.

## Overriding tokens

Redeclare any token after the AppShell imports. Use `:root` for light and `:root.dark` for dark — that pair wins against every palette AppShell ships:

```css
@import "tailwindcss";
@import "@tailor-platform/app-shell/styles";

:root {
  --primary: #2563eb;
}

:root.dark {
  --primary: #60a5fa;
}
```

Two rules:

* **Set each override in both modes.** Overriding only `:root` misbehaves either way: on the default palette the light value carries into dark mode, and on a branded palette the override stops applying in dark mode altogether.
* **Override individual tokens; never copy the palette wholesale.** Copied tokens freeze at the value you copied while everything else tracks AppShell, so the two halves drift apart — and any surface AppShell adds later has no value in your copy at all.

`:root.dark` rather than `.dark` because the two palette families behave differently. The default palette is imported inside a cascade layer (`layer(theme.defaults)`), so any unlayered declaration of yours beats it. The branded palettes (`cream`, `bloom`) are imported by you, unlayered, and define dark values on `:root.dark` — which outranks a bare `.dark`, so a `.dark` override would silently lose. `:root.dark` is correct against both.

Overriding under a narrower scope — per-section or per-tenant — needs the same care: pair `.tenant-a` with `:root.dark .tenant-a` so the dark rule still outranks a branded palette's `:root.dark`. Note also that `:root.dark` matches only `<html class="dark">`; if you apply `.dark` to a subtree to darken one region, scope your overrides to that subtree rather than to `:root.dark`.

## Typography and Fonts

AppShell bundles **Inter Variable** for Latin and **Noto Sans JP Variable** for Japanese, and
applies both via the `body` rule in `@tailor-platform/app-shell/styles`. No extra import:

```css
@import "tailwindcss";
@import "@tailor-platform/app-shell/styles";
```

Both are variable fonts with a continuous 100–900 weight axis, so every weight the design
system names — `font-normal`, `font-medium`, `font-semibold`, `font-bold` — resolves to a real
weight in both scripts rather than to whatever faces happen to be installed.

### Why Japanese needs its own font

Inter has no CJK glyphs, so without a bundled Japanese font, Japanese characters fall through
to the operating system's. On Windows that font is Yu Gothic UI, which ships only
Light/Semilight/Regular/Semibold/Bold — no 500 — so CSS weight matching resolves a
`font-weight: 500` request down to Regular, and `font-medium` becomes **indistinguishable from
body text in Japanese**. Current macOS is not affected: it ships Hiragino Sans W0–W9 including
W5, which `font-weight: 500` resolves to correctly. Bundling the font makes the weight scale
hold on every platform rather than depending on what the OS happens to install.

Noto Sans JP is metric-harmonised against Inter (`size-adjust: 94%` plus ascent/descent
overrides) so mixed Japanese/Latin strings read at one optical size, and a line containing
Japanese is exactly as tall as one without. A metric-matched `local()` fallback covers the
window before a subset arrives, so rows do not change height as fonts stream in.

### What it costs

The Japanese faces are roughly **5 MB of woff2 subsets**, and they land in your build output
whether or not your app renders Japanese — a bundler emits every subset it can see, because it
cannot know at build time which characters your data will contain. The stylesheet grows from
about 98 KB to 200 KB uncompressed, or 15 KB to 45 KB gzipped.

What your **users** download is much smaller, and proportional to what they actually read.
Each subset carries a `unicode-range`, so the browser fetches one only when it is about to
paint a character in that range. The faces are restricted to Japanese blocks — kana, kanji,
CJK punctuation, fullwidth forms and the compatibility blocks carrying ㈱ ㍿ ㎡ — so shared
symbols such as `✓` or `→` resolve to Inter or the system font as before, and
**an app that renders no Japanese downloads none of them**:

| what the user has seen                   | downloaded  |
| ---------------------------------------- | ----------- |
| all hiragana + katakana                  | ~237 KB     |
| + ~230 common ERP kanji                  | ~458 KB     |
| + ~30 name kanji including variant forms | ~467 KB     |
| **typical first Japanese screen**        | **~910 KB** |

Files are content-hashed and cached, so the cost is front-loaded rather than per-navigation,
and it grows slowly as unusual characters appear in your data. Weight costs nothing extra —
every weight lives in the same file, so using `font-medium` and `font-bold` downloads no more
than `font-normal` alone.

To drop the Japanese faces entirely, override the stack without naming them (see below).
Nothing references them, so nothing is downloaded — though the files still ship in your build
output.

### Using your own font

Set `--app-shell-font-sans` on `:root` **after** importing AppShell styles to replace the whole
stack:

```css
@import "@tailor-platform/app-shell/styles";

:root {
  --app-shell-font-sans: "Your Brand Sans", ui-sans-serif, system-ui, sans-serif;
}
```

A replacement should be a variable font, or otherwise supply real 400/500/600/700 faces —
AppShell's weight scale assumes all four exist. If your app renders Japanese, include a
Japanese family with a continuous weight axis for the same reason.

## Z-Index Layering

AppShell defines CSS custom properties for z-index values so you can adjust the stacking order to integrate with other libraries or overlays in your application.

These properties are defined in `:root` and can be overridden in your own CSS:

| Property           | Default | Used for                                                            |
| ------------------ | ------- | ------------------------------------------------------------------- |
| `--z-sidebar`      | `10`    | The sidebar panel                                                   |
| `--z-sidebar-rail` | `20`    | The sidebar collapse rail / toggle button                           |
| `--z-popup`        | `50`    | Portal-based popups (Menu, Select, Combobox, Autocomplete, Tooltip) |
| `--z-overlay`      | `50`    | Modal overlays (Dialog, Sheet)                                      |

### Example: Raising popup z-index

```css
/* your-app/globals.css */
@import "tailwindcss";
@import "@tailor-platform/app-shell/styles";

:root {
  --z-popup: 100;
}
```

## Adding a palette

Theme tokens live in `packages/core/src/assets/themes/`. Copy `_template.css` to start a new palette — it lists exactly which sections to fill in for light and dark mode.

| Section               | Required?             | What to set                                                                    |
| --------------------- | --------------------- | ------------------------------------------------------------------------------ |
| **1. Brand**          | Yes                   | `primary`, `secondary`, `accent` (+ foregrounds) — both modes                  |
| **2. Shell gradient** | Branded palettes only | `--shell-gradient-base`, `--shell-gradient-tint`                               |
| **3. System**         | Tune or copy default  | Surfaces: background, card, popover, muted, borders                            |
| **4. Palette**        | Optional              | Radius, chart colors, shadows                                                  |
| **5. Semantic**       | Do not duplicate      | Status and alert tokens inherit from `default.css`                             |
| **6. Structural**     | Branded palettes      | Copy the structural override block from `bloom.css` or `cream.css` when needed |

A palette is selected by CSS import, not by an AppShell prop. Import exactly one theme file after `@tailor-platform/app-shell/styles`; if you import none, the default palette from `styles` is used.

Preview token values at `/custom-page/color` in the Next.js example app.

Or skip the local setup: **[theme.tailor.tech](https://theme.tailor.tech/playground)**
takes a primary color, previews it on real AppShell components, and exports a
`themes/{name}.css` structured according to the tier table above.

---

---
url: https://docs.tailor.tech/app-shell/components/action-panel.md
description: >-
  Display a title and a vertical list of actions with per-row loading and
  disabled states
---

# ActionPanel

`ActionPanel` is a presentational card component for rendering a vertical list of actions (icon + label). It is designed for ERP detail pages and side panels where available actions are often backend-driven.

[Live preview in the UI Catalogue →](https://ui.tailor.tech/components/action-panel)

## Import

```tsx
import { ActionPanel } from "@tailor-platform/app-shell";
```

## Basic Usage

```tsx
<ActionPanel
  title="Actions"
  actions={[
    {
      key: "create-invoice",
      label: "Create new sales invoice",
      icon: <ReceiptIcon />,
      onClick: () => openCreateInvoiceModal(),
    },
    {
      key: "view-docs",
      label: "View documentation",
      icon: <ExternalLinkIcon />,
      onClick: () => window.open("/docs", "_blank", "noopener,noreferrer"),
    },
  ]}
/>
```

## Props

### ActionPanel Props

| Prop        | Type           | Default      | Description                              |
| ----------- | -------------- | ------------ | ---------------------------------------- |
| `title`     | `string`       | **Required** | Card title (for example, `"Actions"`)    |
| `actions`   | `ActionItem[]` | **Required** | List of actions to render                |
| `className` | `string`       | -            | Additional CSS classes for the card root |

### ActionItem

| Property   | Type                          | Default      | Description                                                           |
| ---------- | ----------------------------- | ------------ | --------------------------------------------------------------------- |
| `key`      | `string`                      | **Required** | Unique key for stable rendering                                       |
| `label`    | `string`                      | **Required** | Action label shown to users                                           |
| `icon`     | `ReactNode`                   | **Required** | Icon rendered in a fixed 16px slot                                    |
| `onClick`  | `() => void \| Promise<void>` | -            | Click handler for the action                                          |
| `disabled` | `boolean`                     | `false`      | Disables interaction and applies disabled styling                     |
| `loading`  | `boolean`                     | `false`      | Shows spinner, disables interaction, sets busy UI                     |
| `variant`  | `"default" \| "destructive"`  | `"default"`  | Visual variant; use `"destructive"` for dangerous actions like delete |

## Behavior

* Rows are rendered as `<button type="button">` elements.
* `disabled` or `loading` makes the row non-interactive.
* When `loading` is `true`, the icon slot renders a spinner without shifting layout.
* Empty actions show a built-in fallback message: `No actions available`.

## With Loading State

Use parent state to control which row is loading:

```tsx
const [loadingKey, setLoadingKey] = useState<string | null>(null);

const handleConfirm = async () => {
  setLoadingKey("confirm");
  try {
    await confirmOrder(orderId);
  } finally {
    setLoadingKey(null);
  }
};

<ActionPanel
  title="Actions"
  actions={[
    {
      key: "confirm",
      label: "Confirm order",
      icon: <CheckIcon />,
      onClick: handleConfirm,
      loading: loadingKey === "confirm",
    },
  ]}
/>;
```

## CommandPalette Integration

`ActionPanel` automatically registers its enabled actions to the CommandPalette. Actions that are not `disabled`, not `loading`, and have an `onClick` handler are registered under the panel's `title` as the group name. Registration is cleaned up when the component unmounts.

This means users can discover and trigger any visible ActionPanel action via `Cmd+K` / `Ctrl+K` without any additional setup.

```tsx
// Actions in this panel will automatically appear in the CommandPalette
<ActionPanel
  title="Order Actions"
  actions={[
    { key: "confirm", label: "Confirm order", icon: <CheckIcon />, onClick: handleConfirm },
    { key: "cancel", label: "Cancel order", icon: <XIcon />, onClick: handleCancel },
  ]}
/>
```

> **Note:** `ActionPanel` must be rendered inside `AppShell` (which provides the required `CommandPaletteProvider`). Rendering it outside that tree will throw.

## Backend-Driven Pattern

In ERP apps, the backend often decides which actions are available for a document. A common setup:

1. Backend returns document data and available action keys.
2. Frontend maps each key to a registry entry (`label`, `icon`, `execute`).
3. Page builds `ActionItem[]` and wires `onClick`.
4. Page controls `loading` per key and passes it to `ActionPanel`.

This keeps `ActionPanel` simple and reusable across entity types.

## Accessibility

* Action list uses `role="list"` and each row wrapper uses `role="listitem"`.
* Buttons are keyboard accessible and include focus-visible states.
* Loading rows set `aria-busy="true"`.
* Disabled rows set `aria-disabled="true"` and native `disabled`.

## Styling

The component uses Tailwind classes with the `astw:` prefix:

* Full width card (`astw:w-full`)
* Compact spacing for dense action lists
* Fixed icon slot for stable alignment
* Inline spinner for loading state

Use `className` on `ActionPanel` to add or override card-level styles.

## Examples in This Repo

* `examples/app-module` includes an **Action Panel Demo** resource.
* The **2 Columns** layout page also includes an ActionPanel with loading behavior.

## Related Components

* [Layout](layout) - Compose page-level column layouts
* [DescriptionCard](description-card) - Display structured record fields
* [Badge](badge) - Show statuses and semantic labels

## Related Concepts

* [Modules and Resources](../concepts/modules-and-resources) - Organize pages and routes
* [Routing and Navigation](../concepts/routing-navigation) - Navigation patterns

---

---
url: https://docs.tailor.tech/app-shell/components/activity-card.md
description: Timeline of recent document activities with avatars and overflow dialog
---

# ActivityCard

The `ActivityCard` component displays a timeline of recent activities (e.g. changes on a PO, SO, or GR document). Each entry shows an avatar, user name, description, and timestamp. A limited number of activities are shown in the card; additional activities are available via a clickable overflow that opens a dialog with a scrollable full list.

[Live preview in the UI Catalogue →](https://ui.tailor.tech/components/activity-card)

## Import

```tsx
import {
  ActivityCard,
  type ActivityCardItem,
  type ActivityCardBaseItem,
  type ActivityCardProps,
} from "@tailor-platform/app-shell";
```

Use `ActivityCardItem` for each item in the standalone API. Use `ActivityCardBaseItem` as the minimum constraint when extending items for the compound API.

## Basic Usage

```tsx
const items = [
  {
    id: "1",
    actor: { name: "Hanna", avatarUrl: "/avatars/hanna.jpg" }, // avatarUrl is optional
    description: "changed the status from DRAFT to CONFIRMED",
    timestamp: new Date("2025-03-21T09:00:00"),
  },
  {
    id: "2",
    actor: { name: "Pradeep Kumar" },
    description: "created this PO",
    timestamp: new Date("2025-03-21T15:16:00"),
  },
  {
    id: "3",
    // no actor — system event with no specific subject
    description: "Status automatically changed to EXPIRED",
    timestamp: new Date("2025-03-20T10:00:00"),
  },
];

export function DocumentUpdates() {
  return <ActivityCard items={items} title="Updates" />;
}
```

## Overflow and dialog

By default the card shows the 6 most recent activities. If there are more, a button appears at the bottom (e.g. **"2 more activities"**). Clicking it opens a modal dialog titled "All activities" with the full list in a scrollable area. The overflow label can be switched to a count style (**"+2"**) via the `overflowLabel` prop.

```tsx
<ActivityCard items={manyItems} title="Updates" maxVisible={6} overflowLabel="more" />
// or overflowLabel="count" for "+N"
```

## Grouping by day

Set `groupBy="day"` to group activities under labels like "TODAY", "YESTERDAY", or a formatted date.

```tsx
<ActivityCard items={items} title="Updates" groupBy="day" />
```

## Props

| Prop            | Type                 | Default  | Description                                       |
| --------------- | -------------------- | -------- | ------------------------------------------------- |
| `items`         | `ActivityCardItem[]` | required | List of items (newest first).                     |
| `title`         | `string`             | -        | Card title, e.g. "Updates".                       |
| `maxVisible`    | `number`             | `6`      | Max activities shown in the card before overflow. |
| `overflowLabel` | `"more" \| "count"`  | `"more"` | "N more activities" vs "+N".                      |
| `groupBy`       | `"none" \| "day"`    | `"none"` | Optional grouping by day.                         |
| `className`     | `string`             | -        | Applied to the card root.                         |

Each activity must include: `id`, `description`, `timestamp` (Date or string). Optional: `actor` (`{ name, avatarUrl? }`) — omit for system events with no specific actor (initials fallback when `avatarUrl` is absent).

***

## Compound API

Use the compound API when you need fully custom item rendering — custom icons, links, badges, or mixed item kinds. Items still must satisfy `ActivityCardBaseItem` (`id` + `timestamp`). You extend `ActivityCardBaseItem` with any additional fields you need.

### Import

```tsx
import { ActivityCard, type ActivityCardBaseItem } from "@tailor-platform/app-shell";
```

### Parts

| Part                 | Description                                                                                                                                     |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `ActivityCard.Root`  | Outer card container. Accepts the same `items`, `title`, `maxVisible`, `overflowLabel`, `groupBy` props as the standalone API, plus `children`. |
| `ActivityCard.Items` | Iterates over items and renders each via a render-prop children function. Generic over your item type.                                          |
| `ActivityCard.Item`  | A single row in the timeline. Accepts an optional `indicator` (any `ReactNode`) for the left column.                                            |

### ActivityCard.Root Props

| Prop            | Type                | Default  | Description                                                           |
| --------------- | ------------------- | -------- | --------------------------------------------------------------------- |
| `items`         | `T[]`               | required | List of items (newest first). `T` must extend `ActivityCardBaseItem`. |
| `title`         | `string`            | -        | Card title, e.g. "Updates".                                           |
| `maxVisible`    | `number`            | `6`      | Max items shown in the card before overflow.                          |
| `overflowLabel` | `"more" \| "count"` | `"more"` | "N more activities" vs "+N".                                          |
| `groupBy`       | `"none" \| "day"`   | `"none"` | Optional grouping by day.                                             |
| `className`     | `string`            | -        | Applied to the card root.                                             |
| `children`      | `React.ReactNode`   | required | Must contain `ActivityCard.Items`.                                    |

### ActivityCard.Item Props

| Prop        | Type              | Default | Description                                                                                |
| ----------- | ----------------- | ------- | ------------------------------------------------------------------------------------------ |
| `indicator` | `React.ReactNode` | -       | Element rendered in the left column (e.g. Avatar, icon). Omit for a default timeline node. |
| `children`  | `React.ReactNode` | -       | Content for the item row (text, badges, links, etc.).                                      |
| `className` | `string`          | -       | Additional CSS classes.                                                                    |

### Example

```tsx
import { ActivityCard, type ActivityCardBaseItem } from "@tailor-platform/app-shell";

interface MyItem extends ActivityCardBaseItem {
  kind: "approval" | "update";
  label?: string;
  message?: string;
}

const items: MyItem[] = [
  { id: "1", timestamp: new Date(), kind: "approval", label: "PO approved" },
  { id: "2", timestamp: new Date(), kind: "update", message: "Status changed to CONFIRMED" },
];

<ActivityCard.Root items={items} title="Updates" groupBy="day">
  <ActivityCard.Items<MyItem>>
    {(item) =>
      item.kind === "approval" ? (
        <ActivityCard.Item indicator={<ApprovedIcon />}>
          <p>{item.label}</p>
        </ActivityCard.Item>
      ) : (
        <ActivityCard.Item>
          <p>{item.message}</p>
        </ActivityCard.Item>
      )
    }
  </ActivityCard.Items>
</ActivityCard.Root>;
```

***

## See also

* [Avatar](avatar) — underlying avatar primitive used for profile images and initials

---

---
url: https://docs.tailor.tech/app-shell/components/alert.md
description: Contextual status messages with automatic variant icons
---

# Alert

The `Alert` component is a compound component for displaying contextual status messages. It automatically renders a matching icon for each variant and supports optional action buttons and dismiss behavior.

[Live preview in the UI Catalogue →](https://ui.tailor.tech/components/alert)

## Import

```tsx
import { Alert } from "@tailor-platform/app-shell";
```

## Basic Usage

```tsx
<Alert.Root variant="success">
  <Alert.Title>Saved</Alert.Title>
  <Alert.Description>Your changes have been saved.</Alert.Description>
</Alert.Root>
```

## Sub-components

| Sub-component       | Description                                       |
| ------------------- | ------------------------------------------------- |
| `Alert.Root`        | Container with variant styling and automatic icon |
| `Alert.Title`       | Bold title line of the alert                      |
| `Alert.Description` | Additional descriptive text below the title       |

## Props

### Alert.Root Props

| Prop          | Type                                                       | Default     | Description                                          |
| ------------- | ---------------------------------------------------------- | ----------- | ---------------------------------------------------- |
| `variant`     | `"neutral" \| "success" \| "warning" \| "error" \| "info"` | `"neutral"` | Visual style and automatic icon                      |
| `action`      | `React.ReactNode`                                          | -           | Action element rendered below the description        |
| `dismissible` | `boolean`                                                  | `false`     | Shows a dismiss button; hides the alert when clicked |
| `onDismiss`   | `() => void`                                               | -           | Callback invoked when the dismiss button is clicked  |
| `className`   | `string`                                                   | -           | Additional CSS classes                               |
| `children`    | `React.ReactNode`                                          | -           | `Alert.Title` and/or `Alert.Description`             |

All standard HTML `<div>` props are also accepted.

## Variants

Each variant automatically renders a contextual icon:

```tsx
<Alert.Root variant="neutral">
  <Alert.Title>Note</Alert.Title>
  <Alert.Description>General information.</Alert.Description>
</Alert.Root>

<Alert.Root variant="success">
  <Alert.Title>Success</Alert.Title>
  <Alert.Description>Operation completed successfully.</Alert.Description>
</Alert.Root>

<Alert.Root variant="warning">
  <Alert.Title>Warning</Alert.Title>
  <Alert.Description>Proceed with caution.</Alert.Description>
</Alert.Root>

<Alert.Root variant="error">
  <Alert.Title>Error</Alert.Title>
  <Alert.Description>Something went wrong.</Alert.Description>
</Alert.Root>

<Alert.Root variant="info">
  <Alert.Title>Info</Alert.Title>
  <Alert.Description>Here is some useful information.</Alert.Description>
</Alert.Root>
```

| Variant   | Automatic Icon      | Color palette   |
| --------- | ------------------- | --------------- |
| `neutral` | Message circle icon | Muted surface   |
| `success` | Check circle icon   | Green           |
| `warning` | Alert triangle icon | Yellow          |
| `error`   | X circle icon       | Red/destructive |
| `info`    | Info icon           | Blue            |

## With Action Button

Use the `action` prop to render an action element below the description:

```tsx
<Alert.Root
  variant="warning"
  action={
    <Button size="sm" variant="outline">
      Review
    </Button>
  }
>
  <Alert.Title>Review Required</Alert.Title>
  <Alert.Description>This record has pending changes that need review.</Alert.Description>
</Alert.Root>
```

## Dismissible Alert

Set `dismissible` to show a close button. Use `onDismiss` to react when the alert is dismissed:

```tsx
<Alert.Root variant="info" dismissible onDismiss={() => markAlertRead(alertId)}>
  <Alert.Title>New Feature Available</Alert.Title>
  <Alert.Description>Check out the new dashboard layout in Settings.</Alert.Description>
</Alert.Root>
```

> **Note:** When `dismissible` is `true`, clicking the close button hides the alert via internal state. The `onDismiss` callback fires after the alert is hidden.

## Examples

### Form Validation Error

```tsx
function OrderForm() {
  const [error, setError] = useState<string | null>(null);

  return (
    <form>
      {error && (
        <Alert.Root variant="error" dismissible onDismiss={() => setError(null)}>
          <Alert.Title>Submission Failed</Alert.Title>
          <Alert.Description>{error}</Alert.Description>
        </Alert.Root>
      )}
      {/* form fields */}
    </form>
  );
}
```

### Success Confirmation

```tsx
<Alert.Root variant="success">
  <Alert.Title>Invoice Created</Alert.Title>
  <Alert.Description>Invoice #INV-0042 has been sent to the customer.</Alert.Description>
</Alert.Root>
```

### Warning with Action

```tsx
<Alert.Root
  variant="warning"
  action={
    <Button size="sm" variant="outline" onClick={() => navigate("/settings/billing")}>
      Update Billing
    </Button>
  }
>
  <Alert.Title>Payment Method Expiring</Alert.Title>
  <Alert.Description>Your credit card on file expires at the end of this month.</Alert.Description>
</Alert.Root>
```

## Accessibility

* The root element has `role="alert"` so screen readers announce the message.
* The dismiss button has `aria-label="Dismiss"`.
* Variant icons are marked `aria-hidden` and are decorative only — the text content carries the meaning.

## Styling

Alerts use Tailwind CSS classes prefixed with `astw:`. Customize appearance using:

1. **Using `className`** on `Alert.Root` for additional styles
2. **Using `alertVariants`** utility to apply variant classes to custom elements

```tsx
import { alertVariants } from "@tailor-platform/app-shell";
import { cn } from "@/lib/utils";

<div className={cn(alertVariants({ variant: "info" }), "astw:my-4")}>Custom alert container</div>;
```

## Related Components

* [Badge](badge) - Inline status labels
* [Button](button) - Use as action element inside alerts

---

---
url: https://docs.tailor.tech/app-shell/components/app-shell.md
description: >-
  The root component that provides routing, navigation, and theming for your
  application
---

# AppShell

`AppShell` is the root component that wires together routing, navigation, authentication, and theming for your AppShell application. It should wrap your entire application layout.

[Live preview in the UI Catalogue →](https://ui.tailor.tech/components/app-shell)

## Import

```tsx
import { AppShell } from "@tailor-platform/app-shell";
```

## Basic Usage

```tsx
import { AppShell, SidebarLayout, defineModule } from "@tailor-platform/app-shell";

const modules = [
  defineModule({
    path: "dashboard",
    component: DashboardPage,
    meta: { title: "Dashboard" },
  }),
];

function App() {
  return (
    <AppShell title="My ERP App" basePath="/app" modules={modules}>
      <SidebarLayout />
    </AppShell>
  );
}
```

## Props

### title

* **Type:** `string` (optional)
* **Description:** Application title displayed in the sidebar header. Also used as the browser tab title suffix — AppShell keeps `document.title` in sync with the active route as `"<page> · <title>"`, where `<page>` is the current breadcrumb leaf (including any [`useOverrideBreadcrumb`](../api/use-override-breadcrumb) override). When omitted, the tab shows just the page name.

```tsx
<AppShell title="My ERP App" modules={modules}>
  {/* ... */}
</AppShell>
```

### icon

* **Type:** `React.ReactNode` (optional)
* **Description:** Application icon displayed in the sidebar header

```tsx
import { Building } from "lucide-react";

<AppShell title="My App" icon={<Building />} modules={modules}>
  {/* ... */}
</AppShell>;
```

### favicon

* **Type:** `string` (optional)
* **Default:** Bundled default favicon set
* **Description:** Browser-tab favicon href. Accepts any value valid for `<link rel="icon">` — a public-path URL (e.g. `/favicon.ico`) or a data URI. When provided, AppShell renders a single `<link rel="icon">` with this href, replacing the default favicon set.

When `favicon` is omitted and the host page declares no `<link rel="icon">`, AppShell automatically injects a small default favicon set as embedded data URIs (no asset-copy step required):

* 16×16 PNG tab icon
* 32×32 PNG tab icon
* 180×180 Apple touch icon (covers "Add to Home Screen" on iOS and Android)

If the host page already declares a `<link rel="icon">`, AppShell leaves it untouched.

```tsx
<AppShell favicon="/favicon.ico" modules={modules}>
  {/* ... */}
</AppShell>
```

### basePath

* **Type:** `string` (optional)
* **Default:** `""`
* **Description:** Base path prefix for all routes

```tsx
// Routes will be /app/dashboard, /app/products, etc.
<AppShell basePath="/app" modules={modules}>
  {/* ... */}
</AppShell>

// Routes will be /dashboard, /products, etc.
<AppShell basePath="" modules={modules}>
  {/* ... */}
</AppShell>
```

### modules

* **Type:** `Module[]` (required when not using file-based routing)
* **Description:** Array of module definitions that define your application structure

```tsx
import { defineModule, defineResource } from "@tailor-platform/app-shell";

const modules = [
  defineModule({
    path: "products",
    component: ProductsListPage,
    meta: { title: "Products" },
    resources: [
      defineResource({
        path: ":id",
        component: ProductDetailPage,
        meta: { title: "Product Details" },
      }),
    ],
  }),
];

<AppShell modules={modules}>{/* ... */}</AppShell>;
```

[Learn more about Modules and Resources →](../concepts/modules-and-resources)

### rootComponent

* **Type:** `() => React.ReactNode` (optional)
* **Description:** Component to render at the root path (e.g., `/app/`)

```tsx
<AppShell basePath="/app" modules={modules} rootComponent={() => <HomePage />}>
  {/* ... */}
</AppShell>
```

When `rootComponent` is set, the root page is treated as a first-class navigation item: it appears in `DefaultSidebar` and `CommandPalette` just like any other module. The title defaults to the localized `"Home"` / `"ホーム"` if no explicit title is provided.

> **Tip:** For redirects from the root, use a guard with `redirectTo()` instead

```tsx
import { redirectTo } from "@tailor-platform/app-shell";

<AppShell basePath="/app" modules={modules} rootComponent={() => redirectTo("/app/dashboard")}>
  {/* ... */}
</AppShell>;
```

> **Note:** If a module with `path: ""` is present in `modules`, it takes precedence over `rootComponent`.

### settingsResources

* **Type:** `Resource[]` (optional)
* **Description:** Resources to include in the settings menu dropdown

```tsx
import { defineResource } from "@tailor-platform/app-shell";

const settingsResources = [
  defineResource({
    path: "profile",
    component: ProfileSettingsPage,
    meta: { title: "Profile" },
  }),
  defineResource({
    path: "billing",
    component: BillingSettingsPage,
    meta: { title: "Billing" },
  }),
];

<AppShell modules={modules} settingsResources={settingsResources}>
  {/* ... */}
</AppShell>;
```

Settings appear in a dropdown menu in the sidebar header, accessible via the settings icon.

### defaultColorTheme

* **Type:** `"light" | "dark" | "system"` (optional)
* **Default:** `"system"`
* **Description:** Initial color mode applied before any value is loaded from `localStorage`. Does not override a stored user preference. `"system"` follows the OS light/dark setting.

```tsx
<AppShell defaultColorTheme="light" modules={modules}>
  {/* ... */}
</AppShell>
```

The end user's selection (via [`AppearanceSwitcher`](appearance-switcher) or a custom toggle using [`useTheme`](../api/use-theme)) is persisted automatically and takes precedence over this prop on subsequent visits.

### locale

* **Type:** `string` (optional)
* **Default:** Auto-detected from browser, falls back to `"en"`
* **Description:** Locale code for built-in UI strings

```tsx
<AppShell locale="ja" modules={modules}>
  {/* ... */}
</AppShell>
```

Supported locales: `en`, `ja`

[Learn more about Internationalization →](../api/define-i18n-labels)

### timeZone

* **Type:** `string` (optional)
* **Default:** User's local timezone
* **Description:** IANA timezone (e.g. `"America/Los_Angeles"`) used by date/time components as the default for resolving "today" and for `ZonedDateTime` values. When omitted, date/time components fall back to the user's local timezone.

```tsx
<AppShell timeZone="America/Los_Angeles" modules={modules}>
  {/* ... */}
</AppShell>
```

Access the configured timezone in components using [`useTimeZone`](../api/use-time-zone).

### errorBoundary

* **Type:** `ErrorBoundaryComponent` (optional)
* **Description:** Global error boundary component applied to all routes

```tsx
import { useRouteError } from "@tailor-platform/app-shell";

const GlobalErrorBoundary = () => {
  const error = useRouteError() as Error;
  return (
    <div className="astw:p-8">
      <h1 className="astw:text-xl astw:font-bold astw:mb-4">Something went wrong</h1>
      <p className="astw:text-red-600">{error.message}</p>
    </div>
  );
};

<AppShell modules={modules} errorBoundary={GlobalErrorBoundary}>
  {/* ... */}
</AppShell>;
```

> **Note:** Module and resource-level error boundaries take precedence over the global error boundary.

### contextData

* **Type:** `ContextData` (optional)
* **Description:** Custom context data accessible from guards and components via `useAppShell()`

First, define your context data type using module augmentation:

```typescript
// types.d.ts
declare module "@tailor-platform/app-shell" {
  interface AppShellRegister {
    contextData: {
      apiClient: ApiClient;
      currentUser: User | null;
      tenantId: string;
    };
  }
}
```

Then pass the data to AppShell:

```tsx
// App.tsx
<AppShell
  modules={modules}
  contextData={{
    apiClient,
    currentUser,
    tenantId: "tenant-123",
  }}
>
  {/* ... */}
</AppShell>
```

Access the context data in your components:

```tsx
import { useAppShell } from "@tailor-platform/app-shell";

function MyComponent() {
  const { context } = useAppShell();

  // Fully typed!
  const user = context.currentUser;
  const client = context.apiClient;

  return <div>Welcome, {user?.name}</div>;
}
```

Or in guards:

```tsx
import { pass, hidden } from "@tailor-platform/app-shell";

const requireAuth: Guard = ({ context }) => {
  if (!context.currentUser) {
    return redirectTo("/login");
  }
  return pass();
};
```

### searchSources

* **Type:** `readonly SearchSource[]` (optional)
* **Description:** Async search sources wired into the built-in CommandPalette. Each source is activated by typing its `prefix` followed by `:` in the palette. When active, the Actions and Pages sections are hidden and only results from that source are shown. The empty-input state of the palette lists all registered sources in a **Search Modes** section so users can discover them with a single click.

```tsx
import { AppShell, type SearchSource } from "@tailor-platform/app-shell";

const searchSources: readonly SearchSource[] = [
  {
    prefix: "ORD",
    title: "Orders",
    search: async (query, { signal }) => {
      const results = await api.searchOrders(query, { signal });
      return results.map((o) => ({
        key: o.id,
        label: o.number,
        path: `/orders/${o.id}`,
      }));
    },
  },
];

<AppShell modules={modules} searchSources={searchSources}>
  <SidebarLayout sidebar={<DefaultSidebar />} />
</AppShell>;
```

See [`SearchSource`](command-palette.md#searchsource) for the full type reference.

> **Note:** `DefaultSidebar` always renders a **Search** entry that opens the palette regardless of whether `searchSources` is configured. The `Cmd+K` / `Ctrl+K` shortcut also works globally.

### appInfo

* **Type:** `AppInfo` (optional)
* **Description:** Configuration for the built-in `/__appinfo` page, which exposes app metadata and the current AppShell version. The page is excluded from sidebar navigation but appears in the Command Palette as a page entry and includes a copy button for the rendered information.

`AppInfo` has the following shape:

| Property   | Type                      | Description                                    |
| ---------- | ------------------------- | ---------------------------------------------- |
| `metadata` | `readonly AppInfoEntry[]` | Additional rows shown on the `/__appinfo` page |

Each `AppInfoEntry` has:

| Property | Type                                               | Description                     |
| -------- | -------------------------------------------------- | ------------------------------- |
| `label`  | `string`                                           | Display label shown on the page |
| `value`  | `string \| number \| boolean \| null \| undefined` | Value rendered as text          |

```tsx
<AppShell
  title="My App"
  appInfo={{
    metadata: [
      { label: "Environment", value: "staging" },
      { label: "Release", value: "2026.07.16" },
    ],
  }}
  modules={modules}
>
  {/* ... */}
</AppShell>
```

### children

* **Type:** `React.ReactNode` (required)
* **Description:** Layout component that renders your application content

Typically, you'll use `SidebarLayout`:

```tsx
import { SidebarLayout } from "@tailor-platform/app-shell";

<AppShell modules={modules}>
  <SidebarLayout />
</AppShell>;
```

Or create a custom layout:

```tsx
<AppShell modules={modules}>
  <CustomLayout />
</AppShell>
```

## File-Based Routing Mode

When using the Vite plugin for file-based routing, use `AppShell` exactly as you would without the plugin — no `modules` prop required. The plugin intercepts the `@tailor-platform/app-shell` import and wraps `AppShell` with pages pre-configured via `AppShell.WithPages()` internally.

```tsx
// App.tsx
import { AppShell, SidebarLayout, DefaultSidebar } from "@tailor-platform/app-shell";

// No modules prop needed — the plugin injects pages automatically
<AppShell title="My App">
  <SidebarLayout sidebar={<DefaultSidebar />} />
</AppShell>;
```

> **Note:** `AppShell.WithPages` is an internal method used by the Vite plugin. Do not call it directly in application code.

[Learn more about File-Based Routing →](../concepts/file-based-routing)

## Complete Example

Here's a complete example with all common features:

```tsx
import {
  AppShell,
  SidebarLayout,
  defineModule,
  defineResource,
  useRouteError,
} from "@tailor-platform/app-shell";
import { Building } from "lucide-react";

// Define context data type
declare module "@tailor-platform/app-shell" {
  interface AppShellRegister {
    contextData: {
      currentUser: User | null;
    };
  }
}

// Error boundary
const ErrorBoundary = () => {
  const error = useRouteError() as Error;
  return (
    <div className="astw:p-8">
      <h1 className="astw:text-xl astw:font-bold">Error</h1>
      <p>{error.message}</p>
    </div>
  );
};

// Modules
const modules = [
  defineModule({
    path: "dashboard",
    component: DashboardPage,
    meta: { title: "Dashboard" },
  }),
  defineModule({
    path: "products",
    component: ProductsPage,
    meta: { title: "Products" },
    resources: [
      defineResource({
        path: ":id",
        component: ProductDetailPage,
      }),
    ],
  }),
];

// Settings
const settingsResources = [
  defineResource({
    path: "profile",
    component: ProfilePage,
    meta: { title: "Profile" },
  }),
];

// App
function App() {
  const currentUser = useCurrentUser();

  return (
    <AppShell
      title="My ERP App"
      icon={<Building />}
      favicon="/favicon.ico"
      basePath="/app"
      modules={modules}
      settingsResources={settingsResources}
      locale="en"
      defaultColorTheme="system"
      errorBoundary={ErrorBoundary}
      contextData={{ currentUser }}
    >
      <SidebarLayout />
    </AppShell>
  );
}

export default App;
```

## Related Components

* [SidebarLayout](sidebar-layout) - Default layout with sidebar navigation
* [CommandPalette](command-palette) - Keyboard-driven navigation

## Related Concepts

* [Modules and Resources](../concepts/modules-and-resources) - Application structure
* [Authentication](../concepts/authentication) - User authentication setup
* [Routing and Navigation](../concepts/routing-navigation) - Navigation between pages

## API Reference

* [defineModule](../api/define-module) - Define a top-level module
* [defineResource](../api/define-resource) - Define a nested resource
* [useAppShell](../api/use-app-shell) - Access AppShell context
* [useResolvedLocale](../api/use-resolved-locale) - Access the full BCP-47 locale and language code
* [useTimeZone](../api/use-time-zone) - Access the configured IANA timezone

---

---
url: https://docs.tailor.tech/app-shell/components/appearance-switcher.md
description: Pre-built dropdown for toggling the application color theme
---

# AppearanceSwitcher

`AppearanceSwitcher` is a ready-made button and dropdown menu that lets end users switch between **Light**, **Dark**, and **System** color modes. It reads and writes the theme through [`useTheme`](../api/use-theme) and requires no configuration.

## Import

```tsx
import { AppearanceSwitcher } from "@tailor-platform/app-shell";
```

## Basic Usage

```tsx
<AppearanceSwitcher />
```

Drop it anywhere inside an `<AppShell>` tree — for example in a sidebar footer or a settings toolbar.

It is also the default action in [`SidebarLayout.DefaultHeader`](default-header). Because `DefaultHeader`'s `actions` prop **replaces** the entire right-hand cluster, you must include `<AppearanceSwitcher />` in your `actions` array if you customize the header and still want the switcher:

```tsx
<SidebarLayout
  header={
    <SidebarLayout.DefaultHeader
      actions={[<NotificationBell key="bell" />, <AppearanceSwitcher key="appearance" />]}
    />
  }
/>
```

## Props

`AppearanceSwitcher` accepts no props. Color theme state is managed internally via `useTheme`.

## Behavior

* Renders a palette icon button. Clicking it opens a popover menu with three radio options: **Light**, **Dark**, and **System**.
* The active option is highlighted.
* When **System** is selected, the button tooltip shows the currently resolved mode (e.g. *"Following system — currently dark"*).
* The selected preference is persisted to `localStorage` (key `appshell-ui-theme`) and restored on subsequent visits.

## Example: Sidebar Footer

```tsx
import {
  AppShell,
  SidebarLayout,
  DefaultSidebar,
  AppearanceSwitcher,
} from "@tailor-platform/app-shell";

function CustomSidebar() {
  return (
    <DefaultSidebar
      footer={
        <div className="flex items-center justify-end p-2">
          <AppearanceSwitcher />
        </div>
      }
    />
  );
}

function App() {
  return (
    <AppShell title="My App" modules={modules}>
      <SidebarLayout sidebar={<CustomSidebar />} />
    </AppShell>
  );
}
```

## Related

* [useTheme](../api/use-theme) — hook to read and set the color theme programmatically
* [Styling & Theming](../concepts/styling-theming) — color themes and palette overview

---

---
url: https://docs.tailor.tech/app-shell/components/attachment.md
description: >-
  Attachment list with upload, previews, and per-item actions; compose with Card
  for titles and surface styling
---

# Attachment

`Attachment` is a reusable file/image attachment surface for ERP detail pages. It provides upload affordance (click or drag-and-drop onto the upload tile), optional helper text via `uploadHint`, image/file preview tiles, and per-item menu actions for download and delete.

[Live preview in the UI Catalogue →](https://ui.tailor.tech/components/attachment)

## Import

```tsx
import { Attachment, useAttachment } from "@tailor-platform/app-shell";
import type { AttachmentItem, AttachmentOperation } from "@tailor-platform/app-shell";
```

## Basic usage

Use `useAttachment` to manage upload/delete state locally, then flush operations to your backend on submit via `applyChanges`. Spread the returned `props` directly onto `<Attachment />`.

```tsx
import { Attachment, Card, useAttachment } from "@tailor-platform/app-shell";
import type { AttachmentOperation } from "@tailor-platform/app-shell";

function ProductForm() {
  const { props, applyChanges } = useAttachment({
    initialItems: existingAttachments,
    accept: "image/*,.pdf",
  });

  async function handleSubmit() {
    await applyChanges(async (operations) => {
      for (const op of operations) {
        if (op.type === "upload") await uploadToServer(op.file);
        if (op.type === "delete") await deleteFromServer(op.item.id);
      }
    });
  }

  return (
    <Card.Root>
      <Card.Header title="Product images" description="PNG, JPG, or PDF — max 10 MB per file." />
      <Card.Content>
        <Attachment
          {...props}
          uploadLabel="Upload image"
          uploadHint="PNG, JPG, or PDF — max 10 MB per file."
          onDownload={(item) => console.log("download", item)}
        />
      </Card.Content>
    </Card.Root>
  );
}
```

## Composition with Card

* Use **`Card.Header`** for the section title and description.
* Use **`Card.Root`** (and usually **`Card.Content`**) for border, radius, shadow, and padding around the attachment block.

## useAttachment

`useAttachment` tracks pending uploads and deletes locally until `applyChanges` is called. It handles object URL creation/revocation for image previews automatically.

### Options

| Option         | Type               | Default | Description                                  |
| -------------- | ------------------ | ------- | -------------------------------------------- |
| `initialItems` | `AttachmentItem[]` | `[]`    | Existing items to populate on mount          |
| `accept`       | `string`           | -       | Accepted file types passed to the file input |
| `disabled`     | `boolean`          | `false` | Disable upload and item actions              |

### Return value

| Field          | Type                                                                   | Description                                                                                                                                           |
| -------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `props`        | `{ items, onUpload, onDelete, accept, disabled }`                      | Spread directly onto `<Attachment />`                                                                                                                 |
| `applyChanges` | `(fn: (ops: AttachmentOperation[]) => Promise<void>) => Promise<void>` | Flush buffered operations to your backend; clears the buffer after `fn` resolves. If `fn` throws, the buffer is preserved so the call can be retried. |
| `isApplying`   | `boolean`                                                              | `true` while `applyChanges` is in progress. Use to show a loading indicator during form submission.                                                   |

> **Upload ordering:** newly uploaded files are prepended to `items`, so the most recent uploads appear first in the tile list.

## AttachmentOperation

Represents a single pending change buffered by `useAttachment`. Passed as an array to the `applyChanges` callback.

```ts
type AttachmentOperation =
  | { type: "upload"; file: File; item: AttachmentItem }
  | { type: "delete"; item: AttachmentItem };
```

## AttachmentItem

```ts
interface AttachmentItem {
  id: string;
  fileName: string;
  mimeType: string;
  previewUrl?: string;
}
```

## Attachment props

| Prop          | Type                             | Default             | Description                                                                                   |
| ------------- | -------------------------------- | ------------------- | --------------------------------------------------------------------------------------------- |
| `items`       | `AttachmentItem[]`               | `[]`                | Attachment list rendered as preview tiles                                                     |
| `onUpload`    | `(files: File[]) => void`        | *(required)*        | Called when files are selected or dropped on the upload tile                                  |
| `onDelete`    | `(item: AttachmentItem) => void` | *(required)*        | Called when Delete is chosen in a preview menu                                                |
| `onDownload`  | `(item: AttachmentItem) => void` | -                   | Called when Download is chosen in a preview menu                                              |
| `uploadLabel` | `string`                         | `"Click to upload"` | Primary label on the upload tile                                                              |
| `uploadHint`  | `string`                         | -                   | Supporting text below the upload label                                                        |
| `accept`      | `string`                         | -                   | Accepted file types for hidden file input                                                     |
| `disabled`    | `boolean`                        | `false`             | Disables upload, drop, and hides per-item menu actions                                        |
| `className`   | `string`                         | -                   | Classes on the root (e.g. padding); component has no outer border or inset padding by default |

## Behavior

* **Layout**: hidden file input, then the tile row—no built-in page inset.
* **Image items** (`mimeType` starts with `image/`) render as 120×120 image thumbnails when `previewUrl` loads; otherwise a fallback tile.
* **Non-image items** render as 120×120 file tiles with icon and wrapped filename.
* **Drag and drop** applies only to the **upload tile** (dashed “click to upload” control), not the full attachment block. Use the file picker from the same tile for click-to-upload.
* **Disabled state** (`disabled={true}`): the upload tile and drop target are hidden; per-item menu actions are also hidden.
* **Item actions** are available through the preview menu (`Download`, `Delete`) when not disabled.

### DOM

* Root: `data-slot="attachment"`
* Content wrapper: `data-slot="attachment-content"`

## Related components

* [Card](card)
* [Button](button)
* [Menu](menu)

---

---
url: https://docs.tailor.tech/app-shell/components/autocomplete.md
description: >-
  Text input with a suggestion list — value is the raw input string, not a
  discrete item selection
---

# Autocomplete

The `Autocomplete` component provides a free-text input with a suggestion list. Unlike `Select` and `Combobox`, the component value is the raw input string — not a discrete item selection. For async suggestions use `Autocomplete.Async`. For custom compositions use `Autocomplete.Parts`.

[Live preview in the UI Catalogue →](https://ui.tailor.tech/components/autocomplete)

## Import

```tsx
import { Autocomplete } from "@tailor-platform/app-shell";
```

## Basic Usage

```tsx
<Autocomplete
  items={["Apple", "Banana", "Cherry"]}
  placeholder="Type a fruit..."
  onValueChange={(value) => console.log(value)}
/>
```

## Props

### Autocomplete Props

| Prop              | Type                      | Default         | Description                                                         |
| ----------------- | ------------------------- | --------------- | ------------------------------------------------------------------- |
| `items`           | `I[]`                     | -               | Suggestion items. May be a flat array or an array of `ItemGroup<T>` |
| `placeholder`     | `string`                  | -               | Placeholder text for the input                                      |
| `emptyText`       | `string`                  | `"No results."` | Text shown when no items match                                      |
| `value`           | `string`                  | -               | Controlled value (raw input string)                                 |
| `defaultValue`    | `string`                  | -               | Initial value (uncontrolled)                                        |
| `onValueChange`   | `(value: string) => void` | -               | Called when the value changes                                       |
| `mapItem`         | `(item: T) => MappedItem` | -               | Map each item to its label, key, and optional custom render         |
| `className`       | `string`                  | -               | Additional CSS classes for the root container                       |
| `disabled`        | `boolean`                 | `false`         | Disables the autocomplete                                           |
| `aria-label`      | `string`                  | -               | Accessible name for the input. Use when there is no visible label   |
| `aria-labelledby` | `string`                  | -               | ID of the element(s) that label the input                           |
| `id`              | `string`                  | -               | ID applied to the combobox input element                            |

### MappedItem

```ts
interface MappedItem {
  label: string; // Display text, used for filtering and a11y
  key?: string; // React key. Defaults to label
  render?: React.ReactNode; // Custom JSX to render in the dropdown
}
```

### ItemGroup

```ts
interface ItemGroup<T> {
  label: string;
  items: T[];
}
```

## Grouped Suggestions

```tsx
const cities = [
  { label: "Japan", items: ["Tokyo", "Osaka", "Kyoto"] },
  { label: "France", items: ["Paris", "Lyon", "Marseille"] },
];

<Autocomplete items={cities} placeholder="Search cities..." />;
```

## Object Items with mapItem

When items are objects, use `mapItem` to tell the component how to display them. The selected value is the item's `label` string returned by `mapItem`:

```tsx
type City = { code: string; name: string };

const cities: City[] = [
  { code: "TYO", name: "Tokyo" },
  { code: "OSA", name: "Osaka" },
];

<Autocomplete
  items={cities}
  mapItem={(city) => ({ label: city.name, key: city.code })}
  placeholder="Search cities..."
  onValueChange={(name) => console.log(name)} // receives "Tokyo", "Osaka", etc.
/>;
```

## Async Suggestions

Use `Autocomplete.Async` to fetch suggestions as the user types. The fetcher is called on each keystroke (debounced). When the dropdown first opens or the input is cleared, the fetcher receives `null` as the query — return initial/default suggestions for `null`, or return an empty array to show nothing until the user starts typing.

```tsx
import { type AutocompleteAsyncFetcher } from "@tailor-platform/app-shell";

const fetcher: AutocompleteAsyncFetcher<string> = async (query, { signal }) => {
  const res = await fetch(`/api/suggestions?q=${query ?? ""}`, { signal });
  return res.json();
};

<Autocomplete.Async
  fetcher={fetcher}
  placeholder="Search..."
  onValueChange={(value) => console.log(value)}
/>;
```

### Autocomplete.Async Props

Accepts all the same props as `Autocomplete` except `items`, plus:

| Prop           | Type                          | Default                    | Description                                                        |
| -------------- | ----------------------------- | -------------------------- | ------------------------------------------------------------------ |
| `fetcher`      | `AutocompleteAsyncFetcher<T>` | -                          | Fetcher called on each keystroke (debounced by default)            |
| `loadingText`  | `string`                      | `"Loading..."`             | Text shown while loading                                           |
| `errorText`    | `string`                      | `"Couldn't load results."` | Message shown in the popover when the fetcher fails (with Retry)   |
| `retryText`    | `string`                      | `"Retry"`                  | Label for the retry button in the error state                      |
| `onFetchError` | `(error: unknown) => void`    | -                          | Called once per outage when a fetch fails (logging/error tracking) |

### AutocompleteAsyncFetcher

```ts
type AutocompleteAsyncFetcher<T> =
  | ((query: string | null, options: { signal: AbortSignal }) => Promise<T[]>)
  | {
      fn: (query: string | null, options: { signal: AbortSignal }) => Promise<T[]>;
      debounceMs: number;
    };
```

`query` is `null` when the user has not typed anything (e.g. the dropdown was just opened or the input was cleared). Pass `{ fn, debounceMs }` to customize the debounce delay.

### Error handling

If the fetcher throws or rejects, `Autocomplete.Async` renders a built-in inline error state in the popover — the `errorText` message plus a **Retry** button that re-runs the last fetch — instead of the misleading "No results." empty state. Aborted/superseded requests are ignored, and announcements are de-duped per outage. Pass `onFetchError` to run a side effect (logging, toast) — it fires once per outage and re-arms after the next successful fetch.

## Low-level Primitives

`Autocomplete.Parts` exposes styled sub-components and hooks for fully custom compositions:

```tsx
const {
  Root,
  Value,
  InputGroup,
  Input,
  Trigger,
  Content,
  List,
  Item,
  Empty,
  Clear,
  Group,
  GroupLabel,
  Collection,
  Status,
} = Autocomplete.Parts;
```

## Form submission

Inside a `Field.Root`, the field's `name` identifies the value and these props are unnecessary —
see [Form](form). They matter for **native** submission: a plain `<form>`, `new FormData(form)`,
or a server action.

| Prop       | Type                          | Default | Description                                                                                       |
| ---------- | ----------------------------- | ------- | ------------------------------------------------------------------------------------------------- |
| `name`     | `string`                      | -       | Names the input for native submission. **Ignored inside a `Field.Root`** — the field's name wins. |
| `form`     | `string`                      | -       | `id` of the owning form, when the control is rendered outside it.                                 |
| `required` | `boolean`                     | `false` | Blocks submission until a value is chosen, surfacing the matching `Field.Error`.                  |
| `inputRef` | `React.Ref<HTMLInputElement>` | -       | Ref to the underlying text input (use for React Hook Form's `field.ref`).                         |

Autocomplete's value is the raw input string, so no value-serialisation hook is needed.

## Examples

### Controlled Autocomplete

```tsx
const [query, setQuery] = useState("");

<Autocomplete items={suggestions} value={query} onValueChange={setQuery} placeholder="Search..." />;
```

### Address Input with Async Suggestions

```tsx
const fetcher: AutocompleteAsyncFetcher<string> = async (query, { signal }) => {
  if (!query) return [];
  const res = await fetch(`/api/address-lookup?q=${encodeURIComponent(query)}`, { signal });
  return res.json();
};

<Autocomplete.Async
  fetcher={fetcher}
  placeholder="Start typing an address..."
  onValueChange={(address) => form.setValue("address", address)}
/>;
```

### Async with Parts (custom composition)

Combine `Autocomplete.useAsync` with `Autocomplete.Parts` for full control over layout and rendering:

`Autocomplete.useAsync` accepts the same options as `Autocomplete.Async` (including `onFetchError`) and returns:

| Property  | Type         | Description                                             |
| --------- | ------------ | ------------------------------------------------------- |
| `items`   | `T[]`        | Currently loaded items                                  |
| `loading` | `boolean`    | Whether a fetch is in progress                          |
| `error`   | `unknown`    | The error thrown by the last fetch, if any              |
| `retry`   | `() => void` | Re-runs the last fetch (use to build a custom retry UI) |

```tsx
const suggestions = Autocomplete.useAsync({
  fetcher: async (query, { signal }) => {
    const res = await fetch(`/api/suggestions?q=${query ?? ""}`, { signal });
    return res.json();
  },
  onFetchError: (error) => reportError(error),
});

<Autocomplete.Parts.Root {...suggestions} filter={null}>
  <Autocomplete.Parts.InputGroup>
    <Autocomplete.Parts.Input placeholder="Search..." />
    <Autocomplete.Parts.Clear />
  </Autocomplete.Parts.InputGroup>
  <Autocomplete.Parts.Content>
    <Autocomplete.Parts.List>
      {suggestions.items.map((item) => (
        <Autocomplete.Parts.Item key={item} value={item}>
          {item}
        </Autocomplete.Parts.Item>
      ))}
      <Autocomplete.Parts.Empty>
        {suggestions.error ? (
          <button onClick={suggestions.retry}>Couldn't load. Retry</button>
        ) : suggestions.loading ? (
          "Loading..."
        ) : (
          "No results."
        )}
      </Autocomplete.Parts.Empty>
    </Autocomplete.Parts.List>
  </Autocomplete.Parts.Content>
</Autocomplete.Parts.Root>;
```

## Accessibility

* Input is keyboard accessible with arrow key navigation
* Pressing `Escape` closes the suggestion list
* Selecting a suggestion fills the input with the item's label
* When used standalone (no visible `<label>`), give the input an accessible name with `aria-label` or `aria-labelledby` — otherwise screen readers announce only the current value:

```tsx
<Autocomplete items={items} aria-label="City search" />
```

## Related Components

* [Select](select) - Non-searchable discrete item selection
* [Combobox](combobox) - Searchable combobox that returns discrete items
* [Input](input) - Plain text input without suggestions

---

---
url: https://docs.tailor.tech/app-shell/components/avatar.md
description: User avatar with image and fallback (Base UI)
---

# Avatar

The `Avatar` component wraps Base UI Avatar: a root container with an optional image and fallback content (typically initials) when the image is missing or fails to load.

[Live preview in the UI Catalogue →](https://ui.tailor.tech/components/avatar)

## Import

```tsx
import { Avatar } from "@tailor-platform/app-shell";
```

## Basic usage

```tsx
<Avatar.Root>
  <Avatar.Image src="/user.png" alt="Jane Doe" />
  <Avatar.Fallback>JD</Avatar.Fallback>
</Avatar.Root>
```

## Parts

| Part              | Description                                                |
| ----------------- | ---------------------------------------------------------- |
| `Avatar.Root`     | Outer container; applies size and surface styles.          |
| `Avatar.Image`    | `<img>` for the photo; hidden when not loaded or on error. |
| `Avatar.Fallback` | Shown when there is no image or the image failed to load.  |

## Root props

| Prop        | Type                                | Default     | Description                |
| ----------- | ----------------------------------- | ----------- | -------------------------- |
| `size`      | `"xs" \| "sm" \| "default" \| "lg"` | `"default"` | Circle size (28px default) |
| `className` | `string`                            | —           | Extra classes              |
| `children`  | `React.ReactNode`                   | —           | Image + fallback           |

`Avatar.Root` forwards other stable props from Base UI (for example `aria-hidden`, `style`) and standard HTML attributes for the `<span>` root.

## Sizes

The smallest size, `xs` (16px), is intended for compact/inline contexts and single-glyph or icon content; two-letter initials will be cramped.

```tsx
<Avatar.Root size="xs">
  <Avatar.Fallback>A</Avatar.Fallback>
</Avatar.Root>
<Avatar.Root size="sm">
  <Avatar.Fallback>AB</Avatar.Fallback>
</Avatar.Root>
<Avatar.Root size="default">
  <Avatar.Fallback>CD</Avatar.Fallback>
</Avatar.Root>
<Avatar.Root size="lg">
  <Avatar.Fallback>EF</Avatar.Fallback>
</Avatar.Root>
```

## Types

`AvatarProps` is the props type for `Avatar.Root` (includes `size` and Base UI root props). Import when wrapping or composing:

```tsx
import { Avatar, type AvatarProps } from "@tailor-platform/app-shell";
```

## `avatarVariants`

The same size styles used by `Avatar.Root` are exported as `avatarVariants` (for example if you need to mirror avatar dimensions in layout code). Prefer the `size` prop on `Avatar.Root` for normal use.

---

---
url: https://docs.tailor.tech/app-shell/components/badge.md
description: Display status, labels, and tags with customizable variants
---

# Badge

The `Badge` component displays status indicators, labels, and tags with multiple style variants. It's commonly used to show document status, priority levels, or categorical information.

[Live preview in the UI Catalogue →](https://ui.tailor.tech/components/badge)

## Import

```tsx
import { Badge, type BadgeVariant, type BadgeOptions } from "@tailor-platform/app-shell";
```

## Basic Usage

```tsx
<Badge>Default</Badge>
<Badge variant="success">Success</Badge>
<Badge variant="warning">Warning</Badge>
<Badge variant="error">Error</Badge>
<Badge variant="info">Info</Badge>
<Badge variant="subtle-success">Subtle Success</Badge>
<Badge variant="subtle-warning">Subtle Warning</Badge>
<Badge variant="subtle-error">Subtle Error</Badge>
<Badge variant="subtle-info">Subtle Info</Badge>
```

## Variants

### Solid and Subtle Variants

Filled variants for high emphasis, plus subtle variants for lower-emphasis status labels:

```tsx
<Badge variant="default">Default</Badge>
<Badge variant="success">Approved</Badge>
<Badge variant="warning">Pending</Badge>
<Badge variant="error">Rejected</Badge>
<Badge variant="neutral">Draft</Badge>
<Badge variant="info">New</Badge>
<Badge variant="subtle-success">Matched</Badge>
<Badge variant="subtle-warning">Needs Attention</Badge>
<Badge variant="subtle-error">Needs Review</Badge>
<Badge variant="subtle-info">In Progress</Badge>
```

### Outline Variants with Status Dots

Outlined badges with colored status dots for subtle emphasis:

```tsx
<Badge variant="outline-success">Active</Badge>
<Badge variant="outline-warning">In Progress</Badge>
<Badge variant="outline-error">Failed</Badge>
<Badge variant="outline-info">Info</Badge>
<Badge variant="outline-neutral">Inactive</Badge>
```

## Props

| Prop        | Type              | Default     | Description            |
| ----------- | ----------------- | ----------- | ---------------------- |
| `variant`   | `BadgeVariant`    | `"default"` | Visual style variant   |
| `className` | `string`          | -           | Additional CSS classes |
| `children`  | `React.ReactNode` | -           | Badge content          |

### Badge Variants

```typescript
type BadgeVariant =
  // Solid/subtle variants
  | "default" // Primary color
  | "success" // Green
  | "warning" // Yellow
  | "error" // Red/destructive
  | "neutral" // Gray/secondary
  | "info" // Blue
  | "subtle-success" // Low-emphasis green
  | "subtle-warning" // Low-emphasis yellow
  | "subtle-error" // Low-emphasis red/destructive
  | "subtle-info" // Low-emphasis blue
  // Outline variants with status dots
  | "outline-success"
  | "outline-warning"
  | "outline-error"
  | "outline-info"
  | "outline-neutral";
```

### BadgeOptions

Shared options used by `DataTable` and `DescriptionCard` badge fields:

```typescript
interface BadgeOptions {
  /** Maps each value (stringified) to a Badge variant. Unmapped values use `defaultBadgeVariant`. */
  badgeVariantMap?: Record<string, BadgeVariant>;
  /** Maps each value (stringified) to a display label. Unmapped values render the raw value. */
  badgeLabelMap?: Record<string, string>;
  /** Variant used when the value is not in `badgeVariantMap`. Default: `"outline-neutral"`. */
  defaultBadgeVariant?: BadgeVariant;
}
```

## Examples

### Order Status

```tsx
function OrderStatus({ status }: { status: string }) {
  const variantMap: Record<string, BadgeVariant> = {
    pending: "outline-warning",
    processing: "outline-info",
    shipped: "outline-success",
    delivered: "success",
    cancelled: "outline-error",
  };

  return <Badge variant={variantMap[status] || "neutral"}>{status.toUpperCase()}</Badge>;
}
```

### Priority Badges

```tsx
const priorities = [
  { label: "Low", variant: "outline-neutral" },
  { label: "Medium", variant: "outline-info" },
  { label: "High", variant: "outline-warning" },
  { label: "Critical", variant = "error" },
];

<div className="astw:flex astw:gap-2">
  {priorities.map((p) => (
    <Badge key={p.label} variant={p.variant}>
      {p.label}
    </Badge>
  ))}
</div>;
```

### With Icons

```tsx
import { CheckCircle, AlertCircle, XCircle } from "lucide-react";

<div className="astw:flex astw:gap-2">
  <Badge variant="success">
    <CheckCircle className="astw:w-3 astw:h-3 astw:mr-1" />
    Verified
  </Badge>
  <Badge variant="warning">
    <AlertCircle className="astw:w-3 astw:h-3 astw:mr-1" />
    Review
  </Badge>
  <Badge variant="error">
    <XCircle className="astw:w-3 astw:h-3 astw:mr-1" />
    Blocked
  </Badge>
</div>;
```

### Dynamic Variant Selection

```tsx
interface Product {
  name: string;
  stock: number;
}

function ProductBadge({ product }: { product: Product }) {
  // Determine variant based on stock level
  let variant: BadgeVariant = "success";
  if (product.stock === 0) {
    variant = "error";
  } else if (product.stock < 10) {
    variant = "warning";
  }

  return <Badge variant={variant}>{product.stock} in stock</Badge>;
}
```

### Custom Styling

```tsx
<Badge variant="success" className="astw:text-xs astw:px-3 astw:py-1 astw:uppercase">
  Premium
</Badge>
```

## Visual Reference

### Solid and Subtle Variants

| Variant          | Preview                | Use Case                                   |
| ---------------- | ---------------------- | ------------------------------------------ |
| `default`        | !\[Blue badge]          | Primary actions, default status            |
| `success`        | !\[Green badge]         | Completed, approved, active                |
| `warning`        | !\[Yellow badge]        | Pending, in progress, attention needed     |
| `error`          | !\[Red badge]           | Failed, rejected, critical                 |
| `neutral`        | !\[Gray badge]          | Draft, inactive, disabled                  |
| `info`           | !\[Blue badge]          | Informational, new, in-progress            |
| `subtle-success` | !\[Subtle green badge]  | Low-emphasis completed or matched statuses |
| `subtle-warning` | !\[Subtle yellow badge] | Low-emphasis pending or attention states   |
| `subtle-error`   | !\[Subtle red badge]    | Low-emphasis failures or exceptions        |
| `subtle-info`    | !\[Subtle blue badge]   | Low-emphasis informational or in-progress  |

### Outline Variants

| Variant           | Preview                 | Use Case                   |
| ----------------- | ----------------------- | -------------------------- |
| `outline-success` | !\[Green dot + outline]  | Active, available, healthy |
| `outline-warning` | !\[Orange dot + outline] | In progress, scheduled     |
| `outline-error`   | !\[Red dot + outline]    | Error, unavailable, down   |
| `outline-info`    | !\[Blue dot + outline]   | Information, processing    |
| `outline-neutral` | !\[Gray dot + outline]   | Neutral state, inactive    |

## Accessibility

* Use semantic color meanings consistently (green = success, red = error, etc.)
* Don't rely solely on color to convey information
* Consider adding icons or text labels for clarity
* Badges are non-interactive: they render with the default cursor (not a pointer) and won't suggest clickability, even when placed inside a clickable container such as a `DataTable` row with `onClickRow`

## Usage in DescriptionCard

Badges can be used with DescriptionCard for automatic status rendering:

```tsx
import { DescriptionCard } from "@tailor-platform/app-shell";

<DescriptionCard
  data={orderData}
  fields={[
    {
      type: "badge",
      key: "status",
      label: "Status",
      meta: {
        sentenceCaseBadges: false,
        badgeVariantMap: {
          pending: "outline-warning",
          shipped: "outline-success",
          delivered: "success",
        },
      },
    },
  ]}
/>;
```

[Learn more about DescriptionCard →](description-card)

## Best Practices

### Do:

* ✅ Use consistent variants for the same meaning across your app
* ✅ Keep badge text short (1-2 words)
* ✅ Use outline variants for subtle emphasis
* ✅ Use solid variants for important status indicators

### Don't:

* ❌ Use too many different badge colors (stick to semantic colors)
* ❌ Put long text in badges (use tooltips instead)
* ❌ Make badges clickable without visual indication
* ❌ Use badges for navigation (use links or buttons instead)

## Related Components

* [DescriptionCard](description-card) - Use badges in structured displays
* [Layout](layout) - Organize badges in layouts

## Styling

Badges use Tailwind CSS classes prefixed with `astw:`. Customize appearance by:

1. **Using className prop** for additional styles
2. **Overriding CSS variables** in your theme
3. **Creating custom variants** using the `badgeVariants` utility

```tsx
import { badgeVariants } from "@tailor-platform/app-shell";
import { cn } from "@/lib/utils";

<div className={cn(badgeVariants({ variant: "success" }), "astw:text-lg")}>Custom Badge</div>;
```

---

---
url: https://docs.tailor.tech/app-shell/components/button.md
description: Styled button with multiple variants and sizes
---

# Button

The `Button` component is a styled button with multiple visual variants and sizes. It supports rendering as a custom element via the `render` prop (Base UI render pattern).

[Live preview in the UI Catalogue →](https://ui.tailor.tech/components/button)

## Import

```tsx
import { Button } from "@tailor-platform/app-shell";
```

## Basic Usage

```tsx
<Button>Click me</Button>
<Button variant="outline">Outline</Button>
<Button variant="destructive">Delete</Button>
```

## Props

| Prop        | Type                                                                          | Default     | Description                                       |
| ----------- | ----------------------------------------------------------------------------- | ----------- | ------------------------------------------------- |
| `variant`   | `"default" \| "destructive" \| "outline" \| "secondary" \| "ghost" \| "link"` | `"default"` | Visual style variant                              |
| `size`      | `"default" \| "xs" \| "sm" \| "lg" \| "icon"`                                 | `"default"` | Button size                                       |
| `render`    | `React.ReactElement`                                                          | -           | Custom element to render as (Base UI render prop) |
| `className` | `string`                                                                      | -           | Additional CSS classes                            |
| `children`  | `React.ReactNode`                                                             | -           | Button content                                    |

All standard HTML `<button>` props are also accepted.

## Variants

```tsx
<Button variant="default">Primary Action</Button>
<Button variant="destructive">Delete</Button>
<Button variant="outline">Secondary Action</Button>
<Button variant="secondary">Tertiary</Button>
<Button variant="ghost">Ghost</Button>
<Button variant="link">Link Style</Button>
```

## Sizes

```tsx
<Button size="xs">Extra Small</Button>
<Button size="sm">Small</Button>
<Button size="default">Default</Button>
<Button size="lg">Large</Button>
<Button size="icon"><PlusIcon /></Button>
```

## Render Prop

The `render` prop lets you use the button's styles on a custom element:

```tsx
import { Button } from "@tailor-platform/app-shell";
import { Link } from "@tailor-platform/app-shell";

<Button render={<Link to="/orders" />} variant="outline">
  View Orders
</Button>;
```

This is the Base UI render pattern — the button's class names and event handlers are applied to the rendered element.

## Examples

### Form Actions

```tsx
<div className="astw:flex astw:gap-2 astw:justify-end">
  <Button variant="outline">Cancel</Button>
  <Button>Save Changes</Button>
</div>
```

### Destructive Confirmation

```tsx
<Button variant="destructive" onClick={handleDelete}>
  Delete Order
</Button>
```

### Icon Button

```tsx
import { PlusIcon } from "lucide-react";

<Button size="icon" variant="outline">
  <PlusIcon />
</Button>;
```

## TypeScript

```typescript
import { type ButtonProps } from "@tailor-platform/app-shell";
```

## Styling

Use `buttonVariants` to apply button styles to non-button elements:

```tsx
import { buttonVariants } from "@tailor-platform/app-shell";

<a href="/orders" className={buttonVariants({ variant: "outline", size: "sm" })}>
  View Orders
</a>;
```

## Accessibility

* Buttons render with `cursor: pointer` to signal interactivity consistently across all variants and sizes.
* Disabled buttons suppress the pointer cursor via `pointer-events-none`, so they do not signal clickability.

## Related Components

* [Dialog](dialog) - Use buttons as dialog triggers and actions
* [Sheet](sheet) - Use buttons as sheet triggers
* [Layout](layout) - Use buttons in page header actions

---

---
url: https://docs.tailor.tech/app-shell/components/card.md
description: >-
  General-purpose container with consistent styling using a compound component
  API
---

# Card

`Card` is a general-purpose container component with a compound component API (`Card.Root`, `Card.Header`, `Card.Content`). It provides consistent surface styling (background, border, border-radius, shadow) for grouping related content.

[Live preview in the UI Catalogue →](https://ui.tailor.tech/components/card)

## Import

```tsx
import { Card } from "@tailor-platform/app-shell";
```

## Basic Usage

```tsx
<Card.Root>
  <Card.Header title="Order Details" description="Summary of order #1234" />
  <Card.Content>
    <p>Content goes here</p>
  </Card.Content>
</Card.Root>
```

## Parts

| Part           | Description                                                      |
| -------------- | ---------------------------------------------------------------- |
| `Card.Root`    | Outer container. Renders a `<div>` with surface styling applied. |
| `Card.Header`  | Top section with an optional title and description.              |
| `Card.Content` | Body section with consistent horizontal and bottom padding.      |

## Card.Root Props

`Card.Root` accepts all standard HTML `<div>` props.

| Prop        | Type              | Default | Description            |
| ----------- | ----------------- | ------- | ---------------------- |
| `className` | `string`          | -       | Additional CSS classes |
| `children`  | `React.ReactNode` | -       | Card parts and content |

## Card.Header Props

| Prop          | Type              | Default | Description                                                 |
| ------------- | ----------------- | ------- | ----------------------------------------------------------- |
| `title`       | `React.ReactNode` | -       | Card title rendered in a `<h3>`.                            |
| `description` | `React.ReactNode` | -       | Supplementary text rendered below the title.                |
| `children`    | `React.ReactNode` | -       | Additional header content rendered after title/description. |
| `className`   | `string`          | -       | Additional CSS classes.                                     |

## Card.Content Props

`Card.Content` accepts all standard HTML `<div>` props.

| Prop        | Type              | Default | Description            |
| ----------- | ----------------- | ------- | ---------------------- |
| `className` | `string`          | -       | Additional CSS classes |
| `children`  | `React.ReactNode` | -       | Card body content      |

## Examples

### Header only

```tsx
<Card.Root>
  <Card.Header title="Summary" description="Key metrics for this period" />
</Card.Root>
```

### Content only

```tsx
<Card.Root>
  <Card.Content>
    <p>No header needed for this card.</p>
  </Card.Content>
</Card.Root>
```

### Custom header content

```tsx
<Card.Root>
  <Card.Header title="Recent Orders">
    <Button size="sm" variant="outline">
      View all
    </Button>
  </Card.Header>
  <Card.Content>
    <Table>{/* ... */}</Table>
  </Card.Content>
</Card.Root>
```

## Related

* [MetricCard](metric-card) — Card variant for KPI / dashboard metric display.
* [DescriptionCard](description-card) — Card variant for structured key-value data.
* [ActivityCard](activity-card) — Card variant for timeline activity feeds.

---

---
url: https://docs.tailor.tech/app-shell/components/checkbox.md
description: >-
  Styled checkbox for boolean form fields, with indeterminate state and
  automatic Field / React Hook Form integration
---

# Checkbox

The `Checkbox` component is a styled control for boolean fields. It wraps Base UI's checkbox, so it works with [`Field`](form) and React Hook Form the same way `Input`, `Select`, and `Combobox` do — dropped inside a `Field.Root` it inherits label association, `aria-describedby`, `disabled`, and the invalid (error) state automatically.

## Import

```tsx
import { Checkbox } from "@tailor-platform/app-shell";
```

## Basic Usage

```tsx
<Checkbox label="Subscribe to updates" />
```

Omit `label` to render just the box — useful for a table row-select cell (pass `aria-label`) or when a `Field.Label` sibling supplies the text.

```tsx
<Checkbox aria-label="Select row" />
```

## Props

Accepts all Base UI `Checkbox.Root` props, plus `label`. The most common:

| Prop              | Type                                  | Default | Description                                                                           |
| ----------------- | ------------------------------------- | ------- | ------------------------------------------------------------------------------------- |
| `label`           | `React.ReactNode`                     | -       | Inline label rendered next to the box (wraps both in a `<label>`). Omit for box-only. |
| `checked`         | `boolean`                             | -       | Controlled checked state.                                                             |
| `defaultChecked`  | `boolean`                             | `false` | Initial checked state when uncontrolled.                                              |
| `onCheckedChange` | `(checked: boolean, details) => void` | -       | Called with the next boolean state.                                                   |
| `indeterminate`   | `boolean`                             | `false` | Renders the "partially selected" (mixed) state.                                       |
| `disabled`        | `boolean`                             | `false` | Disables the control.                                                                 |
| `required`        | `boolean`                             | `false` | Marks the control as required for native/Field validation.                            |
| `name`            | `string`                              | -       | Field name for native form submission.                                                |
| `value`           | `string`                              | -       | Submitted value when checked (native forms).                                          |
| `inputRef`        | `React.Ref<HTMLInputElement>`         | -       | Ref to the hidden native input (use for React Hook Form's `field.ref`).               |
| `className`       | `string`                              | -       | Applied to the outer element — the `<label>` when `label` is set, else the box.       |

## Examples

### Controlled

```tsx
const [checked, setChecked] = useState(false);

<Checkbox label="Enable notifications" checked={checked} onCheckedChange={setChecked} />;
```

### Indeterminate ("select all")

```tsx
<Checkbox
  aria-label="Select all rows"
  checked={allSelected}
  indeterminate={someSelected && !allSelected}
  onCheckedChange={(checked) => (checked ? selectAll() : clearAll())}
/>
```

### Disabled

```tsx
<Checkbox label="Unavailable option" disabled />
```

## Use With Field

Placed inside a `Field.Root`, `Checkbox` picks up the field's invalid and disabled state automatically — no `error` prop of its own. Use the inline `label` for the checkbox text and `Field.Error` for the message below it.

```tsx
<Field.Root name="acceptTerms" error={{ message: "You must accept the terms." }}>
  <Checkbox label="I accept the terms and conditions" />
  <Field.Error>You must accept the terms.</Field.Error>
</Field.Root>
```

## React Hook Form

Drive the checkbox with a `Controller`. `onCheckedChange` hands React Hook Form a boolean directly, and spreading `fieldState` onto `Field.Root` wires the error/invalid state.

```tsx
import { useForm, Controller } from "react-hook-form";

function TermsForm() {
  const { control, handleSubmit } = useForm({ defaultValues: { acceptTerms: false } });

  return (
    <Form onSubmit={handleSubmit((data) => save(data))}>
      <Controller
        name="acceptTerms"
        control={control}
        rules={{ required: "You must accept the terms." }}
        render={({ field, fieldState }) => (
          <Field.Root name={field.name} {...fieldState}>
            <Checkbox
              label="I accept the terms and conditions"
              checked={field.value}
              onCheckedChange={field.onChange}
              onBlur={field.onBlur}
              inputRef={field.ref}
            />
            <Field.Error>{fieldState.error?.message}</Field.Error>
          </Field.Root>
        )}
      />
      <button type="submit">Save</button>
    </Form>
  );
}
```

## With a shadcn-style `FormField`

`Checkbox` also drops into the common shadcn `FormField` / `FormControl` / `FormMessage`
pattern — no AppShell `Field` needed. `FormControl` injects `id`, `aria-describedby`, and
`aria-invalid` onto the control; `Checkbox` forwards them (and `ref`, in React 19) to the
underlying element and styles its error state off `aria-invalid`, so the invalid highlight
works here too.

```tsx
<FormField
  control={control}
  name="acceptTerms"
  render={({ field }) => (
    <FormItem>
      <FormControl>
        <Checkbox
          label="I accept the terms and conditions"
          checked={field.value}
          onCheckedChange={field.onChange}
          onBlur={field.onBlur}
          inputRef={field.ref}
        />
      </FormControl>
      <FormMessage />
    </FormItem>
  )}
/>
```

> Use the inline `label` prop for the checkbox text (it wraps the box in a `<label>`, so
> clicking the text toggles it). A separate `FormLabel` with `htmlFor` is descriptive only —
> the control renders a `<span role="checkbox">`, which isn't a natively labelable element,
> so a sibling label won't toggle it on click.

## TypeScript

```typescript
import { type CheckboxProps } from "@tailor-platform/app-shell";
```

## Related Components

* [Form, Field, and Fieldset](form) — Checkbox integrates with `Field` for labels, errors, and validation.
* [Input](input) — Text input counterpart.
* [Textarea](textarea) — Multi-line text counterpart.

---

---
url: https://docs.tailor.tech/app-shell/components/combobox.md
description: >-
  Searchable combobox with single/multi selection, built-in filtering, async
  data fetching, and user-creatable items
---

# Combobox

The `Combobox` component provides a searchable combobox with built-in filtering. Pass `items` and get a ready-to-use combobox out of the box. For async data fetching use `Combobox.Async`. For user-created items add an `onCreateItem` prop. For custom compositions use `Combobox.Parts`.

[Live preview in the UI Catalogue →](https://ui.tailor.tech/components/combobox)

## Import

```tsx
import { Combobox } from "@tailor-platform/app-shell";
```

## Basic Usage

```tsx
<Combobox
  items={["Apple", "Banana", "Cherry"]}
  placeholder="Search fruits..."
  onValueChange={(value) => console.log(value)}
/>
```

## Props

### Combobox Props

| Prop                | Type                                                                       | Default                      | Description                                                                |
| ------------------- | -------------------------------------------------------------------------- | ---------------------------- | -------------------------------------------------------------------------- |
| `items`             | `I[]`                                                                      | -                            | Items to display. May be a flat array or an array of `ItemGroup<T>`        |
| `placeholder`       | `string`                                                                   | -                            | Placeholder text for the input                                             |
| `emptyText`         | `string`                                                                   | `"No results."`              | Text shown when no items match                                             |
| `multiple`          | `true \| false \| undefined`                                               | `false`                      | Enables multi-select mode                                                  |
| `value`             | `T \| null` (single) or `T[]` (multiple)                                   | -                            | Controlled value                                                           |
| `defaultValue`      | `T \| null` (single) or `T[]` (multiple)                                   | -                            | Initial value (uncontrolled)                                               |
| `onValueChange`     | `(value: T \| null) => void` (single) or `(value: T[]) => void` (multiple) | -                            | Called when the selected value changes                                     |
| `mapItem`           | `(item: T) => MappedItem`                                                  | -                            | Map each item to its label, key, and optional custom render                |
| `className`         | `string`                                                                   | -                            | Additional CSS classes for the root container                              |
| `disabled`          | `boolean`                                                                  | `false`                      | Disables the combobox                                                      |
| `aria-label`        | `string`                                                                   | -                            | Accessible name for the input. Use when there is no visible label          |
| `aria-labelledby`   | `string`                                                                   | -                            | ID of the element(s) that label the input                                  |
| `id`                | `string`                                                                   | -                            | ID applied to the combobox input element                                   |
| `onCreateItem`      | `(value: string) => T \| false \| Promise<T \| false>`                     | -                            | Enable user-created items (requires `mapItem`; `T` must be an object type) |
| `formatCreateLabel` | `(value: string) => string`                                                | `` (v) => `Create "${v}"` `` | Format the label for the "create" option                                   |

### MappedItem

```ts
interface MappedItem {
  label: string; // Display text, used for filtering and a11y
  key?: string; // React key. Defaults to label
  render?: React.ReactNode; // Custom JSX to render in the dropdown
}
```

### ItemGroup

```ts
interface ItemGroup<T> {
  label: string;
  items: T[];
}
```

## Grouped Items

```tsx
const fruits = [
  { label: "Citrus", items: ["Orange", "Lemon", "Lime"] },
  { label: "Berries", items: ["Strawberry", "Blueberry"] },
];

<Combobox items={fruits} placeholder="Search fruits..." />;
```

## Multi-select

In multi-select mode, selected items are displayed as chips inside the input:

```tsx
<Combobox
  items={["Red", "Green", "Blue"]}
  multiple
  placeholder="Pick colors"
  onValueChange={(colors) => console.log(colors)}
/>
```

## Creatable Items

Add `onCreateItem` to let users create new items on-the-fly. `T` must be an object type:

```tsx
type Tag = { id: string; name: string };

const [tags, setTags] = useState<Tag[]>([
  { id: "1", name: "Bug" },
  { id: "2", name: "Feature" },
]);

<Combobox
  items={tags}
  mapItem={(tag) => ({ label: tag.name, key: tag.id })}
  onCreateItem={(value) => {
    const newTag: Tag = { id: crypto.randomUUID(), name: value };
    setTags((prev) => [...prev, newTag]);
    return newTag; // return the new item to add it to the selection
  }}
  placeholder="Search or create a tag..."
/>;
```

`onCreateItem` may return:

* `T` — accept the item and add it to the selection
* `false` — cancel the creation
* `Promise<T | false>` — for async workflows

## Async Loading

Use `Combobox.Async` to load items from an API. The fetcher is called on each keystroke (debounced). When the dropdown first opens or the input is cleared, the fetcher receives `null` as the query — return initial/default items for `null`, or return an empty array to show nothing until the user starts typing.

```tsx
import { type ComboboxAsyncFetcher } from "@tailor-platform/app-shell";

const fetcher: ComboboxAsyncFetcher<User> = async (query, { signal }) => {
  const res = await fetch(`/api/users?q=${query ?? ""}`, { signal });
  return res.json();
};

<Combobox.Async
  fetcher={fetcher}
  mapItem={(user) => ({ label: user.name, key: user.id })}
  placeholder="Search users..."
  onValueChange={(user) => console.log(user)}
/>;
```

`Combobox.Async` also supports `onCreateItem` for creatable async comboboxes.

### Combobox.Async Props

Accepts all the same props as `Combobox` except `items`, plus:

| Prop           | Type                       | Default                    | Description                                                        |
| -------------- | -------------------------- | -------------------------- | ------------------------------------------------------------------ |
| `fetcher`      | `ComboboxAsyncFetcher<T>`  | -                          | Fetcher called on each keystroke (debounced by default)            |
| `loadingText`  | `string`                   | `"Loading..."`             | Text shown while loading                                           |
| `errorText`    | `string`                   | `"Couldn't load results."` | Message shown in the popover when the fetcher fails (with Retry)   |
| `retryText`    | `string`                   | `"Retry"`                  | Label for the retry button in the error state                      |
| `onFetchError` | `(error: unknown) => void` | -                          | Called once per outage when a fetch fails (logging/error tracking) |

### ComboboxAsyncFetcher

```ts
type ComboboxAsyncFetcher<T> =
  | ((query: string | null, options: { signal: AbortSignal }) => Promise<T[]>)
  | {
      fn: (query: string | null, options: { signal: AbortSignal }) => Promise<T[]>;
      debounceMs: number;
    };
```

`query` is `null` when the user has not typed anything (e.g. the dropdown was just opened or the input was cleared). Pass `{ fn, debounceMs }` to customize the debounce delay.

### Error handling

If the fetcher throws or rejects, `Combobox.Async` renders a built-in inline error state in the popover — the `errorText` message plus a **Retry** button that re-runs the last fetch — instead of the misleading "No results." empty state. Aborted/superseded requests (a keystroke replaced by a newer one) are ignored, and the component de-dupes per outage so typing during an outage doesn't stack repeated announcements.

To run a side effect on failure (log to error tracking, show a toast), pass `onFetchError` — it fires **once per outage** (on the transition into the error state) and re-arms after the next successful fetch. The inline error state is shown regardless.

```tsx
<Combobox.Async
  fetcher={fetcher}
  errorText="Couldn't load users."
  retryText="Try again"
  onFetchError={(error) => reportError(error)}
/>
```

## Low-level Primitives

`Combobox.Parts` exposes styled sub-components and hooks for fully custom compositions:

```tsx
const {
  Root,
  InputGroup,
  Input,
  Trigger,
  Content,
  List,
  Item,
  Empty,
  Group,
  GroupLabel,
  Clear,
  Chips,
  Chip,
  ChipRemove,
  Value,
  Collection,
  Status,
} = Combobox.Parts;
```

## Form submission

Inside a `Field.Root`, the field's `name` identifies the value and these props are unnecessary —
see [Form](form). They matter for **native** submission: a plain `<form>`, `new FormData(form)`,
or a server action.

| Prop                | Type                          | Default | Description                                                                                                                                                            |
| ------------------- | ----------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`              | `string`                      | -       | Names the hidden input for native submission. **Ignored inside a `Field.Root`** — the field's name wins.                                                               |
| `form`              | `string`                      | -       | `id` of the owning form, when the control is rendered outside it.                                                                                                      |
| `required`          | `boolean`                     | `false` | Blocks submission until a value is chosen, surfacing the matching `Field.Error`.                                                                                       |
| `inputRef`          | `React.Ref<HTMLInputElement>` | -       | Ref to the hidden input (use for React Hook Form's `field.ref`).                                                                                                       |
| `itemToStringValue` | `(item: T) => string`         | -       | Serialises a non-string item for submission. Items shaped `{ value, label }` use `value` automatically. Not available on the creatable variant, which derives its own. |

`itemToStringValue` is not accepted on the creatable variant (`onCreateItem`): `Combobox` derives
its own there so the pending-item sentinel serialises correctly. A creatable combobox over object
items therefore cannot customise the submitted value — use the non-creatable variant, or map the
value in your submit handler.

## Examples

### Controlled Combobox

```tsx
const [selected, setSelected] = useState<User | null>(null);

<Combobox
  items={users}
  mapItem={(u) => ({ label: u.name, key: u.id })}
  value={selected}
  onValueChange={setSelected}
  placeholder="Select a user"
/>;
```

### Async with Parts (custom composition)

Combine `Combobox.useAsync` with `Combobox.Parts` for full control over layout and rendering:

`Combobox.useAsync` accepts the same options as `Combobox.Async` (including `onFetchError`) and returns:

| Property  | Type         | Description                                             |
| --------- | ------------ | ------------------------------------------------------- |
| `items`   | `T[]`        | Currently loaded items                                  |
| `loading` | `boolean`    | Whether a fetch is in progress                          |
| `error`   | `unknown`    | The error thrown by the last fetch, if any              |
| `retry`   | `() => void` | Re-runs the last fetch (use to build a custom retry UI) |

```tsx
type Country = { code: string; name: string };

const countries = Combobox.useAsync({
  fetcher: async (query, { signal }) => {
    const res = await fetch(`/api/countries?q=${query ?? ""}`, { signal });
    if (!res.ok) return [];
    return res.json() as Promise<Country[]>;
  },
  onFetchError: (error) => reportError(error),
});

<Combobox.Parts.Root {...countries} filter={null} itemToStringLabel={(c) => c.name}>
  <Combobox.Parts.InputGroup>
    <Combobox.Parts.Input placeholder="Search countries..." />
    <Combobox.Parts.Clear />
    <Combobox.Parts.Trigger />
  </Combobox.Parts.InputGroup>
  <Combobox.Parts.Content>
    <Combobox.Parts.List>
      {countries.items.map((c) => (
        <Combobox.Parts.Item key={c.code} value={c}>
          {c.name}
        </Combobox.Parts.Item>
      ))}
      <Combobox.Parts.Empty>
        {countries.error ? (
          <button onClick={countries.retry}>Couldn't load. Retry</button>
        ) : countries.loading ? (
          "Loading..."
        ) : (
          "No results."
        )}
      </Combobox.Parts.Empty>
    </Combobox.Parts.List>
  </Combobox.Parts.Content>
</Combobox.Parts.Root>;
```

## Accessibility

* Input is keyboard accessible with arrow key navigation
* Pressing `Escape` closes the dropdown
* Multi-select chips have `aria-label` set from the item label
* When used standalone (no visible `<label>`), give the input an accessible name with `aria-label` or `aria-labelledby` — otherwise screen readers announce only the current value:

```tsx
<Combobox items={items} aria-label="Fruit filter" />
```

## Related Components

* [Select](select) - Non-searchable dropdown
* [Autocomplete](autocomplete) - Free-text input with suggestions

---

---
url: https://docs.tailor.tech/app-shell/components/command-palette.md
description: >-
  Keyboard-driven quick navigation with fuzzy search for all routes in your
  application
---

# CommandPalette

`CommandPalette` provides a keyboard-driven quick navigation interface that allows users to search and navigate to any page in your application. Activated with `Cmd+K` (Mac) or `Ctrl+K` (Windows), it offers fuzzy search across all accessible routes.

[Live preview in the UI Catalogue →](https://ui.tailor.tech/components/command-palette)

## Usage

The CommandPalette is built into `AppShell` and rendered automatically. No explicit import or placement is needed:

```tsx
import { AppShell, SidebarLayout } from "@tailor-platform/app-shell";

function App() {
  return (
    <AppShell modules={modules}>
      <SidebarLayout />
    </AppShell>
  );
}
```

The CommandPalette will automatically:

* ✅ Index all navigatable routes from your modules
* ✅ Provide fuzzy search functionality
* ✅ Show breadcrumb paths for context
* ✅ Display module icons
* ✅ Respect access control (hidden routes won't appear)

## Keyboard Shortcuts

### Opening/Closing

| Shortcut                   | Action                |
| -------------------------- | --------------------- |
| `Cmd + K` (Mac)            | Toggle CommandPalette |
| `Ctrl + K` (Windows/Linux) | Toggle CommandPalette |
| `Esc`                      | Close CommandPalette  |

### Navigation

| Shortcut       | Action                           |
| -------------- | -------------------------------- |
| `↑` / `↓`      | Navigate up/down through results |
| `Enter`        | Navigate to selected route       |
| Type to search | Filter routes by fuzzy search    |

## Features

### Fuzzy Search

The CommandPalette uses intelligent fuzzy search that matches:

* **Route titles** - Page names from your resource meta
* **Paths** - URL segments
* **Breadcrumbs** - Full navigation path

Example searches:

* `dash` → Matches "Dashboard"
* `prod det` → Matches "Products > Product Details"
* `ord` → Matches "Orders", "Order Details", etc.

### Breadcrumb Display

Each result shows its full navigation path for context:

```
🏠 Dashboard > Analytics > Revenue
📦 Products > Categories > Electronics
📋 Orders > History > 2024
```

### Access Control Integration

The CommandPalette automatically respects your route guards:

* Hidden routes (via `hidden()` guard) don't appear in search
* Protected routes are filtered based on current user permissions
* Dynamic updates when context changes

### Icon Display

Module icons are displayed next to search results for visual recognition:

```tsx
const productsModule = defineModule({
  path: "products",
  component: ProductsPage,
  meta: {
    title: "Products",
    icon: <Package />, // Shown in CommandPalette
  },
});
```

## Contextual Actions

In addition to navigation results, the CommandPalette can surface page-level actions. Use the `useRegisterCommandPaletteActions` hook to register actions that appear in the **Actions** section of the palette. Actions are unregistered automatically when the component unmounts.

```tsx
import { useRegisterCommandPaletteActions } from "@tailor-platform/app-shell";

function OrderDetailPage() {
  useRegisterCommandPaletteActions("Order Actions", [
    { key: "confirm", label: "Confirm order", onSelect: handleConfirm },
    { key: "cancel", label: "Cancel order", icon: <XIcon />, onSelect: handleCancel },
  ]);
}
```

### Parameters

| Parameter | Type                     | Description                                              |
| --------- | ------------------------ | -------------------------------------------------------- |
| `group`   | `string`                 | Display group name for the actions shown in the palette  |
| `actions` | `CommandPaletteAction[]` | List of actions to register (see `CommandPaletteAction`) |

### `CommandPaletteAction`

| Property   | Type                          | Description                                                                   |
| ---------- | ----------------------------- | ----------------------------------------------------------------------------- |
| `key`      | `string`                      | Unique key for React reconciliation                                           |
| `label`    | `string`                      | Visible label shown in the palette; also used for search matching             |
| `icon`     | `ReactNode`                   | Optional icon rendered next to the label                                      |
| `group`    | `string`                      | Optional group override; defaults to the `group` parameter passed to the hook |
| `onSelect` | `() => void \| Promise<void>` | Callback invoked when the user selects the action                             |

> **Note:** `icon` changes alone do not trigger re-registration. To reflect a dynamic icon update, also change the action's `key` or `label`.

### ActionPanel Integration

When you use the [`ActionPanel`](action-panel) component, its enabled actions (not `disabled`, not `loading`, and with an `onClick` handler) are automatically registered to the CommandPalette under the panel's `title`. No additional setup is required.

For more details see [`useRegisterCommandPaletteActions`](../api/use-register-command-palette-actions).

## Async Search Sources

In addition to built-in page search and contextual actions, you can wire async, prefix-activated search sources into the CommandPalette via the `searchSources` prop on `AppShell`.

### How It Works

1. Pass an array of `SearchSource` objects to `AppShell`'s `searchSources` prop.
2. When the user types a source's `prefix` followed by `:` (e.g. `ORD:`), the palette switches into **search mode**: the Actions and Pages sections are hidden and only results from that source are shown.
3. On the **empty-input** state, the palette renders a **Search Modes** section listing every registered source so users can activate a mode with a single click.

### Basic Example

```tsx
import {
  AppShell,
  SidebarLayout,
  DefaultSidebar,
  type SearchSource,
} from "@tailor-platform/app-shell";

const searchSources: readonly SearchSource[] = [
  {
    prefix: "ORD",
    title: "Orders",
    search: async (query, { signal }) => {
      const results = await api.searchOrders(query, { signal });
      return results.map((o) => ({
        key: o.id,
        label: o.number,
        description: `${o.customerName} — ${o.date}`,
        path: `/orders/${o.id}`,
      }));
    },
  },
  {
    prefix: "CUST",
    title: "Customers",
    search: async (query, { signal }) => {
      const results = await api.searchCustomers(query, { signal });
      return results.map((c) => ({
        key: c.id,
        label: c.name,
        path: `/customers/${c.id}`,
      }));
    },
  },
];

function App() {
  return (
    <AppShell modules={modules} searchSources={searchSources}>
      <SidebarLayout sidebar={<DefaultSidebar />} />
    </AppShell>
  );
}
```

### `SearchSource`

| Property | Type                                                                                         | Required | Description                                                                                        |
| -------- | -------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------- |
| `prefix` | `string`                                                                                     | ✅       | Mode-activating prefix (e.g. `"ORD"`). Case-sensitive, alphanumeric only.                          |
| `title`  | `string`                                                                                     | ✅       | Heading shown above results and in the Search Modes list (e.g. `"Orders"`).                        |
| `icon`   | `ReactNode`                                                                                  | No       | Optional icon shown next to each result that lacks its own icon.                                   |
| `search` | `(query: string, options: { signal: AbortSignal }) => Promise<CommandPaletteSearchResult[]>` | ✅       | Async function invoked with the query text after the prefix and an `AbortSignal` for cancellation. |

### `CommandPaletteSearchResult`

| Property      | Type        | Required | Description                                                    |
| ------------- | ----------- | -------- | -------------------------------------------------------------- |
| `key`         | `string`    | ✅       | Unique key for React reconciliation.                           |
| `label`       | `string`    | ✅       | Visible label shown in the palette (e.g. `"Order #ORD-1234"`). |
| `description` | `string`    | No       | Optional secondary text (e.g. `"山田太郎 - 2024/01/15"`).      |
| `icon`        | `ReactNode` | No       | Optional icon for this specific result.                        |
| `path`        | `string`    | ✅       | Resolved navigation path (e.g. `"/orders/abc-123"`).           |

### Prefix Syntax

The prefix match is **case-sensitive**. When a user types `ORD:`, the string after the colon (including any space) is forwarded to `search` as the query:

```
User types: ORD:
  → search("", { signal })  — empty query, show all or hint

User types: ORD:12345
  → search("12345", { signal })

User types: ORD: alice
  → search(" alice", { signal })  — leading space preserved
```

## Customization

### Custom Palette (Advanced)

If you need to customize the CommandPalette behavior, you can use the `useCommandPalette` hook:

```tsx
import { useCommandPalette, navItemsToRoutes } from "@tailor-platform/app-shell";

function CustomPalette() {
  const navItems = useNavItems(); // Get navigation items
  const routes = navItemsToRoutes(navItems);

  const { open, handleOpenChange, search, setSearch, filteredRoutes, handleSelect, handleKeyDown } =
    useCommandPalette({ routes });

  // Custom UI implementation
  return (
    <Dialog open={open} onOpenChange={handleOpenChange}>
      <Input
        value={search}
        onChange={(e) => setSearch(e.target.value)}
        onKeyDown={handleKeyDown}
        placeholder="Search pages..."
      />
      {filteredRoutes.map((route) => (
        <button key={route.path} onClick={() => handleSelect(route)}>
          {route.icon}
          {route.title}
          <span>{route.breadcrumb.join(" > ")}</span>
        </button>
      ))}
    </Dialog>
  );
}
```

### Disabling CommandPalette

Currently, the CommandPalette is always enabled with `SidebarLayout`. To disable it, you would need to create a custom layout without the CommandPalette component.

## Examples

### Basic Usage

The CommandPalette works automatically with your module definitions:

```tsx
const modules = [
  defineModule({
    path: "dashboard",
    component: DashboardPage,
    meta: { title: "Dashboard", icon: <Home /> },
    resources: [
      defineResource({
        path: "analytics",
        component: AnalyticsPage,
        meta: { title: "Analytics" },
      }),
    ],
  }),
  defineModule({
    path: "products",
    component: ProductsPage,
    meta: { title: "Products", icon: <Package /> },
    resources: [
      defineResource({
        path: ":id",
        component: ProductDetailPage,
        meta: { title: "Product Details" },
      }),
    ],
  }),
];

// CommandPalette will show:
// - Dashboard
// - Dashboard > Analytics
// - Products
// - Products > Product Details (when applicable)
```

### With Access Control

Routes hidden by guards won't appear in search:

```tsx
const adminModule = defineModule({
  path: "admin",
  component: AdminPage,
  meta: { title: "Admin Panel" },
  guards: [
    ({ context }) => {
      return context.currentUser?.role === "admin" ? pass() : hidden(); // Won't show in CommandPalette for non-admins
    },
  ],
});
```

### Search Behavior

```
User types: "prod"
Results:
  📦 Products
  📦 Products > Product Details
  📦 Products > Categories

User types: "dash ana"
Results:
  🏠 Dashboard > Analytics

User types: "ord 123"
Results:
  📋 Orders > Order #123 (if dynamic routes are indexed)
```

## Design

The CommandPalette follows these design principles:

### Visual Design

* **Clean, focused UI** - Minimal distractions
* **Clear hierarchy** - Module icons, titles, and breadcrumbs
* **Active state** - Highlight selected result
* **Empty state** - "No results found" message

### UX Patterns

* **Immediate feedback** - Results update as you type
* **Keyboard-first** - All actions accessible via keyboard
* **Contextual information** - Breadcrumbs show location
* **Quick access** - Single shortcut to open

### Performance

* **Instant search** - Client-side fuzzy matching
* **Debounced input** - Smooth typing experience
* **Lazy loading** - Routes loaded only when needed

## Best Practices

### Do:

* ✅ Provide clear, descriptive titles in resource meta
* ✅ Use meaningful module icons for visual recognition
* ✅ Structure modules logically for better discoverability
* ✅ Keep route hierarchies shallow when possible

### Don't:

* ❌ Use generic titles like "Page 1", "Section A"
* ❌ Create deeply nested resources (hard to navigate)
* ❌ Forget to set meta.title on resources
* ❌ Use similar titles for different routes

## Accessibility

* **Keyboard navigation** - Full keyboard support
* **ARIA labels** - Proper labels for screen readers
* **Focus management** - Focus trapped in dialog when open
* **ESC to close** - Standard dialog behavior

## Related Components

* [AppShell](app-shell) - Root component that provides CommandPalette
* [SidebarLayout](sidebar-layout) - Layout that includes CommandPalette

## Related Concepts

* [Modules and Resources](../concepts/modules-and-resources) - Define routes that appear in CommandPalette
* [Routing and Navigation](../concepts/routing-navigation) - Navigation system
* [Guards and Permissions](../api/guards/overview) - Control route visibility

## Troubleshooting

### Routes not appearing in search

**Problem:** Some routes don't show up in CommandPalette

**Solutions:**

1. Check that the resource has a `meta.title` defined
2. Verify the route isn't hidden by a guard
3. Ensure the route is navigatable (not a redirect-only route)

### Search not matching expected routes

**Problem:** Typing a route name doesn't find it

**Solutions:**

1. Try typing the breadcrumb path: "Products Categories"
2. Use abbreviations: "prod cat"
3. Check spelling of the title in resource meta

### CommandPalette not opening

**Problem:** `Cmd+K` / `Ctrl+K` doesn't work

**Solutions:**

1. Check if another app is capturing the shortcut
2. Verify you're using `SidebarLayout` (CommandPalette is included)
3. Check browser console for JavaScript errors

---

---
url: https://docs.tailor.tech/app-shell/components/csv-importer.md
description: >-
  Guided multi-step CSV import flow with drag-and-drop upload, column mapping,
  validation, and inline error correction
---

# CsvImporter

The `CsvImporter` component provides a guided, multi-step CSV import flow rendered inside a drawer. It handles drag-and-drop file upload, interactive column mapping, Standard Schema validation, inline cell editing, and async server-side validation.

[Live preview in the UI Catalogue →](https://ui.tailor.tech/components/csv-importer)

## Import

```tsx
import {
  CsvImporter,
  useCsvImporter,
  csv,
  type CsvSchema,
  type CsvColumn,
  type CsvImportEvent,
  type CsvCellIssue,
  type CsvCorrection,
  type CsvColumnMapping,
  type ParsedRow,
  type InferCsvRow,
} from "@tailor-platform/app-shell";
```

## Basic Usage

Use the `useCsvImporter` hook to manage state, then render `<CsvImporter>` with the returned props.

```tsx
import { CsvImporter, useCsvImporter, csv } from "@tailor-platform/app-shell";
import { Button } from "@tailor-platform/app-shell";

function ProductImport() {
  const { open, props } = useCsvImporter({
    schema: {
      columns: [
        {
          key: "name",
          label: "Name",
          required: true,
          aliases: ["product_name"],
          schema: csv.string({ min: 1 }),
        },
        {
          key: "price",
          label: "Price",
          schema: csv.number({ min: 0 }),
        },
        {
          key: "active",
          label: "Active",
          schema: csv.boolean(),
        },
      ],
    },
    onImport: (event) => {
      console.log(event.summary);
    },
  });

  return (
    <>
      <Button onClick={open}>Import CSV</Button>
      <CsvImporter {...props} />
    </>
  );
}
```

## `useCsvImporter`

The `useCsvImporter` hook manages the open/close state and returns both an `open` function and `props` to spread onto `<CsvImporter>`.

### Options

| Option        | Type                                               | Default            | Description                                                                 |
| ------------- | -------------------------------------------------- | ------------------ | --------------------------------------------------------------------------- |
| `schema`      | `CsvSchema`                                        | —                  | Column definitions for the import (see [CsvSchema](#csvschema))             |
| `onImport`    | `(event: CsvImportEvent) => void \| Promise<void>` | —                  | Called when the user confirms the import after resolving all errors         |
| `onValidate`  | `(rows: ParsedRow[]) => Promise<CsvCellIssue[]>`   | —                  | Optional async callback for server-side validation after schema checks pass |
| `maxFileSize` | `number`                                           | `10485760` (10 MB) | Maximum allowed file size in bytes                                          |

### Return Value

| Property | Type               | Description                                           |
| -------- | ------------------ | ----------------------------------------------------- |
| `open`   | `() => void`       | Function to programmatically open the importer drawer |
| `props`  | `CsvImporterProps` | Props object to spread directly onto `<CsvImporter>`  |

## `CsvImporter` Props

`CsvImporter` is intended to be used with props returned from `useCsvImporter`. Spread the `props` object directly onto the component.

```tsx
<CsvImporter {...props} />
```

## Schemas

### `CsvSchema`

```ts
type CsvSchema = {
  columns: CsvColumn[];
};
```

### `CsvColumn`

| Property      | Type               | Default | Description                                                                             |
| ------------- | ------------------ | ------- | --------------------------------------------------------------------------------------- |
| `key`         | `string`           | —       | Internal key; becomes the object key in parsed row data                                 |
| `label`       | `string`           | —       | Display label shown in the mapping UI                                                   |
| `description` | `string`           | —       | Optional hint shown in the mapping UI                                                   |
| `required`    | `boolean`          | `false` | Whether this column must be mapped before proceeding                                    |
| `aliases`     | `string[]`         | —       | Alternative CSV header names for automatic matching                                     |
| `schema`      | `StandardSchemaV1` | —       | Standard Schema validator for coercion and validation (see [csv helpers](#csv-helpers)) |

## `csv` Helpers

Built-in Standard Schema validators for common CSV column types. Each helper handles both coercion and validation in a single declaration.

| Helper                                                                    | Output type        | Description                                                             |
| ------------------------------------------------------------------------- | ------------------ | ----------------------------------------------------------------------- |
| `csv.string(options?: { min?: number; max?: number })`                    | `string`           | Pass-through string with optional length constraints                    |
| `csv.number(options?: { min?: number; max?: number; integer?: boolean })` | `number`           | Coerces raw CSV string to a number; rejects `NaN`                       |
| `csv.boolean(options?: { truthy?: string[]; falsy?: string[] })`          | `boolean`          | Recognises `"true"/"1"/"yes"` and `"false"/"0"/"no"` (case-insensitive) |
| `csv.date()`                                                              | `Date`             | Coerces raw CSV string to a `Date`; rejects unparseable values          |
| `csv.enum(values: string[])`                                              | `T extends string` | Validates the value is one of the allowed strings (case-sensitive)      |

```tsx
// String with required check (min: 1)
csv.string({ min: 1 });

// Number with lower bound
csv.number({ min: 0 });

// Integer only
csv.number({ integer: true });

// Boolean with defaults: truthy = ["true","1","yes"], falsy = ["false","0","no"]
csv.boolean();

// Date
csv.date();

// Enum
csv.enum(["active", "inactive", "pending"]);
```

## Server-side Validation

Use `onValidate` to perform async checks (e.g. uniqueness constraints) after schema validation passes. Return an array of `CsvCellIssue` objects to mark cells with errors or warnings.

```tsx
const { open, props } = useCsvImporter({
  schema: { columns: [...] },
  onValidate: async (rows) => {
    const issues = await checkUniqueness(rows);
    return issues; // CsvCellIssue[]
  },
  onImport: (event) => { /* ... */ },
});
```

### `CsvCellIssue`

| Property    | Type                   | Description                                          |
| ----------- | ---------------------- | ---------------------------------------------------- |
| `rowIndex`  | `number`               | 0-based row index                                    |
| `columnKey` | `string`               | The schema column key                                |
| `level`     | `"error" \| "warning"` | `"error"` blocks import; `"warning"` allows import   |
| `message`   | `string`               | Human-readable message displayed inline in the table |

## Import Event

The `onImport` callback receives a `CsvImportEvent` with the following shape:

| Property      | Type                                                                | Description                                                              |
| ------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `file`        | `File`                                                              | The original file selected by the user                                   |
| `mappings`    | `CsvColumnMapping[]`                                                | The confirmed column mappings                                            |
| `corrections` | `CsvCorrection[]`                                                   | Corrections made by the user in the review step                          |
| `issues`      | `CsvCellIssue[]`                                                    | Any remaining issues (warnings only — errors are resolved before import) |
| `summary`     | `{ totalRows, validRows, correctedRows, skippedRows, warningRows }` | Summary statistics                                                       |
| `buildRows()` | `() => Promise<InferCsvRow<T>[]>`                                   | Reconstruct fully-processed rows with schema coercion and corrections    |

## `event.buildRows()`

A method on the import event that reconstructs the fully processed row data on the client side. The return type is inferred from the schema definition — column keys become object keys, and `StandardSchemaV1` output types are preserved.

```tsx
onImport: async (event) => {
  const rows = await event.buildRows();
  // rows is typed based on schema — e.g. { name: string; price: number; ... }[]
  await saveToBackend(rows);
},
```

> If you are sending the file, mappings, and corrections to a backend for processing, you do not need `buildRows()`.

## i18n

`CsvImporter` includes built-in English and Japanese labels. No additional setup is required.

## Related Components

* [Sheet](sheet) — Slide-in panel (the drawer used internally by CsvImporter)
* [Button](button) — Use as the trigger to open the importer

---

---
url: https://docs.tailor.tech/app-shell/components/data-table.md
description: >-
  Compound data table component with sortable columns, filter chips,
  cursor-based pagination, row actions, and multi-row selection
---

# DataTable

`DataTable` is a compound component for displaying collections of records. It integrates with the collection variable hooks (`useCollectionVariables`) to drive sorting, filtering, and cursor-based pagination through a GraphQL API.

[Live preview in the UI Catalogue →](https://ui.tailor.tech/components/data-table)

## Import

```tsx
import {
  DataTable,
  useDataTable,
  useDataTableContext,
  useCollectionVariables,
  createColumnHelper,
  type Column,
  type DataTableData,
  type DataTableRootProps,
  type DataTablePaginationProps,
  type RowAction,
  type UseDataTableOptions,
  type UseDataTableReturn,
  type MetadataFieldOptions,
  type DataTableContextValue,
} from "@tailor-platform/app-shell";
```

## Basic Usage

```tsx
import { gql, useQuery } from "urql";
import {
  DataTable,
  useDataTable,
  useCollectionVariables,
  createColumnHelper,
} from "@tailor-platform/app-shell";

const LIST_JOURNALS = gql`
  query ListJournals(
    $after: String
    $before: String
    $first: Int
    $last: Int
    $order: [JournalOrderInput]
    $query: JournalQueryInput
  ) {
    journals(
      after: $after
      before: $before
      first: $first
      last: $last
      order: $order
      query: $query
    ) {
      edges {
        node {
          id
          contents
          authorID
        }
      }
      pageInfo {
        endCursor
        hasNextPage
        hasPreviousPage
        startCursor
      }
      total
    }
  }
`;

type Journal = { id: string; contents: string; authorID: string };

const { column } = createColumnHelper<Journal>();

const columns = [
  column({
    label: "ID",
    render: (row) => row.id,
    filter: { field: "id", type: "uuid" },
  }),
  column({
    label: "Author",
    render: (row) => row.authorID,
    sort: { field: "authorID", type: "string" },
    filter: { field: "authorID", type: "string" },
  }),
  column({
    label: "Contents",
    render: (row) => row.contents,
    filter: { field: "contents", type: "string" },
  }),
];

function JournalsPage() {
  const { variables, control } = useCollectionVariables({
    params: { pageSize: 20 },
  });

  const [result] = useQuery({
    query: LIST_JOURNALS,
    variables: {
      ...variables.pagination,
      query: variables.query,
      order: variables.order,
    },
  });

  const table = useDataTable({
    columns,
    data: result.data
      ? {
          rows: result.data.journals.edges.map((e) => e.node),
          pageInfo: result.data.journals.pageInfo,
          total: result.data.journals.total,
        }
      : undefined,
    loading: result.fetching,
    control,
  });

  return (
    <DataTable.Root value={table}>
      <DataTable.Toolbar>
        <DataTable.Filters />
      </DataTable.Toolbar>
      <DataTable.Table />
      <DataTable.Footer>
        <DataTable.Pagination pageSizeOptions={[10, 20, 50]} />
      </DataTable.Footer>
    </DataTable.Root>
  );
}
```

## Sub-components

`DataTable` is a namespace object. All sub-components read state from `DataTable.Root` via context.

| Sub-component          | Description                                                                                                                                                                           |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DataTable.Root`       | Context provider. Wraps all other sub-components. Required.                                                                                                                           |
| `DataTable.Table`      | Renders the `<table>` with headers and body. Required.                                                                                                                                |
| `DataTable.Toolbar`    | Container for toolbar content (e.g. filters). Optional. Pass `columnSettings` to render the built-in "Columns" control (show/hide + reorder + pin) at the top-right. See props below. |
| `DataTable.Filters`    | Add-filter panel + active filter chips, auto-generated from column filter configs. Requires `control` from `useCollectionVariables`.                                                  |
| `DataTable.Footer`     | Footer container for pagination and other footer content. Optional.                                                                                                                   |
| `DataTable.Pagination` | Pre-built pagination controls with optional row count and selection info. Requires `control` from `useCollectionVariables`. Place inside `DataTable.Footer`.                          |

### `DataTable.Root` Props

| Prop        | Type                       | Description                                  |
| ----------- | -------------------------- | -------------------------------------------- |
| `value`     | `UseDataTableReturn<TRow>` | Return value of `useDataTable()`. Required.  |
| `children`  | `ReactNode`                | Sub-components to render inside the root.    |
| `className` | `string`                   | Additional CSS class for the root container. |

### `DataTable.Toolbar` Props

| Prop             | Type        | Default | Description                                                                                                                                         |
| ---------------- | ----------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `children`       | `ReactNode` | —       | Toolbar content (e.g. `DataTable.Filters`), laid out on the left.                                                                                   |
| `columnSettings` | `boolean`   | `false` | Render the built-in "Columns" control (show/hide + reorder + pin) anchored to the top-right. Persists per-user when `useDataTable` has a `tableId`. |
| `className`      | `string`    | —       | Additional CSS class for the toolbar container.                                                                                                     |

### `DataTable.Filters` Props

| Prop          | Type                        | Default | Description                                                                                    |
| ------------- | --------------------------- | ------- | ---------------------------------------------------------------------------------------------- |
| `slot`        | `"all" \| "chips" \| "add"` | `"all"` | Which part to render (see below).                                                              |
| `addIconOnly` | `boolean`                   | `false` | Render the **Add filter** trigger as an icon-only button (the label becomes its `aria-label`). |
| `className`   | `string`                    | —       | Additional CSS class for the filters container.                                                |

By default `DataTable.Filters` renders the active filter chips plus the **Add filter** trigger together. The `slot` prop lets you split them across a custom toolbar layout:

* `"all"` — chips + the **Add filter** trigger (default).
* `"chips"` — only the active chips (renders nothing when there are none).
* `"add"` — only the **Add filter** trigger.

```tsx
// Add filter in a header row (with tabs, etc.); chips on the row below.
<DataTable.Toolbar>
  <div className="flex items-center justify-between">
    <MyViewTabs />
    <DataTable.Filters slot="add" />
  </div>
  <DataTable.Filters slot="chips" />
</DataTable.Toolbar>
```

### `DataTable.Pagination` Props

| Prop              | Type       | Default | Description                                                                                                                                                                             |
| ----------------- | ---------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pageSizeOptions` | `number[]` | —       | Available page-size options. When provided, a page-size switcher is rendered. The First button is always shown; the Last button is shown only when the backend returns a `total` count. |

`DataTable.Pagination` automatically displays a row count and selection info text on the left side of the pagination bar based on context state:

| Condition                                 | Displayed text           |
| ----------------------------------------- | ------------------------ |
| `total` is provided                       | `X row(s)`               |
| Rows selected and `total` is provided     | `Y of X row(s) selected` |
| Rows selected and `total` is not provided | `Y row(s) selected`      |
| No selection enabled and no `total`       | *(nothing displayed)*    |

Row selection is enabled by providing `onSelectionChange` to `useDataTable`. The `total` value comes from `DataTableData.total`.

## Column pinning, visibility & ordering

* **Pin** a column with `pin: "left" | "right"`. Pinned columns stay visible during horizontal scroll; the selection and expand columns auto-pin left and the row-actions column auto-pins right. A subtle shadow appears at the frozen edge once the table is scrolled under it. Sticky offsets are measured from the rendered layout, so a `width` isn't required — but setting `width` on pinned columns is recommended so their size stays stable as content changes.
* **Column settings.** Pass `columnSettings` to `DataTable.Toolbar` to render a built-in "Columns" control — a popover to show/hide columns, reorder them (drag), and change pinning by dragging a column between the **Fixed left**, **Scrollable**, and **Fixed right** zones. It's a toolbar prop (not a composed sub-component) because the control always sits in the same top-right position.
* **Persistence.** Pass a stable, **unique** `tableId` to persist each user's column layout (visibility, order, pinning) to `localStorage` (key `as:data-table:v1:<tableId>`). This is a per-user preference — it is deliberately **not** stored in the URL like filters/sort/pagination, so it survives reloads and isn't reset by shared/filtered links. Omit `tableId` for in-memory-only layout (state simply isn't persisted). Two tables mounted with the same `tableId` share one storage key and overwrite each other — use a unique id per table (e.g. `<route>:<entity>`); a dev-mode warning fires on duplicates.

```tsx
const table = useDataTable<Order>({
  columns, // e.g. [{ id: "ref", label: "Ref", width: 140, pin: "left" }, ...]
  data,
  tableId: "orders-list",
});

<DataTable.Root value={table}>
  <DataTable.Toolbar columnSettings />
  <DataTable.Table />
</DataTable.Root>;
```

## Expandable rows

Pass `rowExpansion` to `useDataTable` and each row gets a chevron that reveals a detail panel beneath it. Providing the option is what enables the feature — a dedicated chevron column is added at the left edge (auto-pinned left, after the selection column) and the detail row renders automatically. There is nothing new to compose in JSX.

The parts are grouped rather than flat so the type system rejects incoherent setups: a `getLabel` or `canExpand` with no `render`, or `expandedIds` without `onChange`, are compile errors rather than silently inert configurations.

```tsx
const table = useDataTable<Order>({
  columns,
  data,
  control,
  rowExpansion: {
    render: (row) => <OrderLineItems orderId={row.id} />,
    canExpand: (row) => row.lineItemCount > 0,
    getLabel: (row) => row.orderNumber,
  },
});
```

* **Rows must have an `id`.** Expansion is keyed by `row.id`, the same constraint as row selection. Rows without one render **no chevron** (not a disabled one) — a row must never be un-toggleable.
* **`canExpand`** suppresses the chevron per row (e.g. an order with no line items). The cell is still rendered, empty, so the column count stays consistent. The predicate gates the panel in **both** directions: a row whose result flips to `false` while open closes immediately, and an id sitting in `expandedIds` never opens a panel for a row the predicate rejects. That matters when restoring `expandedIds` from a URL or storage — the excluded row may have no detail data to render at all. Its id stays in `expandedIds` but is inert; `collapseAllRows()` clears it.
* **`getLabel`** returns a **bare identifier** — `"INV-1001"`, not `"Expand row INV-1001"`. The built-in i18n labels compose it into the trigger's accessible name (`"Expand row INV-1001"`) and the panel's (`"INV-1001 details"`), so English and Japanese word order both stay correct. Without it, the generic "Expand row" / "Row details" strings are used — set it on any table with more than a couple of rows.
* **`onClickRow` is unaffected.** The chevron lives in its own column and stops click propagation, so row-level navigation keeps working.
* **Expansion survives page changes.** Ids of rows that are no longer on the page simply don't render. Call `collapseAllRows()` to reset.
* **Multiple rows can be open at once.** There is no accordion / single-open mode.

### Controlled mode

Pass `expandedIds` to own the state yourself; internal state is then never written and you update the array from `onChange`. The two must be passed together — the type rejects either alone.

```tsx
const [expandedIds, setExpandedIds] = useState<string[]>([]);

const table = useDataTable<Order>({
  columns,
  data,
  rowExpansion: {
    render: (row) => <OrderLineItems orderId={row.id} />,
    expandedIds,
    onChange: setExpandedIds,
  },
});
```

`useDataTable` also returns `expandedIds`, `isRowExpanded(row)`, `toggleRowExpansion(row)`, and `collapseAllRows()`. The last two are `undefined` when `rowExpansion` is not provided, and both keep a stable identity across renders, so they are safe to list in an effect's dependency array:

```tsx
// Collapse everything when the page changes.
useEffect(() => {
  collapseAllRows?.();
}, [collapseAllRows, currentPage]);
```

`collapseAllRows()` is a no-op when nothing is open — it neither writes state nor fires `onExpandedChange`.

**Batching caveat.** Each toggle derives the next array from the current value of `expandedIds`, not from a functional update. Two toggles dispatched before your state commits both read the same base, so the first is lost. This matters when `expandedIds` lives behind an async store (Redux/Zustand middleware, a debounced URL sync, a `startTransition`), or when looping `toggleRowExpansion` over many rows to build an "expand all". Compute such updates yourself and set `expandedIds` directly rather than driving them through repeated toggles.

In uncontrolled mode `onChange` is still allowed on its own, as a notification.

### Accessibility

The trigger is a native `<button>`, so Enter/Space activation and the focus ring come for free, and it carries `aria-expanded` — that is what announces the state change on activation. The panel is a `role="region"` with an accessible name, and it sits immediately after its trigger in DOM order, so forward-tabbing reaches it next. Collapsing while focus is inside the panel hands focus back to the trigger rather than dropping it to `<body>`. The chevron's rotation and the panel's reveal both respect `prefers-reduced-motion`. Panel content wider than the viewport scrolls horizontally within the panel, and on a horizontally scrolled table the panel stays pinned to the left edge of the scrollport.

**Expand/collapse is animated** — the panel reveals by transitioning `grid-template-rows` from `0fr` to `1fr`, so it animates to its exact natural height whatever you render, with no height cap to clip tall content. One consequence worth knowing when writing tests against a table: `aria-expanded` flips immediately, but the detail row stays mounted for the ~300ms collapse (marked `data-state="closed"` meanwhile) before it is removed. Assert its removal with `waitFor` rather than synchronously. Under `prefers-reduced-motion` the transition is skipped, but the unmount is still deferred by the same interval.

**Known limitation — row count.** Detail rows are real `<tr>` elements, so a screen reader counts them: ten records with two expanded announces as twelve rows. Fixing this needs `aria-rowcount` plus explicit `aria-rowindex` on every row (with detail rows sharing their parent's index) and correct interaction with pagination; `role="presentation"` on the detail row would fix the count but remove the panel from screen-reader table navigation. Neither is implemented.

## `useDataTable`

Creates the table state object to pass to `DataTable.Root`.

```tsx
const table = useDataTable({
  columns,
  data,
  loading,
  control,
});
```

### Options

| Option              | Type                               | Description                                                                                                                                                                     |
| ------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `columns`           | `Column<TRow>[]`                   | Column definitions. Required.                                                                                                                                                   |
| `data`              | `DataTableData<TRow> \| undefined` | Fetched data. Pass `undefined` while loading.                                                                                                                                   |
| `loading`           | `boolean`                          | When `true`, renders a loading skeleton.                                                                                                                                        |
| `error`             | `Error \| null`                    | When set, renders an error message in the table body.                                                                                                                           |
| `control`           | `CollectionControl`                | Collection control from `useCollectionVariables()`. Required for `DataTable.Pagination` and `DataTable.Filters`.                                                                |
| `onClickRow`        | `(row: TRow) => void`              | Called when the user clicks a row. Adds a pointer cursor to rows.                                                                                                               |
| `tableId`           | `string`                           | Stable id used to persist per-user column layout (visibility, order, pinning) to `localStorage`. When omitted, column layout is in-memory only and resets on reload.            |
| `rowActions`        | `RowAction<TRow>[]`                | Per-row action items rendered in a kebab-menu column. The column is omitted when empty or not provided.                                                                         |
| `onSelectionChange` | `(ids: string[]) => void`          | Called with selected row IDs on change. Providing this enables the checkbox column. Rows must have a string `id`.                                                               |
| `rowExpansion`      | `RowExpansionOptions<TRow>`        | Expandable detail rows: `render`, plus optional `canExpand` / `getLabel`, and `expandedIds` + `onChange` together for controlled mode. See [Expandable rows](#expandable-rows). |
| `sort`              | `false \| { multiple?: boolean }`  | Sort behaviour. `false` disables sorting entirely. `{ multiple: true }` enables multi-column sorting. Omit or pass `{}` for single-column sort (default).                       |

### `DataTableData`

| Property   | Type             | Description                                                          |
| ---------- | ---------------- | -------------------------------------------------------------------- |
| `rows`     | `TRow[]`         | Row data to display.                                                 |
| `pageInfo` | `PageInfo`       | Cursor pagination info from the API.                                 |
| `total`    | `number \| null` | Total record count. Used for First/Last navigation and page counter. |

## `Column`

A column definition passed to `useDataTable`. `Column<TRow>` is a discriminated union on `type` — the shape of `typeOptions` is narrowed per branch, so mismatches are compile errors rather than silent runtime no-ops.

### Shared fields

| Property   | Type                                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ---------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `label`    | `string`                                  | Column header text. Omit for icon-only columns.                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `header`   | `(ctx: HeaderRenderContext) => ReactNode` | Custom header renderer. When omitted, the built-in header renders `label` and owns the sort button/indicator. When provided, the return value replaces the built-in header entirely; sortable custom headers receive `sortDirection` and `activateSort()` via `ctx` and must render their own click surface.                                                                                                                                                                                  |
| `render`   | `(row: TRow) => ReactNode`                | Renders the cell content. Optional — overrides the built-in `type` renderer when set.                                                                                                                                                                                                                                                                                                                                                                                                         |
| `id`       | `string`                                  | Stable identifier for column visibility and React key. Falls back to `label` when omitted.                                                                                                                                                                                                                                                                                                                                                                                                    |
| `width`    | `number`                                  | Fixed column width in pixels. Optional.                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `pin`      | `"left" \| "right"`                       | Freezes the column to that edge so it stays visible during horizontal scroll (the default; the user can override it via the toolbar's `columnSettings` control). Sticky offsets are measured from the rendered layout, so `width` isn't required — but setting `width` on pinned columns is recommended for stable sizing. The selection and expand columns auto-pin left and the row-actions column auto-pins right.                                                                         |
| `align`    | `"left" \| "right"`                       | Horizontal alignment. Defaults to `"right"` for `type: "number"` and `type: "money"`; `"left"` otherwise. Pass `"left"` to opt a numeric column out.                                                                                                                                                                                                                                                                                                                                          |
| `truncate` | `boolean`                                 | Truncate overflowing text with an ellipsis. Wires up an app-shell `<Tooltip>` automatically when the resolved cell value is a string or number — resolved via `accessor` first, then `row[col.id]` as a fallback — so hovering the cell reveals the full value. With `inferColumns`, no explicit `accessor` is needed because `id` is pinned to the field name. Requires another column to anchor the row width (`width` on a neighbor, or a fixed-size column like selection / row actions). |
| `accessor` | *(narrowed per `type`)*                   | Extracts the raw value. The return type is narrowed per `type` branch — returning an array is a compile error on all typed columns except `badge`, and returning a plain object is a compile error on all typed columns. Untyped columns (`type` omitted) retain `unknown`. `null` and `undefined` are always allowed.                                                                                                                                                                        |
| `sort`     | `SortConfig`                              | Sort configuration. When set, the column header becomes clickable (Asc → Desc → off).                                                                                                                                                                                                                                                                                                                                                                                                         |
| `filter`   | `FilterConfig`                            | Filter configuration. When set, the column appears as an option in `DataTable.Filters`.                                                                                                                                                                                                                                                                                                                                                                                                       |

### `type`-specific fields

| `type`      | `typeOptions`                                                |
| ----------- | ------------------------------------------------------------ |
| *(omitted)* | *(not allowed; provide `render` to draw the cell)*           |
| `"text"`    | *(not allowed)*                                              |
| `"number"`  | `NumberCellOptions`                                          |
| `"money"`   | `MoneyCellOptions<TRow>`                                     |
| `"date"`    | `DateCellOptions`                                            |
| `"badge"`   | `BadgeCellOptions`                                           |
| `"link"`    | **Required** — `LinkCellOptions<TRow>` (must include `href`) |

## Cell types

When `type` is set, the cell is rendered from `accessor(row)` (or `row[id]` when `accessor` is omitted) using a built-in renderer. Pass `render` to override on a per-column basis.

```tsx
column({
  label: "Total",
  accessor: (row) => row.total,
  type: "money",
  typeOptions: { currency: "USD", maxDecimals: 4 },
});
```

| `type`   | Accessor return type                                                                     | Value handling                                                            | Options interface                                                                                                             |
| -------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `text`   | `string \| number \| boolean \| bigint \| null \| undefined`                             | `String(value)` — falls back to `—` when nullish.                         | *(no options)*                                                                                                                |
| `number` | `number \| null \| undefined`                                                            | `Intl.NumberFormat`. `—` for nullish / NaN.                               | `NumberCellOptions`: `minDecimals`, `maxDecimals`, `locale`                                                                   |
| `money`  | `number \| null \| undefined`                                                            | `Intl.NumberFormat` currency. `—` for nullish.                            | `MoneyCellOptions<TRow>`: `currency` (string or `(row) => string`), `maxDecimals`, `locale`                                   |
| `date`   | `Date \| string \| number \| null \| undefined`                                          | `Intl.DateTimeFormat`. Accepts `Date`/ISO/epoch.                          | `DateCellOptions`: `dateFormat` (`"short"` | `"long"` | `"datetime"`), `locale`                                             |
| `badge`  | `string \| number \| boolean \| null \| undefined \| Array<string \| number \| boolean>` | `<Badge>` keyed off the stringified value. Arrays render multiple badges. | `BadgeCellOptions`: `badgeVariantMap`, `badgeLabelMap`, `defaultBadgeVariant` (defaults to `"outline-neutral"`), `maxVisible` |
| `link`   | `string \| number \| boolean \| null \| undefined`                                       | app-shell `<Link>` to `typeOptions.href(row)`.                            | `LinkCellOptions<TRow>`: `href: (row) => string \| null \| undefined` (returning nullish renders plain text; **required**)    |

Empty values (`null`, `undefined`, `""`) render a muted `—` placeholder for every type. Use `render` for custom empty-state handling.

The discriminated-union shape means:

```tsx
// ❌ Compile error — badgeVariantMap is not a money option
column({ type: "money", accessor: (r) => r.total, typeOptions: { badgeVariantMap: {} } });

// ❌ Compile error — link columns must provide typeOptions.href
column({ type: "link", accessor: (r) => r.title });

// ❌ Compile error — text columns reject typeOptions entirely
column({ type: "text", accessor: (r) => r.title, typeOptions: { locale: "en-US" } });

// ❌ Compile error — text/number/money/link accessor cannot return an array or object
column({ type: "text", accessor: (row) => row.tags }); // row.tags is string[]
column({ type: "number", accessor: (row) => row.meta }); // row.meta is an object
```

## Adding a typed column

Each column type follows the same three-step shape: pick a `type`, point `accessor` at the value, and pass `typeOptions` for the type-specific bits. `label`, `sort`, `filter`, `align`, `width`, and `id` work the same regardless of `type`.

### `text` — plain string

```tsx
column({
  label: "Name",
  accessor: (row) => row.name,
  type: "text",
});
```

* `null` / `undefined` / `""` render a muted `—`.
* No `typeOptions` are accepted on `text` columns.
* Omit `type` entirely if you want to keep `render` required for that column.

### `number` — locale-formatted number

```tsx
column({
  label: "Stock",
  accessor: (row) => row.stockOnHand,
  type: "number",
  typeOptions: { minDecimals: 0, maxDecimals: 0, locale: "en-US" },
});
```

* `minDecimals` / `maxDecimals` default to `0`.
* `maxDecimals` defaults to `minDecimals` when only `minDecimals` is set — pass both for ranges (e.g. `min: 2, max: 4`).
* `NaN` and `null` render the `—` placeholder.

### `money` — currency

```tsx
column({
  label: "Total",
  accessor: (row) => row.total,
  type: "money",
  typeOptions: { currency: "USD" },
});
```

For mixed-currency tables, read `currency` from the row:

```tsx
column({
  label: "Total",
  accessor: (row) => row.total,
  type: "money",
  typeOptions: {
    currency: (row) => row.currencyCode, // "USD", "JPY", "EUR", …
    maxDecimals: 4, // raise the cap above the currency default
  },
});
```

* Default `currency` is `"USD"` when omitted or when the accessor returns falsy.
* Invalid ISO codes fall back to USD (rather than throwing).
* The minimum decimals always stays at the currency default (2 for USD, 0 for JPY); `maxDecimals` raises the cap without padding with trailing zeros.

### `date` — formatted date

```tsx
column({
  label: "Placed",
  accessor: (row) => row.placedAt, // Date | ISO string | epoch ms
  type: "date",
  typeOptions: { dateFormat: "short" }, // "short" | "long" | "datetime"
});
```

| `dateFormat`        | Example output         |
| ------------------- | ---------------------- |
| `"short"` (default) | `Apr 9, 2026`          |
| `"long"`            | `April 9, 2026`        |
| `"datetime"`        | `Apr 9, 2026, 3:45 PM` |

* Accepts a `Date`, an ISO 8601 string, or epoch milliseconds.
* Invalid dates render the `—` placeholder.

### `badge` — status pill

```tsx
column({
  label: "Status",
  accessor: (row) => row.status,
  type: "badge",
  typeOptions: {
    badgeVariantMap: {
      shipped: "success",
      processing: "outline-warning",
      cancelled: "subtle-error",
    },
    badgeLabelMap: {
      shipped: "Shipped",
      processing: "Processing",
      cancelled: "Cancelled",
    },
    defaultBadgeVariant: "outline-neutral", // unmapped values fall back here
  },
});
```

* The cell value is stringified before lookup, so `accessor` can return strings, numbers, or booleans.
* `accessor` may also return an **array** of values — each item is rendered as a separate badge.
* Unmapped values render with `defaultBadgeVariant` (or `"outline-neutral"`) and the raw stringified value as the label.

#### Array badges with overflow

Use `maxVisible` to cap the number of badges shown. Extra values are hidden behind a hover popover:

```tsx
column({
  ...infer("tags"),
  type: "badge",
  typeOptions: {
    badgeVariantMap: { Premium: "warning", Office: "outline-info" },
    maxVisible: 2,
  },
});
```

### `link` — clickable text

```tsx
column({
  label: "Order",
  accessor: (row) => row.reference,
  type: "link",
  typeOptions: { href: (row) => `/orders/${row.id}` },
});
```

* `href` is **required** on `link` columns — it's enforced by the type.
* Returning `null` / `undefined` from `href` renders the cell value as plain text (useful for "no detail page yet" rows).
* Uses the app-shell `<Link>` (react-router) so SPA navigation is preserved. For external URLs, fall back to `render` with a plain `<a>`.

### Overriding a built-in renderer

`render` always wins over the built-in renderer, so the escape hatch stays open per column:

```tsx
column({
  label: "Status",
  accessor: (row) => row.status,
  type: "badge",
  typeOptions: { badgeVariantMap: { active: "success" } },
  // Custom render with an icon — type/typeOptions are still required for
  // sort/filter scaffolding but are bypassed for rendering.
  render: (row) => (
    <span className="flex items-center gap-1">
      <CircleCheck className="size-3" />
      {row.status}
    </span>
  ),
});
```

### Combining `type` with `inferColumns`

`inferColumns` (from `@tailor-platform/app-shell-sdk-plugin`) derives `label`, `sort`, `filter`, and `id` from TailorDB metadata. You can layer a `type` on top to get a built-in renderer without losing the inferred sort/filter config:

```tsx
const infer = inferColumns(tableMetadata.order);

const columns = [
  // Inferred column — displays row[id] as plain text
  column(infer("reference")),

  // Inferred datetime column, swapped to a `date` cell with long format
  column({
    ...infer("placedAt"),
    type: "date",
    typeOptions: { dateFormat: "long" },
    accessor: (row) => row.placedAt,
  }),

  // Inferred enum column, rendered as a badge
  column({
    ...infer("status"),
    type: "badge",
    accessor: (row) => row.status,
    typeOptions: {
      badgeVariantMap: { active: "success", draft: "neutral" },
    },
  }),
];
```

When you spread `...infer("field")`, add `accessor` when you want a typed renderer to read a specific value — built-in renderers read from `accessor` (or `row[id]`).

## `FilterConfig`

The `filter` property on a column accepts the same base shape as `FilterConfig`, plus a DataTable-only `operators` allowlist. When set, the column becomes filterable in `DataTable.Filters` — available in the **Add filter** panel, and rendered as a segmented chip once active.

| Property    | Type                                             | Description                                                                                                    |
| ----------- | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
| `field`     | `string`                                         | API field name used in the generated query input.                                                              |
| `type`      | `FilterType`                                     | Filter editor type (see table below).                                                                          |
| `options`   | `SelectOption[]`                                 | Required when `type` is `"enum"`. List of selectable values.                                                   |
| `operators` | `readonly [FilterOperator, ...FilterOperator[]]` | Optional non-empty DataTable UI allowlist. Order controls menu order and, when provided, the default operator. |

`operators` only narrows what the built-in DataTable filter UI shows. Programmatic `CollectionControl.addFilter(...)`, URL state, and saved/persisted filters still use the broader backend operator set. When `operators` is omitted, the built-in UI keeps the normal default for that field type (for example, string fields still default to `contains`).

### Adding and editing filters

`DataTable.Filters` renders active filters as segmented chips followed by an **Add filter** button:

* **Add filter panel** — a single popover laid out in up to three columns: **field ▸ condition ▸ value**. The condition column appears for fields with more than one operator (number, date/time, string); single-operator fields (enum, uuid) go straight to the value. Enter a value and click **Apply**; the panel stays open so several filters can be added in a row.
* **Segmented chip** — each active filter shows `field │ operator │ value │ ✕`. The operator segment opens a searchable dropdown to change the condition; the value segment reopens the type-specific editor; `✕` removes the filter. Multi-select enum values are summarized as "N items" (e.g. "2 statuses").

### Filter Types and Operators

| Type       | Input editor              | Supported operators                                                                                          |
| ---------- | ------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `string`   | Text                      | `eq`, `ne`, `contains`, `notContains`, `hasPrefix`, `hasSuffix`, `notHasPrefix`, `notHasSuffix`, `in`, `nin` |
| `number`   | Number                    | `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, **`between`**, `in`, `nin`                                             |
| `datetime` | Datetime-local            | `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, **`between`**, `in`, `nin`                                             |
| `date`     | **Calendar / DatePicker** | `eq` (*exact date*), `gte` (*after*), `lte` (*before*), **`between`**                                        |
| `time`     | Time                      | `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, **`between`**, `in`, `nin`                                             |
| `enum`     | Dropdown                  | `eq`, `ne`, `in`, `nin`                                                                                      |
| `boolean`  | Toggle                    | `eq`, `ne`                                                                                                   |
| `uuid`     | Text                      | `eq`, `ne`, `in`, `nin`                                                                                      |

When the `between` operator is selected on a `number`, `datetime`, `date`, or `time` column, the value editor renders a range input with **min**/**max** (or **From**/**To** for dates) bounds.

### Date Filters

`date` columns render app-shell date components as the value editor: single-value operators (`eq` / `gte` / `lte`) use an inline `Calendar`, and the `between` range uses two [`DatePicker`](date-picker) **From** / **To** fields. (The range fields are a stopgap — they'll be replaced with a single range calendar once date-range support lands in the date-picker component.) `date` columns also present a friendlier, slimmer operator set:

| Operator  | Label        | Meaning                    |
| --------- | ------------ | -------------------------- |
| `eq`      | *exact date* | matches that calendar date |
| `gte`     | *after*      | on or after (inclusive)    |
| `lte`     | *before*     | on or before (inclusive)   |
| `between` | *between*    | inclusive min–max range    |

`gt` / `lt` / `ne` are intentionally dropped — the inclusive *after* / *before* cover the intent. The filter chip shows the value as a locale-formatted date (e.g. `15 Jun 2026`), and the picker resolves its locale/timezone from the AppShell context. (Only `date` is remapped this way; `datetime` and `time` keep the full numeric operator set and native inputs.)

### String Filter Case Sensitivity

String filters are **case-insensitive by default** — they use the Tailor Platform `regex` operator with an `(?i)` prefix. The filter chip renders a **"Case sensitive"** checkbox that lets users opt into exact-case matching.

To control this behavior programmatically, pass `caseSensitive: true` to `CollectionControl.addFilter`:

```tsx
control.addFilter("title", "contains", "acme", { caseSensitive: true });
```

You can also set `caseSensitive` directly on a `Filter` object when using `params.initialFilters` in `useCollectionVariables`:

```tsx
const { variables, control } = useCollectionVariables({
  params: {
    initialFilters: [{ field: "title", operator: "contains", value: "acme", caseSensitive: true }],
  },
});
```

When `caseSensitive` is omitted or `false`, the filter is case-insensitive. When `true`, the filter matches the exact case of the input.

## `RowAction`

| Property     | Type                         | Description                                          |
| ------------ | ---------------------------- | ---------------------------------------------------- |
| `id`         | `string`                     | Stable identifier for the action.                    |
| `label`      | `string`                     | Display label in the kebab menu.                     |
| `icon`       | `ReactNode`                  | Optional icon shown beside the label.                |
| `variant`    | `"default" \| "destructive"` | Visual style of the menu item.                       |
| `isDisabled` | `(row: TRow) => boolean`     | Return `true` to disable the action for a given row. |
| `onClick`    | `(row: TRow) => void`        | Called when the action is clicked.                   |

## `createColumnHelper`

Factory that captures the row type once and returns `column` and `inferColumns` with `TRow` already bound. Prefer this over the standalone `column()` function to avoid repeating the generic parameter.

```tsx
const { column, inferColumns } = createColumnHelper<Order>();
```

### `column(options)`

Defines a column with an explicit render function.

```tsx
column({ label: "Name", render: (row) => row.name });
column({ label: "Actions", render: (row) => <button>Edit {row.name}</button> });
```

### `inferColumns(tableMetadata)`

Binds table metadata and returns a per-field column factory. The factory derives `label`, `sort`, `filter` config, and `id` automatically from the field's metadata. `id` is always pinned to the metadata field name — this stabilizes the React key / column-visibility identifier and enables the `truncate` tooltip without an explicit `accessor`. Requires metadata generated by `@tailor-platform/app-shell-sdk-plugin`.

```tsx
const infer = inferColumns(tableMetadata.order);

const columns = [
  column(infer("title")),
  column(infer("status")),
  column({ ...infer("createdAt"), render: (row) => formatDate(row.createdAt) }),
];
```

The factory accepts an optional second argument to override per-column defaults:

| Option   | Type                                                                        | Default                                     | Description                                                                                                                              |
| -------- | --------------------------------------------------------------------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `label`  | `string`                                                                    | Field `description` or `name` from metadata | Override the column header text.                                                                                                         |
| `width`  | `number`                                                                    | —                                           | Fixed column width in pixels.                                                                                                            |
| `sort`   | `boolean`                                                                   | `true`                                      | Set to `false` to suppress the auto-generated sort config.                                                                               |
| `filter` | `boolean \| { operators?: readonly [FilterOperator, ...FilterOperator[]] }` | `true`                                      | Set to `false` to suppress the auto-generated filter config, or pass a non-empty `operators` allowlist to narrow the built-in filter UI. |

Like `column.filter`, `operators` only affects the built-in DataTable UI. Order controls menu order and, when provided, the default operator. Programmatic `CollectionControl.addFilter(...)`, URL state, and saved/persisted filters still accept the broader backend operator set.

## `useCollectionVariables`

Manages collection query state (filters, sort, pagination) and derives `variables` for GraphQL queries.

```tsx
const { variables, control } = useCollectionVariables({
  params: { pageSize: 20 },
});

// variables.pagination → { first, after? } or { last, before? }
// variables.query      → filter input object or undefined
// variables.order      → sort input array or undefined
```

### Options

| Option                  | Type                                 | Description                                                                                                           |
| ----------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
| `params.pageSize`       | `number`                             | Initial page size. Default: `20`.                                                                                     |
| `params.initialFilters` | `Filter[]`                           | Filters applied on first render.                                                                                      |
| `params.initialSort`    | `SortState[]`                        | Sort applied on first render.                                                                                         |
| `tableMetadata`         | `TableMetadata`                      | Generated table metadata. Required for typed GraphQL documents (see [Typed query variables](#typed-query-variables)). |
| `onParamsChange`        | `(params: CollectionParams) => void` | Called after each filter, sort, or page-size change with the current params.                                          |

### Return Value

| Property    | Type                  | Description                                                    |
| ----------- | --------------------- | -------------------------------------------------------------- |
| `variables` | `CollectionVariables` | Derived `query`, `order`, and `pagination` sub-properties.     |
| `control`   | `CollectionControl`   | State and methods for filter, sort, and pagination management. |

`useCollectionVariables` is decoupled from `DataTable` by design — the hook owns only query state and exposes plain variables. Any collection-based view (Kanban, Gantt, custom components) can use the same hook without modification.

### Typed query variables

When using typed GraphQL documents (`TypedDocumentNode`), pass `tableMetadata` to `useCollectionVariables`. This narrows `variables.query` and `variables.order` from `unknown` to the precise types expected by the generated document.

```tsx
import { tableMetadata } from "@/generated/app-shell-datatable.generated";

const { variables, control } = useCollectionVariables({
  tableMetadata: tableMetadata.order,
  params: { pageSize: 20 },
});

// variables.query is now BuildQueryVariables<typeof tableMetadata.order>
// variables.order is now { field: OrderableFieldName; direction: "Asc" | "Desc" }[]
const [result] = useQuery({
  query: LIST_ORDERS, // TypedDocumentNode — variables are fully type-checked
  variables: {
    ...variables.pagination,
    query: variables.query,
    order: variables.order,
  },
});
```

## `useURLCollectionVariables`

Wraps `useCollectionVariables` with automatic URL persistence. It seeds filter, sort, and page-size state from the current URL search params on mount and writes changes back to the URL as the user interacts with the table — using `replace` navigation so individual interactions don't push new history entries.

Use this instead of `useCollectionVariables` when you want filters, sort, and pagination to survive page refreshes and be shareable via URL.

```tsx
import { useURLCollectionVariables } from "@tailor-platform/app-shell";

const { variables, control } = useURLCollectionVariables({
  tableMetadata,
  params: { pageSize: 20 },
});
```

The return value is identical to `useCollectionVariables` — `variables` and `control`.

### Options

All options accepted by `useCollectionVariables` are accepted here too. `tableMetadata` is optional but recommended for typed variables and correct URL round-tripping of typed field values (numbers and booleans are preserved correctly).

### URL format

| State      | URL key                | Example               |
| ---------- | ---------------------- | --------------------- |
| `pageSize` | `p`                    | `?p=20`               |
| Sort       | `s`                    | `?s=createdAt:desc`   |
| Filter     | `f.<field>:<operator>` | `?f.status:eq=ACTIVE` |

### Custom search-params binding: `withURLCollectionState`

If you need URL persistence but cannot use react-router's `useSearchParams` (e.g. a different router or test environment), use the pure `withURLCollectionState` decorator to compose URL state with `useCollectionVariables` directly:

```tsx
import { withURLCollectionState, useCollectionVariables } from "@tailor-platform/app-shell";

const [searchParams, setSearchParams] = useSearchParams();

const { variables, control } = useCollectionVariables(
  withURLCollectionState({ tableMetadata, params: { pageSize: 20 } }, [
    searchParams,
    setSearchParams,
  ]),
);
```

`withURLCollectionState` returns augmented `useCollectionVariables` options — it does not call the hook itself. The `[searchParams, setSearchParams]` tuple must match the `URLSearchParams` + setter shape that `useSearchParams()` returns.

## `useDataTableContext`

Accesses the full DataTable state from any component rendered inside `DataTable.Root`. Use this to build custom sub-components when the built-in ones don't fit.

```tsx
import { useDataTableContext } from "@tailor-platform/app-shell";

function MyCustomPagination() {
  const { pageInfo, goToNextPage, goToPrevPage, hasNextPage, hasPrevPage } = useDataTableContext();
  // ...
}
```

## SDK Plugin (`@tailor-platform/app-shell-sdk-plugin`)

The SDK plugin generates `tableMetadata` from TailorDB table definitions at generate time. This metadata bridges your schema to the DataTable — it specifies how each field should be rendered and filtered (e.g. date pickers for datetime fields, dropdown for enum fields).

Register the plugin in `tailor.config.ts` and run `tailor generate`:

```ts
import { definePlugins } from "@tailor-platform/sdk";
import { appShellPlugin } from "@tailor-platform/app-shell-sdk-plugin";

export const plugins = definePlugins(
  appShellPlugin({
    dataTable: {
      metadataOutputPath: "src/generated/app-shell-datatable.generated.ts",
    },
  }),
);
```

The generated file exports `tableMetadata`, `tableNames`, and `TableName`. Pass `tableMetadata` to `inferColumns` to get type-safe column definitions with filter editors automatically configured:

```ts
import { tableMetadata } from "@/generated/app-shell-datatable.generated";
import { createColumnHelper } from "@tailor-platform/app-shell";

const { column, inferColumns } = createColumnHelper<Order>();
const infer = inferColumns(tableMetadata.order);

const columns = [
  column(infer("title")), // string → text filter
  column(infer("status")), // enum   → dropdown filter with generated values
  column(infer("createdAt")), // datetime → date picker filter
];
```

## Related

* [CsvImporter](csv-importer) — Guided CSV import flow
* [Table](table) — Low-level table primitives used internally by DataTable

---

---
url: https://docs.tailor.tech/app-shell/components/date-picker.md
description: Accessible date input components (@internationalized/date + Base UI)
---

# DatePicker

Three related components for date input — a segmented field, a field with a calendar popover, and a standalone calendar grid. Built on `@internationalized/date` and Base UI.

[Live preview in the UI Catalogue →](https://ui.tailor.tech/components/date-picker)

## Import

```tsx
import {
  DateField,
  DatePicker,
  DateRangePicker,
  Calendar,
  RangeCalendar,
  Field,
  // Date value helpers (re-exported from @internationalized/date)
  parseDate,
  getLocalTimeZone,
  today,
  type CalendarDate,
  type DateValue,
  type DateRange,
} from "@tailor-platform/app-shell";
```

## API shape

`DateField` and `DatePicker` are standalone composite controls.

* They own date entry, keyboard behavior, constraints, locale/timezone handling, and form value serialization.
* They expose standard labeling hooks: `id`, `aria-label`, `aria-labelledby`, `aria-describedby`, and `isInvalid`.
* They also auto-wire into `Field.Root`, so `Field.Label`, `Field.Description`, `Field.Error`, and form validation state work the same way as the other AppShell form controls.

## DateField

Standalone usage with an accessible name:

```tsx
<DateField aria-label="Invoice date" />
```

With a visible label + description:

```tsx
<label id="invoice-date-label" htmlFor="invoice-date">
  Invoice date
</label>
<DateField
  id="invoice-date"
  aria-labelledby="invoice-date-label"
  aria-describedby="invoice-date-help"
/>
<p id="invoice-date-help">Format follows your locale</p>
```

Inside `Field.Root`:

```tsx
<Field.Root name="invoiceDate">
  <Field.Label>Invoice date</Field.Label>
  <DateField />
  <Field.Description>Format follows your locale</Field.Description>
</Field.Root>
```

Controlled:

```tsx
const [date, setDate] = useState<CalendarDate | null>(null);

<DateField aria-label="Invoice date" value={date} onChange={setDate} />;
```

## DatePicker

A `DateField` with a calendar popover.

```tsx
<DatePicker aria-label="Ship date" />
```

Constrained + unavailable dates:

```tsx
<label id="delivery-date-label" htmlFor="delivery-date">
  Delivery date
</label>
<DatePicker
  id="delivery-date"
  aria-labelledby="delivery-date-label"
  minValue={today(getLocalTimeZone())}
  isDateUnavailable={(date) => {
    const dow = date.toDate(getLocalTimeZone()).getDay();
    return dow === 0 || dow === 6; // weekends
  }}
/>
```

Week start:

```tsx
<DatePicker aria-label="Date" firstDayOfWeek="mon" />
```

## Validation and errors

Use standard HTML + ARIA when rendering the field standalone:

```tsx
<label id="delivery-date-label" htmlFor="delivery-date">
  Delivery date
</label>
<DatePicker
  id="delivery-date"
  aria-labelledby="delivery-date-label"
  aria-describedby={error ? "delivery-date-error" : undefined}
  isInvalid={!!error}
  value={value}
  onChange={setValue}
/>
{error && <p id="delivery-date-error">{error}</p>}
```

Or let `Field.Root` wire the label, description, and error elements:

```tsx
<Field.Root name="deliveryDate" error={error ? { message: error } : undefined}>
  <Field.Label>Delivery date</Field.Label>
  <DatePicker value={value} onChange={setValue} />
  <Field.Error match={!!error}>{error}</Field.Error>
</Field.Root>
```

## Calendar

A standalone calendar grid for custom date-selection UIs.

```tsx
<Calendar aria-label="Select date" onChange={(date) => console.log(date)} />
```

## DateRangePicker

Start and end segmented inputs sharing one calendar popover, with a `{ start, end }` value (`DateRange`) — a **separate component** from `DatePicker`, not a mode. Same composition model as the other controls: standalone with `aria-*`, or inside `Field.Root`. Selection follows the react-aria model — the first calendar pick anchors the range and keeps the popover open, the highlight follows the pointer/arrows, and the second pick completes it; picking backwards swaps the endpoints, while a range **typed** in reverse is flagged invalid (`Field.Error match="customError"`) rather than swapped.

```tsx
const [range, setRange] = useState<DateRange | null>(null);

// standalone
<DateRangePicker aria-label="Billing period" value={range} onChange={setRange} />

// composed
<Field.Root name="period">
  <Field.Label>Billing period</Field.Label>
  <DateRangePicker />
  <Field.Error match="customError" />
</Field.Root>
```

A single combined proxy input is registered as the one Field control — its value is empty until **both** ends are complete, so `isRequired` blocks a partial range. Give that combined input a `name` for a single `start/end` native-POST field (a wrapping `Field.Root` name wins), or use `startName` / `endName` to emit two plain hidden inputs for classic form-POST.

## RangeCalendar

The standalone inline range calendar (the grid inside `DateRangePicker`), for custom layouts.

```tsx
<RangeCalendar aria-label="Stay dates" onChange={(range) => console.log(range)} />
```

## Localization

Locale and timezone come from AppShell automatically. Override per field with `locale` / `timeZone`:

```tsx
<DatePicker aria-label="Date" locale="ja-JP" />
```

## Keyboard

* **Segments:** `↑`/`↓` increment/decrement, digits type-to-fill (auto-advance), `←`/`→` move between segments, `Backspace` clears, `/` commits the current segment and advances.
* **Whole-date shortcuts:** `t` today · `m`/`h` start/end of the entered month · `y`/`r` start/end of the year · `w`/`k` start/end of the week · `-` previous day · `=`/`+` next day.
* **Calendar grid:** arrows move by day/week, `Home`/`End` to week start/end, `PageUp`/`PageDown` by month, `Shift`+`PageUp`/`PageDown` by year, `Enter`/`Space` selects. `Alt`+`↓` opens the calendar from the field.

## Props

### DateFieldProps

| Prop                             | Type                                                          | Description                                                |
| -------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------- |
| `value` / `defaultValue`         | `DateValue \| null`                                           | Controlled / uncontrolled value                            |
| `onChange`                       | `(v: DateValue \| null) => void`                              | Fires when the value changes                               |
| `onBlur`                         | `() => void`                                                  | Fires when focus leaves the whole segmented control        |
| `minValue` / `maxValue`          | `DateValue`                                                   | Inclusive date range bounds                                |
| `isDateUnavailable`              | `(date: DateValue) => boolean`                                | Marks specific dates unavailable                           |
| `isDisabled`                     | `boolean`                                                     | Disables interaction and form submission                   |
| `isReadOnly`                     | `boolean`                                                     | Allows focus/navigation without editing                    |
| `isRequired`                     | `boolean`                                                     | Marks the control required                                 |
| `isInvalid`                      | `boolean`                                                     | Adds invalid styling / `aria-invalid` to the segmented UI  |
| `placeholderValue`               | `DateValue`                                                   | Seeds unset segments                                       |
| `autoFocus`                      | `boolean`                                                     | Focus the first segment on mount                           |
| `locale`                         | `string`                                                      | BCP-47 locale override                                     |
| `name`                           | `string`                                                      | Emits a form value through the proxy input                 |
| `id`                             | `string`                                                      | Proxy input id (use with external `<label htmlFor>`).      |
| `firstDayOfWeek`                 | `"sun" \| "mon" \| "tue" \| "wed" \| "thu" \| "fri" \| "sat"` | Override the locale week start used by `w` / `k` shortcuts |
| `aria-label` / `aria-labelledby` | `string`                                                      | Accessible name                                            |
| `aria-describedby`               | `string`                                                      | IDs of description / error elements                        |
| `className`                      | `string`                                                      | Root element class                                         |

### DatePickerProps

All `DateFieldProps`, plus:

| Prop             | Type                    | Description                         |
| ---------------- | ----------------------- | ----------------------------------- |
| `timeZone`       | `string`                | IANA timezone for resolving "today" |
| `firstDayOfWeek` | `"sun" \| "mon" \| ...` | Force the calendar's first column   |

### CalendarProps

See the calendar docs in-code: controlled/uncontrolled value, min/max, unavailable dates, focused date, locale, timezone, accessible naming, and className.

### DateRangePickerProps

The `DatePickerProps` surface (labeling, `isInvalid`, `min/maxValue`, `isDateUnavailable`, `granularity`, `firstDayOfWeek`, `timeZone`, `locale`, `autoFocus`, `isDisabled/ReadOnly/Required`), with the range-specific differences:

| Prop                     | Type                             | Description                                                                     |
| ------------------------ | -------------------------------- | ------------------------------------------------------------------------------- |
| `value` / `defaultValue` | `DateRange \| null`              | Controlled / uncontrolled `{ start, end }` range                                |
| `onChange`               | `(v: DateRange \| null) => void` | Fires with a complete range, or `null` when cleared/incomplete                  |
| `name`                   | `string`                         | One combined hidden input (`start/end`) for native POST; `Field.Root` name wins |
| `startName` / `endName`  | `string`                         | Emit two plain hidden inputs with the ISO start/end (classic POST)              |

A typed range with `end` before `start` sets the invalid state and reports a built-in `customError` message (`Field.Error match="customError"`); the calendar always commits ordered endpoints.

### RangeCalendarProps

Same surface as `CalendarProps`, with `value` / `defaultValue`: `DateRange | null` and `onChange`: `(v: DateRange) => void` (fired once per selection, when the second date completes the range).

## Related

* [useTimeZone](../api/use-time-zone)
* [useResolvedLocale](../api/use-resolved-locale)

---

---
url: https://docs.tailor.tech/app-shell/components/default-header.md
description: The built-in SidebarLayout top bar, extensible via an actions slot
---

# DefaultHeader

`DefaultHeader` is the built-in top bar rendered by [`SidebarLayout`](sidebar-layout). It shows the sidebar trigger and breadcrumb trail on the left, and an `actions` cluster (defaulting to the [`AppearanceSwitcher`](appearance-switcher)) on the right.

It is exposed as `SidebarLayout.DefaultHeader` (and as a top-level `DefaultHeader` export) so you can slightly extend the built-in header — the common case being adding a notification bell or user menu — without reconstructing the trigger and breadcrumb yourself.

## Import

```tsx
import { SidebarLayout } from "@tailor-platform/app-shell";
// SidebarLayout.DefaultHeader

// or, equivalently:
import { DefaultHeader } from "@tailor-platform/app-shell";
```

## Usage

`DefaultHeader` goes into `SidebarLayout`'s [`header`](sidebar-layout.md#header) slot:

```tsx
import { SidebarLayout, AppearanceSwitcher, Button } from "@tailor-platform/app-shell";
import { BellIcon } from "lucide-react";

<SidebarLayout
  header={
    <SidebarLayout.DefaultHeader
      actions={[
        <Button key="bell" variant="outline" size="icon" aria-label="Notifications">
          <BellIcon />
        </Button>,
        <AppearanceSwitcher key="appearance" />,
      ]}
    />
  }
/>;
```

## Props

### actions

* **Type:** `React.ReactNode | React.ReactNode[]` (optional)
* **Default:** `[<AppearanceSwitcher />]`
* **Description:** The entire right-hand cluster of the header. Rendered in a horizontal, vertically-centered row (`flex flex-row items-center gap-2`) with consistent spacing — you don't wrap it yourself. Accepts a single node or an array of nodes.

> ⚠️ **`actions` replaces the whole right-hand cluster, including the appearance switcher.**
>
> * Omitting `actions` keeps the default (`[<AppearanceSwitcher />]`), so the out-of-the-box header is unchanged.
> * If you pass your own `actions` and still want the switcher, include `<AppearanceSwitcher />` in the array — it is a public export.
> * `actions={[]}` renders an empty right side.

This "the switcher is just another action" contract keeps the API a single slot rather than accumulating one-off props like `hideAppearanceSwitcher`.

## When to use which level of customization

| Goal                              | Approach                                                                        |
| --------------------------------- | ------------------------------------------------------------------------------- |
| The standard header               | Omit `header` on `SidebarLayout`                                                |
| Add controls next to the switcher | `header={<SidebarLayout.DefaultHeader actions={[...]} />}`                      |
| A completely different header     | `header={<MyCustomHeader />}` (see [SidebarLayout](sidebar-layout.md#header)) |

## Related Components

* [SidebarLayout](sidebar-layout) - Hosts the header via the `header` slot
* [DefaultSidebar](default-sidebar) - The sibling built-in region (`SidebarLayout.DefaultSidebar`)
* [AppearanceSwitcher](appearance-switcher) - Default action; include it in `actions` to keep it
* [Button](button) - For building icon actions

---

---
url: https://docs.tailor.tech/app-shell/components/default-sidebar.md
description: Pre-built sidebar component that renders navigation from AppShell modules
---

# DefaultSidebar

The default sidebar component that automatically renders navigation items from the AppShell context. This is a convenience component that provides a ready-to-use sidebar without manual configuration.

> Also available as **`SidebarLayout.DefaultSidebar`**. The namespaced form is preferred for discoverability (it pairs with [`SidebarLayout.DefaultHeader`](default-header)); the top-level `DefaultSidebar` export is kept for backwards compatibility. Both refer to the same component.

## Props

| Prop     | Type              | Required | Description           |
| -------- | ----------------- | -------- | --------------------- |
| `header` | `React.ReactNode` | No       | Custom header content |
| `footer` | `React.ReactNode` | No       | Custom footer content |

## Usage

### Basic Usage

```typescript
import { DefaultSidebar } from "@tailor-platform/app-shell";

function Layout() {
  return <DefaultSidebar />;
}
```

### With Custom Header

```typescript
import { DefaultSidebar } from "@tailor-platform/app-shell";

function CompanyLogo() {
  return (
    <div className="p-4">
      <img src="/logo.svg" alt="Company" />
    </div>
  );
}

function Layout() {
  return <DefaultSidebar header={<CompanyLogo />} />;
}
```

### With Custom Footer

```typescript
function UserProfile() {
  const { context } = useAppShell();

  return (
    <div className="p-4 border-t">
      <p>{context.currentUser?.name}</p>
      <button>Logout</button>
    </div>
  );
}

function Layout() {
  return <DefaultSidebar footer={<UserProfile />} />;
}
```

### With Both Header and Footer

```typescript
function Layout() {
  return (
    <DefaultSidebar
      header={<CompanyLogo />}
      footer={<UserProfile />}
    />
  );
}
```

## Features

* **Auto-Navigation**: Automatically renders all modules and resources from AppShell, including the root module (path `""` or `"/"`) when defined. When a `rootComponent` is passed to `AppShell` without an explicit root module, a synthetic root entry is injected with a localized `"Home"` title.
* **Search Entry**: Always renders a **Search** button at the top of the navigation menu that opens the CommandPalette (equivalent to `Cmd+K` / `Ctrl+K`). This is available regardless of whether `searchSources` are configured on `AppShell`.
* **Active State**: Highlights the current route
* **Collapsible Groups**: Supports nested resource groups
* **Responsive**: Adapts to mobile and desktop layouts
* **Customizable**: Add header/footer content as needed

## Using in SidebarLayout

The `DefaultSidebar` is commonly used with `SidebarLayout`:

```typescript
import { SidebarLayout, DefaultSidebar } from "@tailor-platform/app-shell";

<SidebarLayout
  sidebar={
    <DefaultSidebar
      header={<Logo />}
      footer={<UserMenu />}
    />
  }
>
  <Outlet />
</SidebarLayout>
```

## Custom Navigation

If you need more control over navigation rendering, build a custom sidebar using:

* [SidebarItem](sidebar-item) - Individual navigation links
* [SidebarGroup](sidebar-group) - Collapsible navigation groups
* [WithGuard](with-guard) - Conditional rendering based on access control

```typescript
import { SidebarItem, SidebarGroup } from "@tailor-platform/app-shell";

function CustomSidebar() {
  return (
    <div>
      <SidebarItem to="/dashboard" />
      <SidebarGroup title="Products">
        <SidebarItem to="/products/all" />
        <SidebarItem to="/products/create" />
      </SidebarGroup>
    </div>
  );
}
```

## Related

* [SidebarLayout](sidebar-layout) - Layout wrapper for sidebar + content
* [SidebarItem](sidebar-item) - Individual navigation links
* [SidebarGroup](sidebar-group) - Collapsible navigation groups
* [Sidebar Navigation](../concepts/sidebar-navigation) - Complete navigation guide

---

---
url: https://docs.tailor.tech/app-shell/components/description-card.md
description: >-
  Display structured key-value information in a responsive grid layout with
  automatic field rendering
---

# DescriptionCard

`DescriptionCard` is a powerful component for displaying structured document information in ERP applications. It automatically renders field-value pairs in a responsive grid with support for multiple field types, dividers, and smart empty value handling.

[Live preview in the UI Catalogue →](https://ui.tailor.tech/components/description-card)

## Import

```tsx
import { DescriptionCard } from "@tailor-platform/app-shell";
```

## Basic Usage

```tsx
const orderData = {
  orderNumber: "ORD-12345",
  customer: "Acme Corporation",
  status: "shipped",
  totalAmount: 15750.0,
  currency: "USD",
  orderDate: "2026-03-01T10:00:00Z",
};

<DescriptionCard
  data={orderData}
  fields={[
    { key: "orderNumber", label: "Order Number" },
    { key: "customer", label: "Customer" },
    { key: "status", label: "Status", type: "badge" },
    { key: "totalAmount", label: "Total", type: "money", meta: { currencyKey: "currency" } },
    { key: "orderDate", label: "Order Date", type: "date" },
  ]}
/>;
```

## Props

| Prop        | Type                      | Default      | Description                               |
| ----------- | ------------------------- | ------------ | ----------------------------------------- |
| `data`      | `Record<string, unknown>` | **Required** | Data object containing field values       |
| `fields`    | `FieldConfig[]`           | **Required** | Array of field configurations or dividers |
| `columns`   | `2 \| 3 \| 4`             | `3`          | Number of columns in the grid             |
| `className` | `string`                  | -            | Additional CSS classes                    |
| `style`     | `CSSProperties`           | -            | Inline styles for the card container      |

## Field Types

### text (default)

Plain text display with optional truncation and copy button.

```tsx
{
  key: "description",
  label: "Description",
  type: "text", // or omit - it's the default
  meta: {
    copyable: true,
    truncateLines: 3, // Show "..." after 3 lines with tooltip
  },
}
```

### badge

Displays value as a Badge component with variant mapping. Accepts a single value or an array of values.

```tsx
{
  key: "status",
  label: "Status",
  type: "badge",
  meta: {
    sentenceCaseBadges: false, // Optional: render the original value instead
    badgeVariantMap: {
      draft: "neutral",
      pending: "subtle-warning",
      approved: "subtle-success",
      shipped: "success",
      cancelled: "subtle-error",
    },
  },
}
```

Badge values are rendered in sentence case by default. Set `meta.sentenceCaseBadges` to `false` when you need to display the original value from your data.

#### Array badges with overflow

When the field value is an array, each item is rendered as a separate badge. Use `maxVisible` to cap the number shown — extra items appear in a hover popover:

```tsx
<DescriptionCard
  data={{ tags: ["urgent", "fragile", "international"] }}
  fields={[
    {
      key: "tags",
      label: "Tags",
      type: "badge",
      meta: {
        badgeVariantMap: { urgent: "error", fragile: "warning", international: "outline-info" },
        maxVisible: 2,
      },
    },
  ]}
/>
```

### money

Formats currency values with proper locale formatting.

```tsx
{
  key: "amount",
  label: "Amount",
  type: "money",
  meta: {
    currencyKey: "currency", // Path to currency code in data
  },
}

// Data: { amount: 1234.56, currency: "USD" }
// Renders: $1,234.56
```

### date

Formats date/time values with multiple format options.

```tsx
{
  key: "createdAt",
  label: "Created",
  type: "date",
  meta: {
    dateFormat: "medium", // "short" | "medium" | "long" | "relative"
  },
}
```

Format examples:

* `short`: 3/6/2026
* `medium`: Mar 6, 2026
* `long`: March 6, 2026 at 2:30 PM
* `relative`: 2 hours ago / In 3 days

Relative dates support both past and future values and are automatically localized based on the AppShell locale (English and Japanese are built in).

### link

Renders a clickable link.

```tsx
{
  key: "customerName",
  label: "Customer",
  type: "link",
  meta: {
    hrefKey: "customerUrl", // Path to URL in data
    external: true, // Opens in new tab
  },
}
```

Internal links (when `external` is not set or `false`) use react-router `<Link>` for client-side navigation. External links (when `external: true`) open in a new tab using a standard `<a>` tag.

### address

Formats multi-line address display.

```tsx
{
  key: "shippingAddress",
  label: "Shipping Address",
  type: "address",
}

// Data: {
//   shippingAddress: {
//     street: "123 Main St",
//     city: "San Francisco",
//     state: "CA",
//     zip: "94105",
//   }
// }
```

### reference

Links to related documents with auto-generated URLs using react-router `<Link>` for client-side navigation.

```tsx
{
  key: "invoiceNumber",
  label: "Invoice",
  type: "reference",
  meta: {
    referenceIdKey: "invoiceId",
    referenceUrlPattern: "/invoices/{id}",
  },
}
```

## Custom Rendering

When no built-in `type` fits, pass `render` to draw the field yourself. It receives the whole `data` object — reach into it for whatever the field needs:

```tsx
<DescriptionCard
  data={orderData}
  title="Order"
  fields={[
    { key: "orderNumber", label: "Order Number" }, // default text
    { key: "status", label: "Status", type: "badge" }, // preset
    {
      key: "deliveryBreakdown",
      label: "Delivery",
      render: (data) => <PieChart data={data.deliveryBreakdown} />, // fully custom
    },
  ]}
/>
```

Because `render` takes the whole object, a field can be derived from several keys at once — destructure the ones you want:

```tsx
{
  key: "total",
  label: "Balance Due",
  render: ({ total, amountPaid, currency }) => (
    <Money amount={total - amountPaid} currency={currency} />
  ),
}
```

This is the same convention as [DataTable's](data-table) column `render`, which also receives the whole row, so the two data-display components behave alike. It also means everything you touch keeps its declared type — nothing is widened to `unknown`.

### Rules

* **`render` always wins over `type`.** Both may be set, but the built-in renderer is skipped entirely.
* **`meta` is not applied.** A custom renderer owns its own presentation — the copy button, truncation, badge maps, and the `–` empty placeholder are all built-in behaviour that `render` replaces. Render them yourself if you want them.
* **`key` is still required.** It identifies the field and is what `emptyBehavior` tests. It does *not* pre-resolve a value for `render` — dot-notation paths are only used by the built-in `type` renderers.
* **`render` still runs when the value at `key` is empty,** so you decide how to display that. `emptyBehavior: "hide"` is checked first and removes the field before `render` is called.

## Dividers

Use dividers to visually separate field groups:

```tsx
<DescriptionCard
  data={data}
  fields={[
    { key: "orderNumber", label: "Order Number" },
    { key: "customer", label: "Customer" },
    { type: "divider" }, // Creates a horizontal line
    { key: "status", label: "Status", type: "badge" },
    { key: "totalAmount", label: "Total", type: "money" },
  ]}
/>
```

## Empty Value Behavior

Control what displays when a field value is empty:

```tsx
{
  key: "notes",
  label: "Notes",
  emptyBehavior: "dash", // Shows "-" when empty (default)
}

{
  key: "optionalField",
  label: "Optional",
  emptyBehavior: "hide", // Hides the entire field when empty
}
```

## Nested Data Access

Use dot notation to access nested properties:

```tsx
const data = {
  customer: {
    name: "Acme Corp",
    contact: {
      email: "contact@acme.com",
    },
  },
};

<DescriptionCard
  data={data}
  fields={[
    { key: "customer.name", label: "Customer Name" },
    { key: "customer.contact.email", label: "Email" },
  ]}
/>;
```

## Column Layouts

Choose between 2, 3, or 4 column layouts:

```tsx
// 2 columns (better for mobile)
<DescriptionCard columns={2} data={data} fields={fields} />

// 3 columns (default, balanced)
<DescriptionCard columns={3} data={data} fields={fields} />

// 4 columns (more compact)
<DescriptionCard columns={4} data={data} fields={fields} />
```

The component is fully responsive:

* **Mobile (< 400px)**: 1 column
* **Tablet (400-600px)**: 2 columns
* **Desktop (600-800px)**: 3 columns
* **Large (> 800px)**: 4 columns (if `columns={4}`)

## Complete Example

```tsx
import { DescriptionCard } from "@tailor-platform/app-shell";

const orderData = {
  // Order info
  orderNumber: "ORD-12345",
  orderDate: "2026-03-01T10:00:00Z",
  status: "shipped",

  // Customer
  customer: {
    name: "Acme Corporation",
    id: "CUST-001",
    email: "orders@acme.com",
  },

  // Financial
  subtotal: 14000.0,
  tax: 1750.0,
  total: 15750.0,
  currency: "USD",

  // Shipping
  shippingAddress: {
    street: "123 Business Ave",
    city: "San Francisco",
    state: "CA",
    zip: "94105",
  },
  trackingNumber: "1Z999AA10123456784",

  // Notes
  notes: "Rush delivery requested",
};

function OrderDetails() {
  return (
    <DescriptionCard
      data={orderData}
      columns={3}
      fields={[
        // Order Information
        {
          key: "orderNumber",
          label: "Order Number",
          meta: { copyable: true },
        },
        {
          key: "orderDate",
          label: "Order Date",
          type: "date",
          meta: { dateFormat: "medium" },
        },
        {
          key: "status",
          label: "Status",
          type: "badge",
          meta: {
            badgeVariantMap: {
              draft: "neutral",
              pending: "subtle-warning",
              shipped: "subtle-success",
              delivered: "success",
              cancelled: "subtle-error",
            },
          },
        },

        { type: "divider" },

        // Customer Information
        {
          key: "customer.name",
          label: "Customer",
          type: "reference",
          meta: {
            referenceIdKey: "customer.id",
            referenceUrlPattern: "/customers/{id}",
          },
        },
        {
          key: "customer.email",
          label: "Email",
          type: "link",
          meta: { hrefKey: "customer.email" },
        },

        { type: "divider" },

        // Financial
        {
          key: "subtotal",
          label: "Subtotal",
          type: "money",
          meta: { currencyKey: "currency" },
        },
        {
          key: "tax",
          label: "Tax",
          type: "money",
          meta: { currencyKey: "currency" },
        },
        {
          key: "total",
          label: "Total",
          type: "money",
          meta: { currencyKey: "currency" },
        },

        { type: "divider" },

        // Shipping
        {
          key: "shippingAddress",
          label: "Shipping Address",
          type: "address",
        },
        {
          key: "trackingNumber",
          label: "Tracking",
          meta: { copyable: true },
        },

        { type: "divider" },

        // Notes
        {
          key: "notes",
          label: "Notes",
          meta: { truncateLines: 2 },
          emptyBehavior: "hide",
        },
      ]}
    />
  );
}
```

## Styling

The component uses container queries for responsive layouts:

```tsx
// Custom styling
<DescriptionCard
  className="astw:bg-white astw:p-6 astw:rounded-lg astw:shadow"
  data={data}
  fields={fields}
/>
```

## Accessibility

* Proper semantic HTML structure
* Labels associated with values
* Keyboard accessible copy buttons
* Tooltips for truncated content
* Screen reader friendly

## Best Practices

### Do:

* ✅ Group related fields with dividers
* ✅ Use appropriate field types for data
* ✅ Enable `copyable` for IDs and codes
* ✅ Use `emptyBehavior: "hide"` for optional fields
* ✅ Provide `badgeVariantMap` for status fields

### Don't:

* ❌ Put too many fields (consider splitting into tabs)
* ❌ Use more than 4 columns (hard to read)
* ❌ Mix unrelated data without dividers
* ❌ Forget to handle nested data properly

## TypeScript

`DescriptionCard` is generic over the shape of `data`, which is normally inferred:

```typescript
import { DescriptionCard, type DescriptionCardProps } from "@tailor-platform/app-shell";

// Define your data type
interface Order {
  orderNumber: string;
  customer: string;
  status: "draft" | "pending" | "shipped";
  total: number;
  currency: string;
}

declare const orderData: Order;

// `data` inside render is typed as Order - no annotation needed
<DescriptionCard
  data={orderData}
  title="Order"
  fields={[
    { key: "orderNumber", label: "Order" },
    { key: "status", label: "Status", type: "badge" },
    { key: "total", label: "Total", render: (data) => `${data.total} ${data.currency}` },
  ]}
/>;
```

To declare the fields array separately, parameterise `DescriptionCardProps` with your data type so `render` callbacks stay typed:

```typescript
const fields: DescriptionCardProps<Order>["fields"] = [
  { key: "orderNumber", label: "Order" },
  { key: "total", label: "Total", render: (data) => `${data.total} ${data.currency}` },
];

<DescriptionCard<Order> data={orderData} title="Order" fields={fields} />;
```

`render` receives `data` typed as your data type, so every key you reach for keeps its declared type. `key` remains a plain `string` accepting dot-notation paths, but it only feeds the built-in `type` renderers — it is not resolved and handed to `render`.

## Related Components

* [Badge](badge) - Used for status fields
* [Layout](layout) - Page layout container

## Related Concepts

* [Styling and Theming](../concepts/styling-theming) - Customize appearance

---

---
url: https://docs.tailor.tech/app-shell/components/dialog.md
description: Modal dialog with a compound component API
---

# Dialog

The `Dialog` component provides a modal dialog with a compound component API. It is backed by Base UI's Dialog primitive.

[Live preview in the UI Catalogue →](https://ui.tailor.tech/components/dialog)

## Import

```tsx
import { Dialog } from "@tailor-platform/app-shell";
```

## Basic Usage

```tsx
<Dialog.Root>
  <Dialog.Trigger render={<Button />}>Open</Dialog.Trigger>
  <Dialog.Content>
    <Dialog.Header>
      <Dialog.Title>Confirm Action</Dialog.Title>
      <Dialog.Description>Are you sure you want to proceed?</Dialog.Description>
    </Dialog.Header>
    <Dialog.Footer>
      <Dialog.Close render={<Button variant="outline" />}>Cancel</Dialog.Close>
      <Button>Confirm</Button>
    </Dialog.Footer>
  </Dialog.Content>
</Dialog.Root>
```

## Sub-components

| Sub-component        | Description                                                             |
| -------------------- | ----------------------------------------------------------------------- |
| `Dialog.Root`        | Manages open/close state                                                |
| `Dialog.Trigger`     | Element that opens the dialog when clicked                              |
| `Dialog.Content`     | The main dialog panel (includes overlay and close button automatically) |
| `Dialog.Header`      | Layout wrapper for title and description                                |
| `Dialog.Footer`      | Layout wrapper for action buttons                                       |
| `Dialog.Title`       | Dialog title (announced by screen readers)                              |
| `Dialog.Description` | Additional context below the title                                      |
| `Dialog.Close`       | Button that closes the dialog                                           |

## Props

### Dialog.Root Props

| Prop           | Type                      | Default | Description                       |
| -------------- | ------------------------- | ------- | --------------------------------- |
| `open`         | `boolean`                 | -       | Controlled open state             |
| `defaultOpen`  | `boolean`                 | `false` | Initial open state (uncontrolled) |
| `onOpenChange` | `(open: boolean) => void` | -       | Callback when open state changes  |
| `modal`        | `boolean`                 | `true`  | Whether the dialog is modal       |
| `children`     | `React.ReactNode`         | -       | Dialog sub-components             |

### Dialog.Content Props

Accepts `className` and all standard HTML `<div>` props.

### Dialog.Trigger / Dialog.Close Props

Accept a `render` prop for custom element rendering (Base UI render pattern), plus standard button props.

## Controlled Usage

```tsx
const [open, setOpen] = useState(false);

<Dialog.Root open={open} onOpenChange={setOpen}>
  <Dialog.Trigger render={<Button variant="outline" />}>Open Dialog</Dialog.Trigger>
  <Dialog.Content>
    <Dialog.Header>
      <Dialog.Title>Settings</Dialog.Title>
    </Dialog.Header>
    <Dialog.Footer>
      <Button onClick={() => setOpen(false)}>Done</Button>
    </Dialog.Footer>
  </Dialog.Content>
</Dialog.Root>;
```

## Examples

### Delete Confirmation

```tsx
function DeleteConfirmation({ onDelete }: { onDelete: () => void }) {
  return (
    <Dialog.Root>
      <Dialog.Trigger render={<Button variant="destructive" />}>Delete</Dialog.Trigger>
      <Dialog.Content>
        <Dialog.Header>
          <Dialog.Title>Delete Order</Dialog.Title>
          <Dialog.Description>
            This action cannot be undone. The order will be permanently deleted.
          </Dialog.Description>
        </Dialog.Header>
        <Dialog.Footer>
          <Dialog.Close render={<Button variant="outline" />}>Cancel</Dialog.Close>
          <Button variant="destructive" onClick={onDelete}>
            Delete
          </Button>
        </Dialog.Footer>
      </Dialog.Content>
    </Dialog.Root>
  );
}
```

### Form Dialog

```tsx
function EditDialog({ item }: { item: Item }) {
  const [name, setName] = useState(item.name);

  return (
    <Dialog.Root>
      <Dialog.Trigger render={<Button variant="outline" />}>Edit</Dialog.Trigger>
      <Dialog.Content>
        <Dialog.Header>
          <Dialog.Title>Edit Item</Dialog.Title>
        </Dialog.Header>
        <Input value={name} onChange={(e) => setName(e.target.value)} />
        <Dialog.Footer>
          <Dialog.Close render={<Button variant="outline" />}>Cancel</Dialog.Close>
          <Button onClick={() => handleSave(name)}>Save</Button>
        </Dialog.Footer>
      </Dialog.Content>
    </Dialog.Root>
  );
}
```

## Accessibility

* Dialog title is announced by screen readers via `Dialog.Title`
* Focus is trapped inside the dialog while open
* Pressing `Escape` closes the dialog
* The close button is always present inside `Dialog.Content`

## Related Components

* [Sheet](sheet) - Slide-in panel alternative for non-modal workflows
* [Button](button) - Use as trigger and action buttons

---

---
url: https://docs.tailor.tech/app-shell/components/document-progress-card.md
description: >-
  Generic card visualising a document's lifecycle state — optional percentage,
  stacked progress bar, and status legend
---

# DocumentProgressCard

`DocumentProgressCard` is a generic, presentational card for communicating the lifecycle/fulfilment state of a document in a record detail right rail. It shows an optional completion percentage, a stacked progress bar, and a legend — driven by an arbitrary set of status `segments`.

It is view-only and domain-agnostic: pass the segments and an explicit `percent`. Any domain-specific math — deriving the percentage, or decomposing overlapping buckets into bar segments — lives in the consumer. See [Example: purchase-order fulfilment](#example-purchase-order-fulfilment) for a complete, copyable pattern.

## Import

```tsx
import { DocumentProgressCard } from "@tailor-platform/app-shell";
```

## Basic Usage

```tsx
<DocumentProgressCard
  title="Shipment status"
  percent={60}
  segments={[
    { label: "Shipped", value: 30, color: "green" },
    { label: "Returned", value: 3, color: "red" },
    { label: "Pending", value: 17, color: "neutral" },
  ]}
/>
```

## Props

| Prop        | Type                        | Default       | Description                                                                                               |
| ----------- | --------------------------- | ------------- | --------------------------------------------------------------------------------------------------------- |
| `segments`  | `DocumentProgressSegment[]` | **Required**  | Status segments rendered as a stacked bar (and, by default, the legend).                                  |
| `title`     | `React.ReactNode`           | -             | Optional card title shown top-left.                                                                       |
| `percent`   | `number`                    | -             | Optional headline percentage (0–100), shown top-right. Explicit — the generic card derives no progress.   |
| `legend`    | `DocumentProgressSegment[]` | `segments`    | Optional legend rows; override only when the legend should differ from the bar (see [Legend](#legend)).   |
| `total`     | `number`                    | sum of values | Denominator used to size the bar. A value larger than the segment sum leaves an unfilled track remainder. |
| `className` | `string`                    | -             | Additional CSS classes for the card root.                                                                 |

### `DocumentProgressSegment`

| Field   | Type                    | Description                                            |
| ------- | ----------------------- | ------------------------------------------------------ |
| `label` | `string`                | Legend label.                                          |
| `value` | `number`                | Amount — shown in the legend and used to size the bar. |
| `color` | `DocumentProgressColor` | Bar / marker color (required).                         |

`DocumentProgressColor` is one of: `"indigo"`, `"pink"`, `"green"`, `"amber"`, `"red"`, `"blue"`, `"neutral"`.

## Progress Bar

The bar tiles `segments` left-to-right, each sized as `value / (total ?? sum of values)`. When `total` exceeds the segment sum, the shortfall renders as an empty `bg-muted` track — useful for a "remaining" portion you don't want as a colored segment. A `"neutral"` segment reads as a muted/track-like fill.

## Legend

By default the legend mirrors `segments`. Pass `legend` to render different rows — for example when buckets overlap and the bar shows a decomposition while the legend shows the raw figures:

```tsx
<DocumentProgressCard
  percent={30}
  total={40}
  segments={[
    { label: "Net received", value: 10, color: "indigo" },
    { label: "Returned", value: 2, color: "pink" },
  ]}
  legend={[
    { label: "Received items", value: 12, color: "indigo" },
    { label: "Returned items", value: 2, color: "pink" },
    { label: "Yet to receive", value: 28, color: "neutral" },
  ]}
/>
```

## Example: purchase-order fulfilment

A common use is communicating a purchase order's receiving state — **received**, **returned**, and **yet to receive**. `DocumentProgressCard` stays generic, so derive the percentage and the bar breakdown in your component and pass them in. This recipe reproduces the recommended look (labels, indigo/pink/neutral colors, and a bar that decomposes received into "kept" + "returned" against the ordered total):

```tsx
function PurchaseOrderFulfilment({
  received,
  returned,
  yetToReceive,
  // Whether returned items still count as fulfilled. Set false to subtract them.
  returnedCountsAsComplete = true,
}: {
  received: number;
  returned: number;
  yetToReceive: number;
  returnedCountsAsComplete?: boolean;
}) {
  // Returned is a subset of received; clamp so the breakdown can't exceed it.
  const effectiveReturned = Math.min(Math.max(returned, 0), Math.max(received, 0));
  const total = Math.max(received, 0) + Math.max(yetToReceive, 0); // the ordered quantity
  const complete = returnedCountsAsComplete ? received : received - effectiveReturned;
  const percent = total > 0 ? Math.round((complete / total) * 100) : 0;

  return (
    <DocumentProgressCard
      title="Fulfilment rate"
      percent={percent}
      total={total} // ordered quantity — the shortfall renders as the "yet to receive" track
      // Bar: net received (kept) + returned. Yet-to-receive is the unfilled remainder.
      segments={[
        { label: "Received items", value: received - effectiveReturned, color: "indigo" },
        { label: "Returned items", value: effectiveReturned, color: "pink" },
      ]}
      // Legend: the three buckets as-is, so "Received items" shows the full amount.
      legend={[
        { label: "Received items", value: received, color: "indigo" },
        { label: "Returned items", value: returned, color: "pink" },
        { label: "Yet to receive", value: yetToReceive, color: "neutral" },
      ]}
    />
  );
}

// <PurchaseOrderFulfilment received={12} returned={2} yetToReceive={28} /> → 30%
```

Notes for adapting it:

* **Colors:** `indigo` (received), `pink` (returned), `neutral` (yet to receive) is the recommended set; swap any of the seven palette colors to fit your domain.
* **Bar vs. legend:** the bar uses `received − returned` so the two colored segments don't double-count the returned items, while the `legend` override keeps "Received items" showing the full received figure.
* **`total`:** pass the ordered quantity so the unfilled portion of the bar represents "yet to receive". Omit it (or use the segment sum) if you want a fully-tiled bar instead.
* **Percentage policy:** flip `returnedCountsAsComplete` to decide whether returned items count toward completion.

## Input handling

Segment values are expected to be non-negative numbers. Non-finite or negative values are coerced to `0`, and `percent` is rounded and clamped to `[0, 100]`.

## Related

* [MetricCard](metric-card) — Compact KPI summary card.
* [Card](card) — The underlying card primitive.

---

---
url: https://docs.tailor.tech/app-shell/components/form.md
description: >-
  Components for building validated forms with automatic accessibility wiring,
  validation state management, and optional React Hook Form integration
---

# Form, Field, and Fieldset

`Form`, `Field`, and `Fieldset` are compound components for building accessible, validated forms. They handle label association, `aria-describedby`, validation state, and external error routing automatically.

[Live preview in the UI Catalogue →](https://ui.tailor.tech/components/form)

## Import

```tsx
import { Form, Field, Fieldset } from "@tailor-platform/app-shell";
```

## Basic Usage

```tsx
<Form onFormSubmit={(values) => save(values)}>
  <Field.Root name="email">
    <Field.Label>Email</Field.Label>
    <Field.Control type="email" required />
    <Field.Description>We'll never share your email.</Field.Description>
    <Field.Error match="valueMissing">Email is required.</Field.Error>
    <Field.Error match="typeMismatch">Enter a valid email address.</Field.Error>
  </Field.Root>
  <button type="submit">Save</button>
</Form>
```

***

## Form

A form element with consolidated error handling and validation. Wraps every child `Field.Root` in a shared validation context.

### Form Props

| Prop             | Type                                                            | Default      | Description                                                                                                                         |
| ---------------- | --------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| `children`       | `React.ReactNode`                                               | **Required** | Form contents                                                                                                                       |
| `onFormSubmit`   | `(values: FormValues, details: FormSubmitEventDetails) => void` | -            | Called after successful validation with parsed form values. Prefer this for simple forms. Use a type argument for type-safe values. |
| `onSubmit`       | `React.FormEventHandler`                                        | -            | Low-level native submit handler. Use when integrating with React Hook Form's `handleSubmit`.                                        |
| `errors`         | `Record<string, string>`                                        | -            | External errors keyed by field `name` (e.g. from an API response). Automatically routed to matching `Field.Error` components.       |
| `validationMode` | `"onSubmit" \| "onBlur" \| "onChange"`                          | `"onSubmit"` | Controls when field validation fires.                                                                                               |
| `noValidate`     | `boolean`                                                       | -            | Disables native browser validation UI (recommended — AppShell renders its own).                                                     |
| `actionsRef`     | `React.Ref<{ validate: () => void }>`                           | -            | Ref to imperatively trigger validation from outside the submit flow.                                                                |
| `id`             | `string`                                                        | -            | Applied to the `<form>` element. Lets a submit button outside the form target it via the native `form` attribute.                   |
| `className`      | `string`                                                        | -            | Additional CSS classes for the `<form>` element.                                                                                    |

### External Errors

Feed API validation errors back into the form via the `errors` prop. Errors are keyed by field `name` and cleared automatically when the user edits the corresponding field.

```tsx
const [errors, setErrors] = React.useState({});

async function handleSubmit(values) {
  const res = await api.save(values);
  if (res.errors) setErrors(res.errors);
}

<Form errors={errors} onFormSubmit={handleSubmit}>
  <Field.Root name="url">
    <Field.Label>Homepage</Field.Label>
    <Field.Control type="url" required />
    <Field.Error />
  </Field.Root>
  <button type="submit">Submit</button>
</Form>;
```

### Programmatic Validation

Use `actionsRef` to imperatively trigger validation (e.g. in a multi-step wizard).

```tsx
const actions = React.useRef(null);

<Form actionsRef={actions}>
  <Field.Root name="name">
    <Field.Label>Name</Field.Label>
    <Field.Control required />
    <Field.Error>Name is required.</Field.Error>
  </Field.Root>
</Form>;

<button onClick={() => actions.current?.validate()}>Check</button>;
```

***

## Field

A compound component that groups all parts of a form field and manages its validation state.

`Field.Root` creates a context boundary. All child sub-components and any Base UI-backed AppShell component (e.g. `Select`, `Combobox`, `Autocomplete`) placed inside `Field.Root` automatically connect to this context — inheriting label association (`htmlFor`), `aria-describedby`, `disabled` state, and validation state.

### Sub-components

| Sub-component       | Description                                                                                   |
| ------------------- | --------------------------------------------------------------------------------------------- |
| `Field.Root`        | Context boundary for a single field. Manages validation state.                                |
| `Field.Label`       | Accessible label; `htmlFor` is resolved automatically via context.                            |
| `Field.Control`     | Styled `<input>`. Can be omitted when using a Base UI-backed AppShell component as the input. |
| `Field.Description` | Supplementary help text; automatically linked via `aria-describedby`.                         |
| `Field.Error`       | Validation error message. Use `match` to target specific validity states.                     |
| `Field.Validity`    | Render-prop access to the field's `ValidityState` for fully custom validation UI.             |

### Field.Root Props

| Prop                     | Type                                     | Default | Description                                                                                         |
| ------------------------ | ---------------------------------------- | ------- | --------------------------------------------------------------------------------------------------- |
| `name`                   | `string`                                 | -       | Field name; used for form value extraction and error routing.                                       |
| `children`               | `React.ReactNode`                        | -       | Field sub-components and input controls.                                                            |
| `disabled`               | `boolean`                                | -       | Disables all controls within the field.                                                             |
| `isTouched`              | `boolean`                                | -       | Whether the field has been blurred. Maps to React Hook Form's `fieldState.isTouched`.               |
| `isDirty`                | `boolean`                                | -       | Whether the field value differs from its default. Maps to React Hook Form's `fieldState.isDirty`.   |
| `invalid`                | `boolean`                                | -       | Marks the field as invalid (shows error styling).                                                   |
| `error`                  | `{ message?: string }`                   | -       | Error object from React Hook Form's `fieldState.error`. Sets `invalid` automatically when provided. |
| `validate`               | `(value: string) => string \| undefined` | -       | Custom validation function; return an error message string to mark the field invalid.               |
| `validationMode`         | `"onSubmit" \| "onBlur" \| "onChange"`   | -       | Overrides the parent Form's `validationMode` for this field.                                        |
| `validationDebounceTime` | `number`                                 | -       | Debounce delay (ms) for `"onChange"` validation mode.                                               |
| `className`              | `string`                                 | -       | Additional CSS classes for the field wrapper.                                                       |

### Field.Error Props

| Prop       | Type                                                             | Default | Description                                                                                                |
| ---------- | ---------------------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------- |
| `match`    | `keyof ValidityState \| boolean \| ((value: string) => boolean)` | -       | Validity state key to match (e.g. `"valueMissing"`, `"typeMismatch"`). Omit for a catch-all error message. |
| `children` | `React.ReactNode`                                                | -       | Error message content. If omitted, the browser's native validation message is shown.                       |

### Using Another AppShell Component as the Control

`Field.Control` can be omitted when using a Base UI-backed AppShell component (e.g. `Select`, `Combobox`). The component registers itself with the `Field` context automatically, inheriting label association and validation state.

```tsx
const [country, setCountry] = React.useState<string | null>(null);

<Field.Root name="country">
  <Field.Label>Country</Field.Label>
  <Select
    items={["Japan", "United States"]}
    value={country}
    onValueChange={setCountry}
    placeholder="Select a country"
  />
  <Field.Error>Please select a country.</Field.Error>
</Field.Root>;
```

### How values reach `onFormSubmit`

`onFormSubmit` does **not** read `FormData`. It collects values from the `Field.Root`s registered
inside the `Form`, keyed by each field's `name`. Every AppShell control works this way once wrapped
in a `Field.Root` — `Select`, `Combobox`, and `Autocomplete` included. They need no `name` of their
own and no React state.

Non-string items are serialised into the submitted value:

| Item shape                             | Value in `onFormSubmit`              |
| -------------------------------------- | ------------------------------------ |
| `string`                               | the string                           |
| `{ value, label }`                     | `value`, automatically               |
| any other object                       | **JSON string** — usually not wanted |
| any other object + `itemToStringValue` | whatever that function returns       |

Multi-select submits an array. For arbitrary objects, pass `itemToStringValue` to choose what gets
submitted — it is distinct from `mapItem`, which controls what the user sees:

```tsx
<Field.Root name="warehouse">
  <Field.Label>Warehouse</Field.Label>
  <Combobox
    items={warehouses}
    mapItem={(w) => ({ label: w.name, key: String(w.id) })}
    itemToStringValue={(w) => String(w.id)}
  />
</Field.Root>
```

### Native form submission

Separately from `onFormSubmit`, controls can participate in **native** submission — a plain
`<form>`, `new FormData(form)`, or a server action. That path reads the DOM, so each control needs
its own `name`. `Select`, `Combobox`, and `Autocomplete` accept `name` (plus `form`, `required`,
`inputRef`) from 1.13.0; before that they contributed nothing to a native payload.

### Submitting from outside the form

Give the `Form` an `id` and point a detached submit button at it with the native `form` attribute —
this is how a page-header Save reaches a form in the page body (1.13.0+).

```tsx
<Layout.Header
  title="Create product"
  actions={[
    <Button key="save" type="submit" form="product-form">
      Save
    </Button>,
  ]}
/>
<Form id="product-form" onFormSubmit={(values) => save(values)}>
  {/* … */}
</Form>
```

### Custom Validation UI with Field.Validity

`Field.Validity` exposes the field's `ValidityState` via a render callback, enabling fully custom validation UI.

```tsx
<Field.Root name="password">
  <Field.Label>Password</Field.Label>
  <Field.Control type="password" required minLength={8} />
  <Field.Validity>
    {(state) => (
      <ul>
        <li>{state.validity.valueMissing ? "❌" : "✅"} Required</li>
        <li>{state.validity.tooShort ? "❌" : "✅"} At least 8 characters</li>
      </ul>
    )}
  </Field.Validity>
</Field.Root>
```

***

## Fieldset

A compound component (`Fieldset.Root`, `Fieldset.Legend`) for grouping related fields with a shared legend for accessible form sectioning.

### Sub-components

| Sub-component     | Description                                                    |
| ----------------- | -------------------------------------------------------------- |
| `Fieldset.Root`   | Renders a `<fieldset>`. Propagates `disabled` to all children. |
| `Fieldset.Legend` | Accessible `<legend>` for the group.                           |

### Fieldset.Root Props

| Prop        | Type              | Default | Description                                |
| ----------- | ----------------- | ------- | ------------------------------------------ |
| `children`  | `React.ReactNode` | -       | Field components to group.                 |
| `disabled`  | `boolean`         | -       | Disables all controls within the fieldset. |
| `className` | `string`          | -       | Additional CSS classes.                    |

### Example

```tsx
<Fieldset.Root>
  <Fieldset.Legend>Billing details</Fieldset.Legend>
  <Field.Root name="company">
    <Field.Label>Company</Field.Label>
    <Field.Control />
  </Field.Root>
  <Field.Root name="taxId">
    <Field.Label>Tax ID</Field.Label>
    <Field.Control />
  </Field.Root>
</Fieldset.Root>
```

***

## React Hook Form Integration

React Hook Form is **optional and not an AppShell dependency** — install it in your own app. `Form` +
`Field` is the default stack and covers most forms via `onFormSubmit`. Reach for RHF only when a form
genuinely needs cross-field validation, field arrays, or a schema resolver (Zod). The two compose
rather than compete: `Field` handles accessibility wiring and visual state, RHF handles values and
the validation lifecycle.

`Field.Root` accepts `isTouched`, `isDirty`, `invalid`, and `error` props that align with React Hook Form's `fieldState` shape, so you can spread `fieldState` directly. Use `Form`'s `onSubmit` prop to connect RHF's `handleSubmit`.

```tsx
import { useForm, Controller } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";
import { z } from "zod";

const schema = z.object({ email: z.string().email() });

function MyForm() {
  const { control, handleSubmit } = useForm({
    resolver: zodResolver(schema),
  });

  return (
    <Form onSubmit={handleSubmit((data) => save(data))}>
      <Controller
        name="email"
        control={control}
        render={({ field, fieldState }) => (
          <Field.Root {...fieldState}>
            <Field.Label>Email</Field.Label>
            <Field.Control {...field} type="email" />
            <Field.Error>{fieldState.error?.message}</Field.Error>
          </Field.Root>
        )}
      />
      <button type="submit">Save</button>
    </Form>
  );
}
```

The `Field` context handles only accessibility wiring (`htmlFor`, `aria-describedby`) and visual state (`data-invalid`, `data-dirty`, `data-touched`) — it does not interfere with RHF's value management or validation lifecycle.

***

## Related

* [Input](input) — Standalone styled input, useful outside of forms.
* [Textarea](textarea) — Multi-line text control that integrates automatically with `Field`.
* [Checkbox](checkbox) — Boolean control that integrates automatically with `Field`.
* [Select](select) — Dropdown that integrates automatically with `Field`.
* [Combobox](combobox) — Searchable combobox that integrates automatically with `Field`.
* [Autocomplete](autocomplete) — Free-text input with suggestions that integrates automatically with `Field`.

---

---
url: https://docs.tailor.tech/app-shell/components/grid.md
description: >-
  Generic CSS-Grid layout primitive for equal or custom-width columns with
  responsive reflow, auto-fit, and spanning
---

# Grid

`Grid` is a generic, presentational layout primitive built on CSS Grid. It arranges arbitrary children into equal or custom-width columns, with gap control, responsive reflow, auto-fit sizing, and optional cell spanning via `Grid.Item`. It makes no assumptions about your data — children simply flow into the tracks you define.

> **Grid vs. Layout:** Use [`Layout`](layout) for top-level **page scaffolding** (header + fixed-width sidebars + main content). Use `Grid` for **content grids** within a page — KPI cards, galleries, field groups, dashboards. They are complementary; reach for `Grid` whenever you just need "arrange these N things into columns."

## Import

```tsx
import { Grid } from "@tailor-platform/app-shell";
```

## Basic Usage

```tsx
<Grid columns={3} gap={4}>
  <Card.Root>One</Card.Root>
  <Card.Root>Two</Card.Root>
  <Card.Root>Three</Card.Root>
</Grid>
```

Plain children occupy a single cell. Wrap a child in `Grid.Item` only when it needs to span multiple tracks or be placed explicitly.

## Sub-components

| Sub-component | Description                                                            |
| ------------- | ---------------------------------------------------------------------- |
| `Grid`        | The grid container — defines columns, rows, gap, and alignment         |
| `Grid.Item`   | An optional cell that spans multiple columns/rows or is placed by line |

## Props

### Grid Props

| Prop            | Type                                                                | Default    | Description                                                                                              |
| --------------- | ------------------------------------------------------------------- | ---------- | -------------------------------------------------------------------------------------------------------- |
| `columns`       | `number \| string \| Responsive<number \| string>`                  | -          | A number creates that many equal columns; a string is a verbatim `grid-template-columns` value           |
| `rows`          | `number \| string \| Responsive<number \| string>`                  | -          | Same shape as `columns`, for `grid-template-rows`                                                        |
| `gap`           | `number \| Responsive<number>`                                      | `3` (12px) | Gap between rows and columns, in spacing-scale units (`4` → `1rem`)                                      |
| `gapX`          | `number \| Responsive<number>`                                      | -          | Horizontal (column) gap override                                                                         |
| `gapY`          | `number \| Responsive<number>`                                      | -          | Vertical (row) gap override                                                                              |
| `minChildWidth` | `number \| string`                                                  | -          | Auto-fit: each item is at least this wide and as many as fit are placed per row. **Overrides `columns`** |
| `flow`          | `"row" \| "column" \| "dense" \| "row-dense" \| "column-dense"`     | `"row"`    | `grid-auto-flow` — placement direction and dense packing                                                 |
| `align`         | `"start" \| "center" \| "end" \| "stretch" \| "baseline"`           | -          | `align-items` — block-axis alignment of items within their tracks                                        |
| `justify`       | `"start" \| "center" \| "end" \| "between" \| "around" \| "evenly"` | -          | `justify-content` — inline-axis distribution of tracks within the grid                                   |
| `className`     | `string`                                                            | -          | Additional CSS classes                                                                                   |
| `children`      | `React.ReactNode`                                                   | -          | Grid items (any elements, or `Grid.Item`)                                                                |

All standard HTML `<div>` props are also accepted.

### Grid.Item Props

| Prop        | Type                                               | Default | Description                                           |
| ----------- | -------------------------------------------------- | ------- | ----------------------------------------------------- |
| `colSpan`   | `number \| "full" \| Responsive<number \| "full">` | -       | Columns to span, or `"full"` for all columns          |
| `rowSpan`   | `number \| "full" \| Responsive<number \| "full">` | -       | Rows to span, or `"full"` for all rows                |
| `colStart`  | `number \| Responsive<number>`                     | -       | 1-based column line to start at (`grid-column-start`) |
| `colEnd`    | `number \| Responsive<number>`                     | -       | 1-based column line to end at (`grid-column-end`)     |
| `className` | `string`                                           | -       | Additional CSS classes                                |
| `children`  | `React.ReactNode`                                  | -       | Cell content                                          |

All standard HTML `<div>` props are also accepted.

## Responsive values

`columns`, `rows`, `gap`, `gapX`, `gapY`, and every `Grid.Item` prop accept either a single value (applied at all breakpoints) or a breakpoint object. Breakpoints align with Tailwind: `initial` (base), `sm`, `md`, `lg`, `xl`, `2xl`.

```tsx
// 1 column on mobile, 2 from md, 4 from xl
<Grid columns={{ initial: 1, md: 2, xl: 4 }} gap={4}>
  {/* … */}
</Grid>
```

## Sizing columns

There are three ways to size columns; pick whichever fits.

```tsx
// 1. Equal columns
<Grid columns={4} gap={4}>{/* … */}</Grid>

// 2. Custom track widths (verbatim grid-template-columns)
<Grid columns="280px 1fr" gap={6}>{/* … */}</Grid>

// 3. Auto-fit — as many ≥240px columns as fit, no breakpoints needed
<Grid minChildWidth={240} gap={4}>{/* … */}</Grid>
```

`minChildWidth` accepts a number (pixels) or a string (e.g. `"16rem"`) and takes precedence over `columns` when set.

## Spanning with Grid.Item

```tsx
<Grid columns={4} gap={4}>
  <Grid.Item colSpan={2}>Wide card</Grid.Item>
  <Card.Root>Normal</Card.Root>
  <Grid.Item colSpan={{ initial: "full", md: 1 }} rowSpan={2}>
    Tall
  </Grid.Item>
  <Grid.Item colSpan="full">Full-width footer row</Grid.Item>
</Grid>
```

## Alignment

`align` aligns items within their row (visible when row height exceeds the item), `justify` distributes the columns when they are narrower than the container (e.g. fixed-width tracks), and `flow` controls placement order:

```tsx
<Grid columns="repeat(3, 96px)" gap={4} justify="between" align="center">
  {/* fixed-width columns spread across the container */}
</Grid>
```

> **Note:** `justify` only has a visible effect when the tracks do not fill the container. With fluid `columns={n}` (which uses `1fr` tracks) the columns always fill the width, so `justify` is a no-op — use fixed-width tracks to distribute columns. Likewise, `flow="…-dense"` only differs from the default when items span multiple cells and leave gaps to backfill.

## Examples

### Responsive KPI grid

```tsx
<Grid columns={{ initial: 1, sm: 2, lg: 4 }} gap={4}>
  {metrics.map((m) => (
    <MetricCard key={m.id} title={m.label} value={m.value} />
  ))}
</Grid>
```

### Auto-fitting card gallery

```tsx
<Grid minChildWidth={240} gap={6}>
  {products.map((p) => (
    <Card.Root key={p.sku}>
      <Card.Header title={p.name} description={p.sku} />
    </Card.Root>
  ))}
</Grid>
```

### Sidebar + content (custom widths)

```tsx
<Grid columns="280px 1fr" gap={6}>
  <Card.Root>{/* filters */}</Card.Root>
  <Card.Root>{/* results */}</Card.Root>
</Grid>
```

### Dashboard with a featured panel

```tsx
<Grid columns={{ initial: 1, md: 4 }} gap={4}>
  <Grid.Item colSpan={{ initial: "full", md: 2 }}>
    <Card.Root>Featured</Card.Root>
  </Grid.Item>
  <Card.Root>Stat</Card.Root>
  <Card.Root>Stat</Card.Root>
</Grid>
```

## Styling

`Grid` is a presentational primitive: it renders a single `<div data-slot="grid">` (and `<div data-slot="grid-item">` for cells) styled with Tailwind utilities prefixed `astw:`. Dynamic templates are applied via CSS custom properties, so arbitrary column counts and responsive values work without extra configuration. Pass `className` or `style` to extend or override.

## Related Components

* [Layout](layout) - Page-level scaffold (header + sidebars + main)
* [Card](card) - Common child of a grid cell
* [MetricCard](metric-card) - KPI cards for dashboard grids

---

---
url: https://docs.tailor.tech/app-shell/components/input.md
description: Styled text input with consistent theming
---

# Input

The `Input` component is a styled text input that provides consistent theming across your application.

[Live preview in the UI Catalogue →](https://ui.tailor.tech/components/input)

## Import

```tsx
import { Input } from "@tailor-platform/app-shell";
```

## Basic Usage

```tsx
<Input placeholder="Enter your name" />
```

## Props

Accepts all standard HTML `<input>` props.

| Prop          | Type      | Default  | Description            |
| ------------- | --------- | -------- | ---------------------- |
| `type`        | `string`  | `"text"` | HTML input type        |
| `placeholder` | `string`  | -        | Placeholder text       |
| `disabled`    | `boolean` | `false`  | Disables the input     |
| `className`   | `string`  | -        | Additional CSS classes |

## Examples

### Text Input

```tsx
<Input type="text" placeholder="Enter your name" />
```

### Email Input

```tsx
<Input type="email" placeholder="you@example.com" />
```

### Number Input

```tsx
<Input type="number" placeholder="0" min={0} max={100} />
```

### Disabled Input

```tsx
<Input value="Read-only value" disabled />
```

### With onChange Handler

```tsx
const [value, setValue] = useState("");

<Input value={value} onChange={(e) => setValue(e.target.value)} placeholder="Type something..." />;
```

## TypeScript

```typescript
import { type InputProps } from "@tailor-platform/app-shell";
```

## Related Components

* [Button](button) - Pair with inputs in forms
* [Textarea](textarea) - Multi-line counterpart, for free-text that outgrows one line
* [Checkbox](checkbox) - Boolean control with the same `Field` / React Hook Form integration

---

---
url: https://docs.tailor.tech/app-shell/components/layout.md
description: >-
  Responsive column layout component for organizing page content in 1, 2, or 3
  columns
---

# Layout

`Layout` is a responsive column layout component that helps you organize page content into 1, 2, or 3 columns with automatic responsive behavior. Perfect for detail pages, dashboards, and forms.

[Live preview in the UI Catalogue →](https://ui.tailor.tech/components/layout)

## Import

```tsx
import { Layout } from "@tailor-platform/app-shell";
```

## Basic Usage

The column count is auto-detected from the number of `Layout.Column` children:

```tsx
<Layout>
  <Layout.Column>
    <h2>Main Content</h2>
    <p>Your main content goes here...</p>
  </Layout.Column>
  <Layout.Column>
    <h2>Sidebar</h2>
    <p>Additional info or actions...</p>
  </Layout.Column>
</Layout>
```

## Props

### Layout Props

| Prop        | Type                | Default      | Description                                                                             |
| ----------- | ------------------- | ------------ | --------------------------------------------------------------------------------------- |
| `className` | `string`            | -            | Additional CSS classes for container                                                    |
| `style`     | `CSSProperties`     | -            | Inline styles for the layout container                                                  |
| `children`  | `Layout.Column[]`   | **Required** | `Layout.Header` and/or `Layout.Column` components                                       |
| `fill`      | `boolean`           | `false`      | Fill the available height instead of growing with content (see [Fill Mode](#fill-mode)) |
| `columns`   | `1 \| 2 \| 3`       | -            | **(Deprecated)** Auto-detected from `Layout.Column` children count when omitted         |
| `title`     | `string`            | -            | **(Deprecated)** Use `<Layout.Header title="...">` instead                              |
| `actions`   | `React.ReactNode[]` | -            | **(Deprecated)** Use `<Layout.Header actions={[...]}>` instead                          |
| `gap`       | `number`            | `4`          | **(Deprecated)** Use `className` (e.g. `className="gap-6"`) instead                     |

### Layout.Header Props

`Layout.Header` is a compound sub-component for page-level headers. Place it as a direct child of `<Layout>`, above any `<Layout.Column>` children.

| Prop       | Type                | Default | Description                                                |
| ---------- | ------------------- | ------- | ---------------------------------------------------------- |
| `title`    | `string`            | -       | Page title (left side, rendered as `<h1>`)                 |
| `actions`  | `React.ReactNode[]` | -       | Action buttons or nodes (right side)                       |
| `children` | `React.ReactNode`   | -       | Full-width content below the title/actions row (e.g. tabs) |

### Layout.Column Props

| Prop        | Type                          | Default | Description                                                               |
| ----------- | ----------------------------- | ------- | ------------------------------------------------------------------------- |
| `className` | `string`                      | -       | Additional CSS classes                                                    |
| `style`     | `CSSProperties`               | -       | Inline styles for the column                                              |
| `area`      | `"left" \| "main" \| "right"` | -       | Column area role for explicit width control (see [Area Mode](#area-mode)) |
| `children`  | `React.ReactNode`             | -       | Column content                                                            |

## Column Configurations

### 1 Column

Full-width layout, always stacks vertically:

```tsx
<Layout>
  <Layout.Column>
    <DescriptionCard data={data} fields={fields} />
  </Layout.Column>
</Layout>
```

**Responsive behavior:**

* All screens: 1 column (full width)

### 2 Columns

Main content with sidebar:

```tsx
<Layout>
  <Layout.Column>
    {/* Main content - flexible width */}
    <DescriptionCard data={orderData} fields={orderFields} />
  </Layout.Column>
  <Layout.Column>
    {/* Sidebar - fixed 280px on desktop */}
    <Card>Quick Actions</Card>
    <Card>History</Card>
  </Layout.Column>
</Layout>
```

**Responsive behavior:**

* Mobile (< 1024px): Stacks vertically
* Desktop (≥ 1024px): First column flexible, second column 280px

**Use cases:**

* Detail pages with sidebar
* Forms with preview
* Main content + related items

### 3 Columns

Left sidebar, main content, right sidebar:

```tsx
<Layout>
  <Layout.Column>
    {/* Left sidebar - fixed 320px */}
    <Navigation />
  </Layout.Column>
  <Layout.Column>
    {/* Main content - flexible */}
    <DescriptionCard data={data} fields={fields} />
  </Layout.Column>
  <Layout.Column>
    {/* Right sidebar - fixed 280px */}
    <ActivityFeed />
  </Layout.Column>
</Layout>
```

**Responsive behavior:**

* Mobile (< 1280px): Stacks vertically
* Desktop (≥ 1280px): Left 320px, middle flexible, right 280px

**Use cases:**

* Dashboards with multiple panels
* Complex detail pages
* Editor with navigation and preview

### 4+ Columns

When more than 3 `Layout.Column` children are provided, all columns share equal width:

```tsx
<Layout>
  <Layout.Column>{/* 25% */}</Layout.Column>
  <Layout.Column>{/* 25% */}</Layout.Column>
  <Layout.Column>{/* 25% */}</Layout.Column>
  <Layout.Column>{/* 25% */}</Layout.Column>
</Layout>
```

**Responsive behavior:**

* Mobile (< 1280px): Stacks vertically
* Desktop (≥ 1280px): Equal-width columns (`repeat(N, 1fr)`)

## Header

Use `Layout.Header` to add a page-level header with title, actions, and optional full-width content:

```tsx
<Layout>
  <Layout.Header
    title="Order #12345"
    actions={[
      <Button key="edit">Edit</Button>,
      <Button key="delete" variant="destructive">
        Delete
      </Button>,
    ]}
  />
  <Layout.Column>{/* ... */}</Layout.Column>
  <Layout.Column>{/* ... */}</Layout.Column>
</Layout>
```

The header displays:

* **Title** on the left (rendered as `<h1>`, large and bold)
* **Actions** on the right (buttons, dropdowns, etc.)
* **Children** (optional) full-width below the title/actions row

### Header with Tabs

```tsx
<Layout>
  <Layout.Header title="Purchase Orders" actions={[<Button key="create">Create</Button>]}>
    <Tabs value={tab} onValueChange={setTab}>
      <TabsList>
        <TabsTrigger value="all">All</TabsTrigger>
        <TabsTrigger value="open">Open</TabsTrigger>
      </TabsList>
    </Tabs>
  </Layout.Header>
  <Layout.Column>…</Layout.Column>
</Layout>
```

## Area Mode

By default, column widths are determined by position (first, second, third). You can use the `area` prop on `Layout.Column` to explicitly assign roles:

| Area      | Width          |
| --------- | -------------- |
| `"left"`  | Fixed 320px    |
| `"main"`  | Flexible (1fr) |
| `"right"` | Fixed 280px    |
| *(unset)* | Flexible (1fr) |

If any `Layout.Column` has an `area` prop, all columns switch to area-based widths. Columns without an `area` default to flexible (`1fr`).

```tsx
<Layout>
  <Layout.Column area="left">
    <nav>Sidebar</nav>
  </Layout.Column>
  <Layout.Column area="main">
    <h2>Content</h2>
  </Layout.Column>
</Layout>
```

Columns are rendered in source order — place them in the visual order you want.

## Fill Mode

By default, `<Layout>` grows with its content and the AppShell content area scrolls. Set `fill` to instead stretch the layout to the available height and bound its column row, so a child component can scroll **internally** while the page chrome stays pinned:

```tsx
<Layout fill>
  <Layout.Header title="Products" />
  <Layout.Column>
    <DataTable.Root value={table}>
      <DataTable.Toolbar>
        <DataTable.Filters />
      </DataTable.Toolbar>
      <DataTable.Table />
      <DataTable.Footer>
        <DataTable.Pagination />
      </DataTable.Footer>
    </DataTable.Root>
  </Layout.Column>
</Layout>
```

With `fill`, the `Layout.Header` (title/actions), the `DataTable` toolbar, its column header row, and its footer all remain visible regardless of row count — only the table's rows region scrolls vertically. When the content is short enough to fit, nothing stretches and no scrollbar appears.

Use `fill` for pages whose main content manages its own scrolling (typically a `DataTable`). Leave it off for pages that should flow and scroll naturally (forms, articles, dashboards). It is intended for single-row layouts; when multiple columns stack vertically on mobile, the content area scrolls as usual.

> Because the shell is viewport-bounded, page content scrolls inside the content area rather than on the document. If you have code that read `window`/document scroll, reach for the content scroll container instead — see [Accessing the content scroll container](sidebar-layout.md#accessing-the-content-scroll-container).

## Gap Spacing

Use `className` to control the space between columns:

```tsx
<Layout className="astw:gap-6">
  <Layout.Column>{/* ... */}</Layout.Column>
  <Layout.Column>{/* ... */}</Layout.Column>
</Layout>
```

## Examples

### Order Detail Page

```tsx
function OrderDetailPage() {
  const { id } = useParams();
  const order = useOrder(id);

  return (
    <Layout>
      <Layout.Header
        title={`Order #${order.orderNumber}`}
        actions={[
          <Button key="print" variant="outline">
            Print
          </Button>,
          <Button key="edit">Edit Order</Button>,
        ]}
      />
      <Layout.Column>
        <DescriptionCard
          data={order}
          fields={[
            { key: "customer.name", label: "Customer" },
            { key: "orderDate", label: "Order Date", type: "date" },
            { key: "status", label: "Status", type: "badge" },
            { type: "divider" },
            { key: "total", label: "Total", type: "money" },
            { key: "shippingAddress", label: "Shipping", type: "address" },
          ]}
        />
      </Layout.Column>
      <Layout.Column>
        <Card>
          <h3>Quick Actions</h3>
          <Button fullWidth>Mark as Shipped</Button>
          <Button fullWidth>Send Invoice</Button>
        </Card>
        <Card>
          <h3>Order History</h3>
          <Timeline events={order.history} />
        </Card>
      </Layout.Column>
    </Layout>
  );
}
```

### Dashboard with 3 Columns

```tsx
function Dashboard() {
  return (
    <Layout>
      <Layout.Header title="Dashboard" />
      <Layout.Column>
        <Card>
          <h3>Navigation</h3>
          <nav>
            <a href="#overview">Overview</a>
            <a href="#sales">Sales</a>
            <a href="#products">Products</a>
          </nav>
        </Card>
      </Layout.Column>
      <Layout.Column>
        <Card>
          <h2>Sales Overview</h2>
          <Chart data={salesData} />
        </Card>
        <Card>
          <h2>Recent Orders</h2>
          <OrdersTable orders={recentOrders} />
        </Card>
      </Layout.Column>
      <Layout.Column>
        <Card>
          <h3>Activity Feed</h3>
          <ActivityList activities={activities} />
        </Card>
      </Layout.Column>
    </Layout>
  );
}
```

### Form with Live Preview

```tsx
function ProductEditor() {
  const [product, setProduct] = useState(initialProduct);

  return (
    <Layout>
      <Layout.Header
        title="Edit Product"
        actions={[
          <Button key="cancel" variant="outline">
            Cancel
          </Button>,
          <Button key="save">Save Changes</Button>,
        ]}
      />
      <Layout.Column>
        <Card>
          <h3>Product Details</h3>
          <Input
            label="Name"
            value={product.name}
            onChange={(e) => setProduct({ ...product, name: e.target.value })}
          />
          <Input
            label="Price"
            type="number"
            value={product.price}
            onChange={(e) => setProduct({ ...product, price: e.target.value })}
          />
          <Textarea
            label="Description"
            value={product.description}
            onChange={(e) => setProduct({ ...product, description: e.target.value })}
          />
        </Card>
      </Layout.Column>
      <Layout.Column>
        <Card>
          <h3>Preview</h3>
          <ProductCard product={product} />
        </Card>
      </Layout.Column>
    </Layout>
  );
}
```

### Area-Based Layout

```tsx
function EditorPage() {
  return (
    <Layout>
      <Layout.Header title="Editor" />
      <Layout.Column area="left">
        <FileTree />
      </Layout.Column>
      <Layout.Column area="main">
        <CodeEditor />
      </Layout.Column>
      <Layout.Column area="right">
        <PropertiesPanel />
      </Layout.Column>
    </Layout>
  );
}
```

### Single Column with Header

```tsx
<Layout>
  <Layout.Header title="Settings" actions={[<Button key="save">Save Changes</Button>]} />
  <Layout.Column>
    <Card>
      <h3>Account Settings</h3>
      <SettingsForm />
    </Card>
  </Layout.Column>
</Layout>
```

## Responsive Behavior

The Layout component automatically handles responsive breakpoints:

### Breakpoints

| Screen Size               | 1 Column   | 2 Columns    | 3+ Columns   |
| ------------------------- | ---------- | ------------ | ------------ |
| Mobile (< 1024px)         | Full width | Stacked      | Stacked      |
| Desktop (1024px - 1280px) | Full width | Side-by-side | Stacked      |
| Large (≥ 1280px)          | Full width | Side-by-side | Side-by-side |

### Column Widths

**2 Columns (Desktop):**

* Column 1: Flexible (takes remaining space)
* Column 2: Fixed 280px

**3 Columns (Desktop):**

* Column 1: Fixed 320px
* Column 2: Flexible (takes remaining space)
* Column 3: Fixed 280px

**4+ Columns (Desktop):**

* All columns: Equal width (`repeat(N, 1fr)`)

## Validation

The Layout component validates its children:

* Only `Layout.Header` and `Layout.Column` are recognized as direct children; other elements are silently filtered out
* If multiple `Layout.Header` children are provided, only the first one is rendered
* When the deprecated `columns` prop is set and doesn't match the actual `Layout.Column` child count, a console warning is emitted

## Styling

### Custom Styling

Add custom classes to the layout container:

```tsx
<Layout className="astw:bg-gray-50 astw:p-8 astw:rounded-lg">{/* ... */}</Layout>
```

Add custom classes to individual columns:

```tsx
<Layout>
  <Layout.Column className="astw:bg-white astw:shadow-sm">
    {/* Main content with background */}
  </Layout.Column>
  <Layout.Column className="astw:space-y-4">{/* Sidebar with extra spacing */}</Layout.Column>
</Layout>
```

## Best Practices

### Do:

* ✅ Use 2 columns for detail pages with sidebar
* ✅ Use 3 columns for dashboards and complex layouts
* ✅ Add meaningful titles to pages
* ✅ Group related actions in the header
* ✅ Keep sidebars focused (5-7 items max)

### Don't:

* ❌ Use 3 columns for mobile-first designs (too complex)
* ❌ Mix Layout with other layout systems (conflicts)
* ❌ Put too many actions in header (use dropdown menus)
* ❌ Forget to handle responsive behavior

## Accessibility

* Semantic HTML structure
* Proper heading hierarchy
* Keyboard navigation support
* Screen reader friendly

## Related Components

* [Grid](grid) - Content-level grid for arranging items into columns
* [DescriptionCard](description-card) - Display data in columns
* [Badge](badge) - Status indicators
* [SidebarLayout](sidebar-layout) - App-level layout

## Related Concepts

* [Styling and Theming](../concepts/styling-theming) - Customize appearance
* [Modules and Resources](../concepts/modules-and-resources) - Page structure

---

---
url: https://docs.tailor.tech/app-shell/components/menu.md
description: >-
  Dropdown menu with a compound component API, supporting checkbox/radio items,
  groups, separators, and nested sub-menus
---

# Menu

The `Menu` component provides a dropdown menu with a compound component API. It is backed by Base UI's Menu primitive.

[Live preview in the UI Catalogue →](https://ui.tailor.tech/components/menu)

## Import

```tsx
import { Menu } from "@tailor-platform/app-shell";
```

## Basic Usage

```tsx
<Menu.Root>
  <Menu.Trigger>Open menu</Menu.Trigger>
  <Menu.Content>
    <Menu.Item>Edit</Menu.Item>
    <Menu.Item>Duplicate</Menu.Item>
    <Menu.Separator />
    <Menu.Item>Delete</Menu.Item>
  </Menu.Content>
</Menu.Root>
```

## Sub-components

| Sub-component                | Description                                               |
| ---------------------------- | --------------------------------------------------------- |
| `Menu.Root`                  | Manages menu open/close state                             |
| `Menu.Trigger`               | Element that opens the menu when clicked                  |
| `Menu.Content`               | The menu popup containing menu items                      |
| `Menu.Item`                  | An individual interactive item                            |
| `Menu.LinkItem`              | A link item for navigation                                |
| `Menu.CheckboxItem`          | A menu item that toggles a setting on or off              |
| `Menu.CheckboxItemIndicator` | Indicates whether the checkbox item is ticked             |
| `Menu.RadioItem`             | A menu item that works like a radio button within a group |
| `Menu.RadioItemIndicator`    | Indicates whether the radio item is selected              |
| `Menu.RadioGroup`            | Groups related radio items                                |
| `Menu.Group`                 | Groups related menu items                                 |
| `Menu.GroupLabel`            | An accessible label for a `Menu.Group`                    |
| `Menu.Separator`             | A visual separator between menu items                     |
| `Menu.SubmenuRoot`           | Groups all parts of a nested sub-menu                     |
| `Menu.SubmenuTrigger`        | A menu item that opens a sub-menu                         |

## Props

### Menu.Root Props

| Prop           | Type                      | Default | Description                       |
| -------------- | ------------------------- | ------- | --------------------------------- |
| `open`         | `boolean`                 | -       | Controlled open state             |
| `defaultOpen`  | `boolean`                 | `false` | Initial open state (uncontrolled) |
| `onOpenChange` | `(open: boolean) => void` | -       | Callback when open state changes  |
| `modal`        | `boolean`                 | `true`  | Whether the menu is modal         |
| `disabled`     | `boolean`                 | `false` | Disables the entire menu          |
| `children`     | `React.ReactNode`         | -       | Menu sub-components               |

### Menu.Content Props

| Prop        | Type                                                                                                           | Default                                             | Description                         |
| ----------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | ----------------------------------- |
| `position`  | `{ side?: "top" \| "right" \| "bottom" \| "left"; align?: "start" \| "center" \| "end"; sideOffset?: number }` | `{ side: "bottom", align: "start", sideOffset: 4 }` | Placement of the popup              |
| `className` | `string`                                                                                                       | -                                                   | Additional CSS classes              |
| `children`  | `React.ReactNode`                                                                                              | -                                                   | Menu items and other sub-components |

### Menu.Item Props

Accepts `className`, `disabled`, and all standard Base UI `Menu.Item` props.

### Menu.SubmenuRoot Props

| Prop           | Type                      | Default | Description                       |
| -------------- | ------------------------- | ------- | --------------------------------- |
| `open`         | `boolean`                 | -       | Controlled open state             |
| `defaultOpen`  | `boolean`                 | `false` | Initial open state (uncontrolled) |
| `onOpenChange` | `(open: boolean) => void` | -       | Callback when open state changes  |
| `disabled`     | `boolean`                 | `false` | Disables the entire sub-menu      |
| `children`     | `React.ReactNode`         | -       | Sub-menu sub-components           |

## Grouped Items

Use `Menu.Group` and `Menu.GroupLabel` to visually group related items:

```tsx
<Menu.Root>
  <Menu.Trigger>Actions</Menu.Trigger>
  <Menu.Content>
    <Menu.Group>
      <Menu.GroupLabel>File</Menu.GroupLabel>
      <Menu.Item>New</Menu.Item>
      <Menu.Item>Open</Menu.Item>
    </Menu.Group>
    <Menu.Separator />
    <Menu.Group>
      <Menu.GroupLabel>Edit</Menu.GroupLabel>
      <Menu.Item>Cut</Menu.Item>
      <Menu.Item>Copy</Menu.Item>
      <Menu.Item>Paste</Menu.Item>
    </Menu.Group>
  </Menu.Content>
</Menu.Root>
```

## Checkbox Items

```tsx
const [bold, setBold] = useState(false);
const [italic, setItalic] = useState(false);

<Menu.Root>
  <Menu.Trigger>Format</Menu.Trigger>
  <Menu.Content>
    <Menu.CheckboxItem checked={bold} onCheckedChange={setBold}>
      <Menu.CheckboxItemIndicator>✓</Menu.CheckboxItemIndicator>
      Bold
    </Menu.CheckboxItem>
    <Menu.CheckboxItem checked={italic} onCheckedChange={setItalic}>
      <Menu.CheckboxItemIndicator>✓</Menu.CheckboxItemIndicator>
      Italic
    </Menu.CheckboxItem>
  </Menu.Content>
</Menu.Root>;
```

## Radio Items

```tsx
const [align, setAlign] = useState("left");

<Menu.Root>
  <Menu.Trigger>Align</Menu.Trigger>
  <Menu.Content>
    <Menu.RadioGroup value={align} onValueChange={setAlign}>
      <Menu.RadioItem value="left">
        <Menu.RadioItemIndicator>●</Menu.RadioItemIndicator>
        Left
      </Menu.RadioItem>
      <Menu.RadioItem value="center">
        <Menu.RadioItemIndicator>●</Menu.RadioItemIndicator>
        Center
      </Menu.RadioItem>
      <Menu.RadioItem value="right">
        <Menu.RadioItemIndicator>●</Menu.RadioItemIndicator>
        Right
      </Menu.RadioItem>
    </Menu.RadioGroup>
  </Menu.Content>
</Menu.Root>;
```

## Nested Sub-menus

```tsx
<Menu.Root>
  <Menu.Trigger>Edit</Menu.Trigger>
  <Menu.Content>
    <Menu.Item>Cut</Menu.Item>
    <Menu.Item>Copy</Menu.Item>
    <Menu.SubmenuRoot>
      <Menu.SubmenuTrigger>Paste Special ›</Menu.SubmenuTrigger>
      <Menu.Content>
        <Menu.Item>Paste as Plain Text</Menu.Item>
        <Menu.Item>Paste and Match Style</Menu.Item>
      </Menu.Content>
    </Menu.SubmenuRoot>
  </Menu.Content>
</Menu.Root>
```

## Examples

### Context Menu

```tsx
function OrderActions({ order }: { order: Order }) {
  return (
    <Menu.Root>
      <Menu.Trigger>
        <Button variant="ghost" size="icon">
          <EllipsisVerticalIcon />
        </Button>
      </Menu.Trigger>
      <Menu.Content>
        <Menu.Item onSelect={() => handleEdit(order)}>Edit</Menu.Item>
        <Menu.Item onSelect={() => handleDuplicate(order)}>Duplicate</Menu.Item>
        <Menu.Separator />
        <Menu.Item onSelect={() => handleDelete(order)}>Delete</Menu.Item>
      </Menu.Content>
    </Menu.Root>
  );
}
```

## Accessibility

* Menu items are keyboard navigable with arrow keys
* Pressing `Escape` closes the menu
* Sub-menus open on arrow-right and close on arrow-left
* `Menu.GroupLabel` is automatically associated with its parent group

## Related Components

* [Dialog](dialog) - For actions that require confirmation
* [Sheet](sheet) - Slide-in panel for more complex workflows
* [Button](button) - Common trigger element for menus

---

---
url: https://docs.tailor.tech/app-shell/components/metric-card.md
description: >-
  Compact card for dashboard KPI summaries with title, value, optional trend and
  description
---

# MetricCard

`MetricCard` is a presentational card for displaying a single KPI (key performance indicator) on dashboards. It shows a small title, a prominent value, and optionally a trend indicator and supplementary description text. In v1 the component is static (no click handler or internal actions).

[Live preview in the UI Catalogue →](https://ui.tailor.tech/components/metric-card)

## Import

```tsx
import { MetricCard } from "@tailor-platform/app-shell";
```

## Basic Usage

```tsx
<MetricCard
  title="Net total payment"
  value="$1,500.00"
  trend={{ direction: "up", value: "+5%" }}
  description="vs last month"
/>
```

## Props

| Prop          | Type                                                        | Default      | Description                                                                                                            |
| ------------- | ----------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------- |
| `title`       | `string`                                                    | **Required** | Short title / header (e.g. "Net total", "Revenue")                                                                     |
| `value`       | `React.ReactNode`                                           | **Required** | Main value (string, number, or custom content)                                                                         |
| `trend`       | `{ direction: "up" \| "down" \| "neutral"; value: string }` | -            | Optional trend (e.g. "+12%", "-5%", "0%")                                                                              |
| `description` | `string`                                                    | -            | Optional supplementary text (e.g. "vs last month", "this week"). Empty strings are treated as absent and not rendered. |
| `icon`        | `React.ReactNode`                                           | -            | Optional icon in the title row                                                                                         |
| `className`   | `string`                                                    | -            | Additional CSS classes for the card root                                                                               |

## Trend Directions

* **up** — Positive change (success styling, e.g. green).
* **down** — Negative change (destructive styling, e.g. red).
* **neutral** — No change or neutral (muted styling).

```tsx
<MetricCard
  title="Revenue"
  value="$2,400"
  trend={{ direction: "up", value: "+12%" }}
  description="vs last month"
/>

<MetricCard
  title="Costs"
  value="$800"
  trend={{ direction: "down", value: "-5%" }}
  description="vs last quarter"
/>

<MetricCard
  title="Balance"
  value="$0"
  trend={{ direction: "neutral", value: "0%" }}
/>
```

## With Icon

```tsx
<MetricCard title="Total orders" value="142" icon={<OrderIcon />} description="this week" />
```

## Related

* [Grid](grid) — Arrange MetricCards in responsive columns (e.g. KPI grids).
* [Layout](layout) — Page layout for placing MetricCards in a grid.
* [DescriptionCard](description-card) — Structured key-value cards for detail views.
* [Badge](badge) — Status badges that can complement metric displays.

---

---
url: https://docs.tailor.tech/app-shell/components/select.md
description: Single or multi-select dropdown with optional async data fetching
---

# Select

The `Select` component provides a fully assembled single or multi-select dropdown. Pass `items` and get a ready-to-use select out of the box. For async data fetching use `Select.Async`. For custom compositions use `Select.Parts`.

[Live preview in the UI Catalogue →](https://ui.tailor.tech/components/select)

## Import

```tsx
import { Select } from "@tailor-platform/app-shell";
```

## Basic Usage

```tsx
<Select
  items={["Apple", "Banana", "Cherry"]}
  placeholder="Pick a fruit"
  onValueChange={(value) => console.log(value)}
/>
```

## Props

### Select Props

| Prop              | Type                                                                       | Default | Description                                                         |
| ----------------- | -------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------- |
| `items`           | `I[]`                                                                      | -       | Items to display. May be a flat array or an array of `ItemGroup<T>` |
| `placeholder`     | `string`                                                                   | -       | Placeholder text shown when no value is selected                    |
| `multiple`        | `true \| false \| undefined`                                               | `false` | Enables multi-select mode                                           |
| `value`           | `T \| null` (single) or `T[]` (multiple)                                   | -       | Controlled value                                                    |
| `defaultValue`    | `T \| null` (single) or `T[]` (multiple)                                   | -       | Initial value (uncontrolled)                                        |
| `onValueChange`   | `(value: T \| null) => void` (single) or `(value: T[]) => void` (multiple) | -       | Called when the selected value changes                              |
| `renderValue`     | `(value: T \| null \| T[]) => React.ReactNode`                             | -       | Custom render function for the selected value display               |
| `mapItem`         | `(item: T) => MappedItem`                                                  | -       | Map each item to its label, key, and optional custom render         |
| `className`       | `string`                                                                   | -       | Additional CSS classes for the root container                       |
| `disabled`        | `boolean`                                                                  | `false` | Disables the select                                                 |
| `aria-label`      | `string`                                                                   | -       | Accessible name for the trigger. Use when there is no visible label |
| `aria-labelledby` | `string`                                                                   | -       | ID of the element(s) that label the trigger                         |
| `id`              | `string`                                                                   | -       | ID applied to the combobox trigger element                          |

### MappedItem

```ts
interface MappedItem {
  label: string; // Display text, used for filtering and a11y
  key?: string; // React key. Defaults to label
  render?: React.ReactNode; // Custom JSX to render in the dropdown
}
```

### ItemGroup

Pass grouped items by wrapping them in `ItemGroup<T>` objects:

```ts
interface ItemGroup<T> {
  label: string;
  items: T[];
}
```

## Grouped Items

```tsx
const fruits = [
  { label: "Citrus", items: ["Orange", "Lemon", "Lime"] },
  { label: "Berries", items: ["Strawberry", "Blueberry"] },
];

<Select items={fruits} placeholder="Pick a fruit" />;
```

## Object Items with mapItem

When items are objects, use `mapItem` to tell the component how to display them:

```tsx
type Fruit = { id: number; name: string };

const fruits: Fruit[] = [
  { id: 1, name: "Apple" },
  { id: 2, name: "Banana" },
];

<Select
  items={fruits}
  mapItem={(fruit) => ({ label: fruit.name, key: String(fruit.id) })}
  onValueChange={(fruit) => console.log(fruit?.id)}
/>;
```

## Multi-select

```tsx
<Select
  items={["Red", "Green", "Blue"]}
  multiple
  placeholder="Pick colors"
  onValueChange={(colors) => console.log(colors)}
/>
```

## Async Loading

Use `Select.Async` to load items from an API. The fetcher is called each time the dropdown is opened.

```tsx
import { type SelectAsyncFetcher } from "@tailor-platform/app-shell";

const fetcher: SelectAsyncFetcher<Fruit> = async ({ signal }) => {
  const res = await fetch("/api/fruits", { signal });
  return res.json();
};

<Select.Async
  fetcher={fetcher}
  mapItem={(fruit) => ({ label: fruit.name, key: String(fruit.id) })}
  placeholder="Pick a fruit"
  onValueChange={(fruit) => console.log(fruit)}
/>;
```

### Select.Async Props

Accepts all the same props as `Select` except `items`, plus:

| Prop                   | Type                       | Default                    | Description                                                                                                                        |
| ---------------------- | -------------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `fetcher`              | `SelectAsyncFetcher<T>`    | -                          | Fetcher called each time the dropdown is opened                                                                                    |
| `loadingText`          | `string`                   | `"Loading..."`             | Text shown while loading                                                                                                           |
| `errorText`            | `string`                   | `"Couldn't load results."` | Message shown in the dropdown when the fetcher fails (with Retry)                                                                  |
| `retryText`            | `string`                   | `"Retry"`                  | Label for the retry button in the error state                                                                                      |
| `onFetchError`         | `(error: unknown) => void` | -                          | Called once per outage when a fetch fails (logging/error tracking)                                                                 |
| `modal`                | `boolean`                  | `false`                    | Whether the select traps focus (modal behavior). Set to `true` when rendering inside a `Dialog` or `Sheet` to preserve focus-trap. |
| `alignItemWithTrigger` | `boolean`                  | `false`                    | Whether to align the selected item with the trigger when the dropdown opens.                                                       |

> **Note:** `Select.Async` does not support `ItemGroup<T>[]` — the fetcher must return a flat array.

> **Limitation:** `Select.Async` defaults to `modal={false}` and `alignItemWithTrigger={false}` to work around a Base UI scroll-lock bug with dynamically loaded items. As a result, it may not function correctly inside focus-trapping containers such as `Dialog` or `Sheet` — the focus trap can block interaction with the dropdown, or the portal may render outside the modal's visible area. If you need an async dropdown inside a `Dialog` or `Sheet`, prefer [`Combobox.Async`](combobox) which uses Popover-based positioning and does not have this constraint.

### SelectAsyncFetcher

```ts
type SelectAsyncFetcher<T> = (options: { signal: AbortSignal }) => Promise<T[]>;
```

### Error handling

If the fetcher throws or rejects, `Select.Async` renders a built-in inline error state in the dropdown — the `errorText` message plus a **Retry** button that re-runs the fetch — instead of the misleading empty state. Aborted requests (the dropdown closed before the fetch settled) are ignored, and announcements are de-duped per outage. Pass `onFetchError` to run a side effect (logging, toast) — it fires once per outage and re-arms after the next successful fetch.

## Low-level Primitives

`Select.Parts` exposes the styled sub-components for fully custom compositions:

```tsx
const { Root, Trigger, Value, Content, Item, Group, GroupLabel, Separator } = Select.Parts;
```

## Form submission

Inside a `Field.Root`, the field's `name` identifies the value and these props are unnecessary —
see [Form](form). They matter for **native** submission: a plain `<form>`, `new FormData(form)`,
or a server action.

| Prop                | Type                          | Default | Description                                                                                              |
| ------------------- | ----------------------------- | ------- | -------------------------------------------------------------------------------------------------------- |
| `name`              | `string`                      | -       | Names the hidden input for native submission. **Ignored inside a `Field.Root`** — the field's name wins. |
| `form`              | `string`                      | -       | `id` of the owning form, when the control is rendered outside it.                                        |
| `required`          | `boolean`                     | `false` | Blocks submission until a value is chosen, surfacing the matching `Field.Error`.                         |
| `inputRef`          | `React.Ref<HTMLInputElement>` | -       | Ref to the hidden input (use for React Hook Form's `field.ref`).                                         |
| `itemToStringValue` | `(item: T) => string`         | -       | Serialises a non-string item for submission. Items shaped `{ value, label }` use `value` automatically.  |

## Examples

### Controlled Select

```tsx
const [selected, setSelected] = useState<string | null>(null);

<Select
  items={["Draft", "Pending", "Approved", "Rejected"]}
  value={selected}
  onValueChange={setSelected}
  placeholder="Select status"
/>;
```

### Custom Render

```tsx
<Select
  items={statuses}
  mapItem={(s) => ({
    label: s.name,
    key: s.id,
    render: (
      <span className="flex items-center gap-2">
        <span className={`size-2 rounded-full bg-${s.color}`} />
        {s.name}
      </span>
    ),
  })}
  placeholder="Select status"
/>
```

### Async with Parts (custom composition)

Combine `Select.useAsync` with `Select.Parts` for full control over layout and rendering:

`Select.useAsync` accepts the same options as `Select.Async` (including `onFetchError`) and returns:

| Property  | Type         | Description                                             |
| --------- | ------------ | ------------------------------------------------------- |
| `items`   | `T[]`        | Currently loaded items                                  |
| `loading` | `boolean`    | Whether a fetch is in progress                          |
| `error`   | `unknown`    | The error thrown by the last fetch, if any              |
| `retry`   | `() => void` | Re-runs the last fetch (use to build a custom retry UI) |

```tsx
type Fruit = { id: number; name: string };

const fruits = Select.useAsync({
  fetcher: async ({ signal }) => {
    const res = await fetch("/api/fruits", { signal });
    return res.json() as Promise<Fruit[]>;
  },
  onFetchError: (error) => reportError(error),
});

<Select.Parts.Root {...fruits} itemToStringLabel={(f) => f.name}>
  <Select.Parts.Trigger>
    <Select.Parts.Value placeholder="Pick a fruit" />
  </Select.Parts.Trigger>
  <Select.Parts.Content>
    {fruits.error ? (
      <div className="px-4 py-2 text-center text-sm">
        Couldn't load. <button onClick={fruits.retry}>Retry</button>
      </div>
    ) : fruits.loading ? (
      <div className="px-4 py-2 text-center text-sm text-muted-foreground">Loading...</div>
    ) : (
      fruits.items.map((f) => (
        <Select.Parts.Item key={f.id} value={f}>
          {f.name}
        </Select.Parts.Item>
      ))
    )}
  </Select.Parts.Content>
</Select.Parts.Root>;
```

## Accessibility

* The trigger exposes the `combobox` role. When used inside a `Form`/`FormControl` it is labeled automatically.
* When used standalone (e.g. a table toolbar or list filter) there is no visible `<label>`, so give the trigger an accessible name with `aria-label` or `aria-labelledby`. Otherwise screen readers announce only the current value.

```tsx
// Announced as "Direction filter, combobox" instead of just the value
<Select items={items} value={value} onValueChange={setValue} aria-label="Direction filter" />

// Or point at a visible label
<span id="dir-label">From</span>
<Select items={items} aria-labelledby="dir-label" />
```

## Related Components

* [Combobox](combobox) - Searchable combobox with filtering
* [Autocomplete](autocomplete) - Free-text input with suggestions

---

---
url: https://docs.tailor.tech/app-shell/components/sheet.md
description: Slide-in panel backed by a Drawer with native swipe-to-dismiss support
---

# Sheet

The `Sheet` component is a slide-in panel that appears from any edge of the screen. It is backed by Base UI's Drawer primitive and includes native swipe-to-dismiss gesture support on touch devices.

[Live preview in the UI Catalogue →](https://ui.tailor.tech/components/sheet)

## Import

```tsx
import { Sheet } from "@tailor-platform/app-shell";
```

## Basic Usage

```tsx
<Sheet.Root side="right">
  <Sheet.Trigger render={<Button />}>Open Settings</Sheet.Trigger>
  <Sheet.Content>
    <Sheet.Header>
      <Sheet.Title>Settings</Sheet.Title>
      <Sheet.Description>Manage your preferences.</Sheet.Description>
    </Sheet.Header>
    {/* Sheet body content */}
    <Sheet.Footer>
      <Sheet.Close render={<Button variant="outline" />}>Close</Sheet.Close>
    </Sheet.Footer>
  </Sheet.Content>
</Sheet.Root>
```

## Sub-components

| Sub-component       | Description                                                                  |
| ------------------- | ---------------------------------------------------------------------------- |
| `Sheet.Root`        | Manages open/close state and controls the slide direction                    |
| `Sheet.Trigger`     | Element that opens the sheet when clicked                                    |
| `Sheet.Content`     | The main sheet panel; includes close button and backdrop when `modal={true}` |
| `Sheet.Header`      | Layout wrapper for title and description                                     |
| `Sheet.Footer`      | Layout wrapper for action buttons                                            |
| `Sheet.Title`       | Sheet title (announced by screen readers)                                    |
| `Sheet.Description` | Additional context below the title                                           |
| `Sheet.Close`       | Button that closes the sheet                                                 |

## Props

### Sheet.Root Props

| Prop           | Type                                     | Default   | Description                                       |
| -------------- | ---------------------------------------- | --------- | ------------------------------------------------- |
| `side`         | `"top" \| "right" \| "bottom" \| "left"` | `"right"` | Which edge of the screen the sheet slides in from |
| `open`         | `boolean`                                | -         | Controlled open state                             |
| `defaultOpen`  | `boolean`                                | `false`   | Initial open state (uncontrolled)                 |
| `onOpenChange` | `(open: boolean) => void`                | -         | Callback when open state changes                  |
| `modal`        | `boolean`                                | `true`    | Whether the sheet is modal                        |
| `children`     | `React.ReactNode`                        | -         | Sheet sub-components                              |

When `modal={false}`, the sheet does not render a backdrop.

### Sheet.Content Props

| Prop        | Type                                     | Default | Description                                                     |
| ----------- | ---------------------------------------- | ------- | --------------------------------------------------------------- |
| `size`      | `"sm" \| "md" \| "lg" \| "xl" \| "full"` | `"sm"`  | Max-width of the sheet panel (applies to left/right sides only) |
| `className` | `string`                                 | -       | Additional CSS classes                                          |

Also accepts all standard HTML `<div>` props.

### Sheet.Header Props

| Prop     | Type              | Default | Description                                             |
| -------- | ----------------- | ------- | ------------------------------------------------------- |
| `action` | `React.ReactNode` | -       | Action buttons displayed to the right of the title area |

The header renders a close button on the left, title in the center, and action buttons on the right.

### Sheet.Trigger / Sheet.Close Props

Accept a `render` prop for custom element rendering (Base UI render pattern), plus standard button props.

## Sizes

Control the width of the sheet panel using the `size` prop on `Sheet.Content`. This applies to `left` and `right` side sheets.

```tsx
<Sheet.Root side="right">
  <Sheet.Trigger render={<Button />}>Open Small</Sheet.Trigger>
  <Sheet.Content size="sm">…</Sheet.Content>  {/* 384px (24rem) — default */}
</Sheet.Root>

<Sheet.Root side="right">
  <Sheet.Trigger render={<Button />}>Open Medium</Sheet.Trigger>
  <Sheet.Content size="md">…</Sheet.Content>  {/* 512px (32rem) */}
</Sheet.Root>

<Sheet.Root side="right">
  <Sheet.Trigger render={<Button />}>Open Large</Sheet.Trigger>
  <Sheet.Content size="lg">…</Sheet.Content>  {/* 720px (45rem) */}
</Sheet.Root>

<Sheet.Root side="right">
  <Sheet.Trigger render={<Button />}>Open XL</Sheet.Trigger>
  <Sheet.Content size="xl">…</Sheet.Content>  {/* 960px (60rem) */}
</Sheet.Root>

<Sheet.Root side="right">
  <Sheet.Trigger render={<Button />}>Open Full</Sheet.Trigger>
  <Sheet.Content size="full">…</Sheet.Content>  {/* 100% width */}
</Sheet.Root>
```

## Sides

```tsx
<Sheet.Root side="right">…</Sheet.Root>   {/* default — slides from right */}
<Sheet.Root side="left">…</Sheet.Root>    {/* slides from left */}
<Sheet.Root side="top">…</Sheet.Root>     {/* slides from top */}
<Sheet.Root side="bottom">…</Sheet.Root>  {/* slides from bottom */}
```

The swipe-to-dismiss gesture direction is automatically determined by the `side` prop.

## Controlled Usage

```tsx
const [open, setOpen] = useState(false);

<Sheet.Root side="right" open={open} onOpenChange={setOpen}>
  <Sheet.Trigger render={<Button />}>Open</Sheet.Trigger>
  <Sheet.Content>
    <Sheet.Header>
      <Sheet.Title>Filters</Sheet.Title>
    </Sheet.Header>
    <Sheet.Footer>
      <Button onClick={() => setOpen(false)}>Apply</Button>
    </Sheet.Footer>
  </Sheet.Content>
</Sheet.Root>;
```

## Non-modal Sheet

```tsx
<Sheet.Root side="right" modal={false}>
  <Sheet.Trigger render={<Button />}>Open Inspector</Sheet.Trigger>
  <Sheet.Content>
    <Sheet.Header>
      <Sheet.Title>Inspector</Sheet.Title>
    </Sheet.Header>
  </Sheet.Content>
</Sheet.Root>
```

## Examples

### Header with Actions

Place action buttons (e.g., save, edit) to the right of the title using the `action` prop on `Sheet.Header`.

```tsx
<Sheet.Root side="right">
  <Sheet.Trigger render={<Button />}>Edit Record</Sheet.Trigger>
  <Sheet.Content size="lg">
    <Sheet.Header action={<Button size="sm">Save</Button>}>
      <Sheet.Title>Edit Customer</Sheet.Title>
    </Sheet.Header>
    <div className="astw:p-4">
      <Input placeholder="Customer name" />
    </div>
  </Sheet.Content>
</Sheet.Root>
```

### Filter Panel

```tsx
function FilterPanel() {
  return (
    <Sheet.Root side="right">
      <Sheet.Trigger render={<Button variant="outline" />}>Filters</Sheet.Trigger>
      <Sheet.Content>
        <Sheet.Header>
          <Sheet.Title>Filter Orders</Sheet.Title>
          <Sheet.Description>Narrow down orders by criteria.</Sheet.Description>
        </Sheet.Header>
        <div className="astw:p-4 astw:flex astw:flex-col astw:gap-4">
          <Input placeholder="Customer name" />
          <Input placeholder="Order number" />
        </div>
        <Sheet.Footer>
          <Sheet.Close render={<Button variant="outline" />}>Clear</Sheet.Close>
          <Button>Apply Filters</Button>
        </Sheet.Footer>
      </Sheet.Content>
    </Sheet.Root>
  );
}
```

### Bottom Sheet on Mobile

```tsx
<Sheet.Root side="bottom">
  <Sheet.Trigger render={<Button />}>More Options</Sheet.Trigger>
  <Sheet.Content>
    <Sheet.Header>
      <Sheet.Title>Actions</Sheet.Title>
    </Sheet.Header>
    <div className="astw:p-4 astw:flex astw:flex-col astw:gap-2">
      <Button variant="ghost" className="astw:justify-start">
        Edit
      </Button>
      <Button variant="ghost" className="astw:justify-start">
        Duplicate
      </Button>
      <Button variant="ghost" className="astw:justify-start astw:text-destructive">
        Delete
      </Button>
    </div>
  </Sheet.Content>
</Sheet.Root>
```

## Accessibility

* Sheet title is announced by screen readers via `Sheet.Title`
* Focus is trapped inside the sheet while open
* Pressing `Escape` closes the sheet
* The close button is rendered inside `Sheet.Header` in the normal document flow

## Related Components

* [Dialog](dialog) - Centered modal dialog for critical confirmations
* [Button](button) - Use as trigger and action buttons

---

---
url: https://docs.tailor.tech/app-shell/components/sidebar-group.md
description: >-
  Collapsible group component for organizing sidebar navigation items with icons
  and nested structure
---

# SidebarGroup

`SidebarGroup` creates a collapsible group in the sidebar to organize related navigation items. It supports icons, clickable headers, nested groups, and internationalization.

## Import

```tsx
import { SidebarGroup } from "@tailor-platform/app-shell";
```

## Basic Usage

```tsx
import { SidebarGroup, SidebarItem } from "@tailor-platform/app-shell";
import { Package } from "lucide-react";

<DefaultSidebar>
  <SidebarGroup title="Products" icon={<Package />}>
    <SidebarItem to="/products/all" />
    <SidebarItem to="/products/categories" />
    <SidebarItem to="/products/brands" />
  </SidebarGroup>
</DefaultSidebar>;
```

## Props

| Prop          | Type                        | Default      | Description                                    |
| ------------- | --------------------------- | ------------ | ---------------------------------------------- |
| `title`       | `string \| LocalizedString` | **Required** | Group title (supports i18n)                    |
| `icon`        | `React.ReactNode`           | -            | Icon displayed next to title                   |
| `to`          | `string`                    | -            | Makes title clickable (navigates to URL)       |
| `defaultOpen` | `boolean`                   | `true`       | Initial expanded/collapsed state               |
| `children`    | `React.ReactNode`           | **Required** | Child items (SidebarItem, nested groups, etc.) |

## Features

### Collapsible

Groups can be expanded or collapsed by clicking the chevron icon:

```tsx
<SidebarGroup title="Products" icon={<Package />}>
  <SidebarItem to="/products/all" />
  <SidebarItem to="/products/categories" />
</SidebarGroup>
```

Click the chevron (▶/▼) to toggle:

* **Expanded:** Shows all child items
* **Collapsed:** Hides child items, shows only title

### Clickable Header

Make the group title a clickable link:

```tsx
<SidebarGroup
  title="Settings"
  icon={<Settings />}
  to="/settings" // Header navigates here
>
  <SidebarItem to="/settings/profile" />
  <SidebarItem to="/settings/security" />
</SidebarGroup>
```

When `to` is provided:

* Title is a clickable link
* Chevron still collapses/expands children
* Useful for groups with a landing page

### Default State

Control whether groups start expanded or collapsed:

```tsx
// Starts expanded (default)
<SidebarGroup title="Recent" defaultOpen={true}>
  <SidebarItem to="/recent/today" />
</SidebarGroup>

// Starts collapsed
<SidebarGroup title="Archives" defaultOpen={false}>
  <SidebarItem to="/archives/2024" />
  <SidebarItem to="/archives/2023" />
</SidebarGroup>
```

### Nested Groups

Create multi-level navigation:

```tsx
<SidebarGroup title="Products" icon={<Package />}>
  <SidebarItem to="/products/all" />

  <SidebarGroup title="By Category">
    <SidebarItem to="/products/electronics" />
    <SidebarItem to="/products/clothing" />
  </SidebarGroup>

  <SidebarGroup title="Archives" defaultOpen={false}>
    <SidebarItem to="/products/archives/2024" />
    <SidebarItem to="/products/archives/2023" />
  </SidebarGroup>
</SidebarGroup>
```

### Internationalization

Titles support i18n with `defineI18nLabels`:

```tsx
import { defineI18nLabels } from "@tailor-platform/app-shell";

const labels = defineI18nLabels({
  products: {
    en: "Products",
    ja: "商品",
  },
  settings: {
    en: "Settings",
    ja: "設定",
  },
});

<SidebarGroup title={labels.t("products")} icon={<Package />}>
  <SidebarItem to="/products/all" />
</SidebarGroup>;
```

## Examples

### Basic Group

```tsx
import { Package } from "lucide-react";

<SidebarGroup title="Products" icon={<Package />}>
  <SidebarItem to="/products/all" />
  <SidebarItem to="/products/categories" />
  <SidebarItem to="/products/brands" />
</SidebarGroup>;
```

### Clickable Group with Landing Page

```tsx
import { Settings } from "lucide-react";

<SidebarGroup title="Settings" icon={<Settings />} to="/settings">
  <SidebarItem to="/settings/profile" />
  <SidebarItem to="/settings/security" />
  <SidebarItem to="/settings/notifications" />
  <SidebarItem to="/settings/billing" />
</SidebarGroup>;
```

Clicking "Settings" navigates to `/settings`, while child items navigate to their specific pages.

### Multiple Groups

```tsx
import { Package, ShoppingCart, Users, Settings } from "lucide-react";

<DefaultSidebar>
  <SidebarItem to="/dashboard" />

  <SidebarGroup title="Products" icon={<Package />}>
    <SidebarItem to="/products/all" />
    <SidebarItem to="/products/categories" />
  </SidebarGroup>

  <SidebarGroup title="Orders" icon={<ShoppingCart />}>
    <SidebarItem to="/orders/pending" />
    <SidebarItem to="/orders/shipped" />
    <SidebarItem to="/orders/completed" />
  </SidebarGroup>

  <SidebarGroup title="Customers" icon={<Users />}>
    <SidebarItem to="/customers/all" />
    <SidebarItem to="/customers/segments" />
  </SidebarGroup>

  <SidebarSeparator />

  <SidebarGroup title="Settings" icon={<Settings />} to="/settings">
    <SidebarItem to="/settings/profile" />
    <SidebarItem to="/settings/billing" />
  </SidebarGroup>
</DefaultSidebar>;
```

### Nested Groups

```tsx
import { FolderIcon } from "lucide-react";

<SidebarGroup title="Documents" icon={<FolderIcon />}>
  <SidebarItem to="/documents/recent" />

  <SidebarGroup title="Projects">
    <SidebarItem to="/documents/project-a" />
    <SidebarItem to="/documents/project-b" />
  </SidebarGroup>

  <SidebarGroup title="Archives" defaultOpen={false}>
    <SidebarItem to="/documents/archives/2024" />
    <SidebarItem to="/documents/archives/2023" />
    <SidebarItem to="/documents/archives/2022" />
  </SidebarGroup>
</SidebarGroup>;
```

### Collapsed by Default

```tsx
<SidebarGroup title="Admin Tools" icon={<Wrench />} defaultOpen={false}>
  <SidebarItem to="/admin/users" />
  <SidebarItem to="/admin/logs" />
  <SidebarItem to="/admin/system" />
</SidebarGroup>
```

Useful for:

* Less frequently used sections
* Admin panels
* Advanced features
* Archives

### With Conditional Items

```tsx
import { WithGuard } from "@tailor-platform/app-shell";

const isAdmin = ({ context }) => (context.currentUser?.role === "admin" ? pass() : hidden());

<SidebarGroup title="Settings" icon={<Settings />}>
  <SidebarItem to="/settings/profile" />
  <SidebarItem to="/settings/notifications" />

  <WithGuard guards={[isAdmin]}>
    <SidebarItem to="/settings/users" />
    <SidebarItem to="/settings/permissions" />
  </WithGuard>
</SidebarGroup>;
```

### With External Links

```tsx
import { HelpCircle, FileText, ExternalLink } from "lucide-react";

<SidebarGroup title="Help" icon={<HelpCircle />}>
  <SidebarItem to="/help/faq" />
  <SidebarItem to="https://docs.example.com" title="Documentation" icon={<FileText />} external />
  <SidebarItem to="https://support.example.com" title="Support" icon={<ExternalLink />} external />
</SidebarGroup>;
```

### With Custom Separator

```tsx
<DefaultSidebar>
  <SidebarGroup title="Main" icon={<Home />}>
    <SidebarItem to="/dashboard" />
    <SidebarItem to="/analytics" />
  </SidebarGroup>

  <SidebarSeparator />

  <SidebarGroup title="Management" icon={<Settings />}>
    <SidebarItem to="/products" />
    <SidebarItem to="/orders" />
  </SidebarGroup>
</DefaultSidebar>
```

## Visual Structure

```
▼ Products                    ← Group header (clickable if `to` provided)
  • All Products              ← SidebarItem
  • Categories                ← SidebarItem
  ▼ Archives                  ← Nested SidebarGroup
    • 2024                    ← SidebarItem
    • 2023                    ← SidebarItem
```

When collapsed:

```
▶ Products                    ← Collapsed group
```

## Active State

When a child item is active, the group:

* Remains expanded (if it was collapsed)
* Group title gets highlighted (if `to` is provided and matches current route)

```tsx
// User is on /settings/profile
<SidebarGroup title="Settings" to="/settings">
  <SidebarItem to="/settings/profile" /> {/* Active */}
  <SidebarItem to="/settings/security" />
</SidebarGroup>

// Group title is highlighted (matches /settings prefix)
// /settings/profile item is highlighted
```

## Styling

### Custom Icon Styling

```tsx
<SidebarGroup title="Products" icon={<Package className="astw:text-blue-500" />}>
  {/* ... */}
</SidebarGroup>
```

### Group Title Styling

The title styling is controlled by AppShell's theme. You can customize via CSS:

```css
/* Custom group header styling */
.astw:sidebar-group-title {
  font-weight: 600;
  font-size: 0.875rem;
}
```

## Accessibility

* Semantic HTML structure
* ARIA labels for expand/collapse state
* Keyboard navigation (Tab, Enter, Space)
* Screen reader announcements for state changes
* Proper heading hierarchy

## Best Practices

### Do:

* ✅ Group related items logically
* ✅ Use clear, descriptive group titles
* ✅ Provide icons for visual recognition
* ✅ Start collapsed for less-used sections
* ✅ Keep groups shallow (max 2 levels of nesting)

### Don't:

* ❌ Create groups with only 1 item (use SidebarItem directly)
* ❌ Nest more than 2 levels deep (hard to navigate)
* ❌ Use very long group titles (keep to 1-2 words)
* ❌ Mix unrelated items in same group
* ❌ Forget icons (helps with visual scanning)

## When to Use

**Use SidebarGroup when:**

* You have 3+ related navigation items
* Items share a common category or theme
* You want to organize a large navigation menu
* Users need to focus on specific sections

**Use SidebarItem directly when:**

* You have standalone top-level navigation
* Items don't fit into logical groups
* You want a flat, simple navigation structure

## Comparison

| Feature         | SidebarGroup           | SidebarItem     |
| --------------- | ---------------------- | --------------- |
| **Purpose**     | Organize related items | Individual link |
| **Collapsible** | ✅ Yes                 | ❌ No           |
| **Contains**    | Multiple items         | Self (link)     |
| **Icon**        | Group identifier       | Link identifier |
| **Clickable**   | Optional (`to` prop)   | Always          |
| **Nesting**     | Can contain groups     | Leaf node       |

## TypeScript

Full type safety:

```typescript
import { type SidebarGroupProps } from "@tailor-platform/app-shell";

const groupProps: SidebarGroupProps = {
  title: "Products",
  icon: <Package />,
  to: "/products",
  defaultOpen: true,
  children: <SidebarItem to="/products/all" />,
};
```

## Troubleshooting

### Group not expanding/collapsing

**Problem:** Clicking chevron doesn't toggle group

**Solution:**

1. Check browser console for errors
2. Ensure children are valid React elements
3. Verify AppShell is properly configured

### Title not clickable

**Problem:** Clicking title doesn't navigate

**Solution:** Add the `to` prop:

```tsx
<SidebarGroup title="Settings" to="/settings">
  {/* ... */}
</SidebarGroup>
```

Without `to`, only the chevron is clickable (for expand/collapse).

### Icon not showing

**Problem:** Icon doesn't appear

**Solution:**

1. Check that icon is a valid React element
2. Import the icon correctly
3. Verify icon library is installed

## Related Components

* [SidebarItem](sidebar-item) - Individual navigation items
* [DefaultSidebar](sidebar-layout) - Container for groups
* [WithGuard](with-guard) - Conditional rendering

## Related Concepts

* [Sidebar Navigation](../concepts/sidebar-navigation) - Sidebar customization guide
* [Internationalization](../api/define-i18n-labels) - Multi-language support

## API Reference

* [defineI18nLabels](../api/define-i18n-labels) - Internationalization helper

---

---
url: https://docs.tailor.tech/app-shell/components/sidebar-item.md
description: >-
  Individual navigation item for customizing sidebar with icons, active states,
  and external links
---

# SidebarItem

`SidebarItem` represents an individual navigation link in the sidebar. It automatically resolves titles and icons from resource definitions and provides active state highlighting.

## Import

```tsx
import { SidebarItem } from "@tailor-platform/app-shell";
```

## Basic Usage

```tsx
import { DefaultSidebar, SidebarItem } from "@tailor-platform/app-shell";

<DefaultSidebar>
  <SidebarItem to="/dashboard" />
  <SidebarItem to="/products" />
  <SidebarItem to="/orders" />
</DefaultSidebar>;
```

When you only provide `to`, the title and icon are automatically resolved from the matching resource's `meta` property.

## Props

| Prop          | Type                   | Default       | Description                                    |
| ------------- | ---------------------- | ------------- | ---------------------------------------------- |
| `to`          | `string`               | **Required**  | Target URL (internal or external)              |
| `title`       | `string`               | Auto-resolved | Override the display title                     |
| `icon`        | `React.ReactNode`      | Auto-resolved | Override the icon                              |
| `external`    | `boolean`              | `false`       | Opens link in new tab with external icon       |
| `activeMatch` | `"exact" \| "prefix"`  | `"prefix"`    | How to match the current path for active state |
| `render`      | `(props) => ReactNode` | -             | Custom render function for full control        |

## Auto-Resolution

### Title Resolution

The title is automatically resolved from the resource's `meta.title`:

```tsx
// In your module definition
const dashboardModule = defineModule({
  path: "dashboard",
  component: DashboardPage,
  meta: {
    title: "Dashboard", // ← Automatically used
  },
});

// In sidebar - no title needed!
<SidebarItem to="/dashboard" />;
// Renders as: Dashboard
```

For the root path (`/` or `""`), when no `meta.title` is set, the title falls back to the localized string `"Home"` (English) or `"ホーム"` (Japanese).

### Icon Resolution

Icons are resolved from the module's `meta.icon`:

```tsx
import { Home, Package } from "lucide-react";

const modules = [
  defineModule({
    path: "dashboard",
    meta: {
      title: "Dashboard",
      icon: <Home />, // ← Automatically used in sidebar
    },
  }),
  defineModule({
    path: "products",
    meta: {
      title: "Products",
      icon: <Package />,
    },
  }),
];

<DefaultSidebar>
  <SidebarItem to="/dashboard" /> {/* Shows Home icon */}
  <SidebarItem to="/products" /> {/* Shows Package icon */}
</DefaultSidebar>;
```

## Manual Override

### Override Title

```tsx
<SidebarItem
  to="/dashboard"
  title="My Dashboard" // Override auto-resolved title
/>
```

### Override Icon

```tsx
import { Home } from "lucide-react";

<SidebarItem
  to="/dashboard"
  icon={<Home />} // Override auto-resolved icon
/>;
```

### Both Title and Icon

```tsx
import { Settings } from "lucide-react";

<SidebarItem to="/settings" title="Settings" icon={<Settings />} />;
```

## External Links

Open links in a new tab with an external link icon:

```tsx
import { ExternalLink } from "lucide-react";

<SidebarItem
  to="https://docs.example.com"
  title="Documentation"
  icon={<ExternalLink />}
  external
/>;
```

The external link icon is automatically added to the end of the item.

## Active State Matching

Control how the active state is determined:

### Prefix Matching (Default)

Highlights when the current path **starts with** the `to` path:

```tsx
<SidebarItem to="/products" activeMatch="prefix" />

// Active when:
// - /products
// - /products/123
// - /products/categories
```

### Exact Matching

Highlights only when the current path **exactly matches** the `to` path:

```tsx
<SidebarItem to="/products" activeMatch="exact" />

// Active when:
// - /products (only)

// NOT active when:
// - /products/123
// - /products/categories
```

## Custom Rendering

For full control, use the `render` prop:

```tsx
<SidebarItem
  to="/notifications"
  render={({ title, icon, isActive }) => (
    <div className="astw:flex astw:items-center astw:gap-2">
      {icon}
      <span>{title}</span>
      {isActive && <Badge>New</Badge>}
      <Badge variant="error">5</Badge>
    </div>
  )}
/>
```

The render function receives:

```typescript
type SidebarItemRenderProps = {
  title: string; // Auto-resolved or overridden
  url: string; // The `to` prop value
  icon?: ReactNode; // Auto-resolved or overridden
  isActive: boolean; // Whether this item matches the current route
};
```

## Examples

### Basic Sidebar

```tsx
<DefaultSidebar>
  <SidebarItem to="/dashboard" />
  <SidebarItem to="/products" />
  <SidebarItem to="/orders" />
  <SidebarItem to="/customers" />
</DefaultSidebar>
```

### With Manual Overrides

```tsx
import { Home, Package, ShoppingCart, Users } from "lucide-react";

<DefaultSidebar>
  <SidebarItem to="/" title="Home" icon={<Home />} />
  <SidebarItem to="/products" title="Products" icon={<Package />} />
  <SidebarItem to="/orders" title="Orders" icon={<ShoppingCart />} />
  <SidebarItem to="/customers" title="Customers" icon={<Users />} />
</DefaultSidebar>;
```

### With External Links

```tsx
import { HelpCircle, FileText, ExternalLink } from "lucide-react";

<DefaultSidebar>
  <SidebarItem to="/dashboard" />
  <SidebarItem to="/products" />

  <SidebarSeparator />

  <SidebarItem to="https://docs.example.com" title="Documentation" icon={<FileText />} external />
  <SidebarItem to="https://support.example.com" title="Support" icon={<HelpCircle />} external />
</DefaultSidebar>;
```

### With Notification Badge

```tsx
<SidebarItem
  to="/notifications"
  render={({ title, icon, isActive }) => (
    <>
      {icon}
      <span>{title}</span>
      <Badge variant="error">12</Badge>
    </>
  )}
/>
```

### With Active Indicator

```tsx
<SidebarItem
  to="/messages"
  render={({ title, icon, isActive }) => (
    <>
      {icon}
      <span className={isActive ? "astw:font-bold" : undefined}>{title}</span>
      {isActive && <span className="astw:ml-auto">•</span>}
    </>
  )}
/>
```

### Exact Match for Root

```tsx
<DefaultSidebar>
  <SidebarItem to="/" activeMatch="exact" />
  <SidebarItem to="/dashboard" />
  <SidebarItem to="/products" />
</DefaultSidebar>
```

Without `activeMatch="exact"`, the root item would be active on all pages since every path starts with `/`.

### Conditional Rendering with Guards

```tsx
import { WithGuard } from "@tailor-platform/app-shell";

const isAdmin = ({ context }) => (context.currentUser?.role === "admin" ? pass() : hidden());

<DefaultSidebar>
  <SidebarItem to="/dashboard" />
  <SidebarItem to="/products" />

  <WithGuard guards={[isAdmin]}>
    <SidebarItem to="/admin" title="Admin Panel" />
  </WithGuard>
</DefaultSidebar>;
```

### In SidebarGroup

```tsx
import { SidebarGroup, SidebarItem } from "@tailor-platform/app-shell";
import { Package } from "lucide-react";

<SidebarGroup title="Products" icon={<Package />}>
  <SidebarItem to="/products/all" />
  <SidebarItem to="/products/categories" />
  <SidebarItem to="/products/brands" />
</SidebarGroup>;
```

## Styling

### Active State

Active items automatically receive the `astw:bg-sidebar-accent` background class:

```css
/* Active item styling (automatic) */
.astw:bg-sidebar-accent {
  background: var(--sidebar-accent);
  font-weight: 500;
}
```

### Custom Styling

Add custom classes via the `render` prop:

```tsx
<SidebarItem
  to="/special"
  render={({ title, icon, isActive }) => (
    <div
      className={cn(
        "astw:flex astw:items-center astw:gap-2",
        isActive && "astw:border-l-4 astw:border-primary",
      )}
    >
      {icon}
      {title}
    </div>
  )}
/>
```

## Accessibility

* Semantic `<a>` tag for links
* Proper `href` attribute
* Active state announced to screen readers
* External links open in new tab with `rel="noopener noreferrer"`
* Keyboard navigation support (Tab, Enter)

## Best Practices

### Do:

* ✅ Let AppShell auto-resolve title/icon when possible
* ✅ Use `external` for links outside your app
* ✅ Use `exact` match for root routes
* ✅ Group related items with `SidebarGroup`
* ✅ Keep item labels short (1-2 words)

### Don't:

* ❌ Hardcode titles that exist in resource meta
* ❌ Forget `external` for external links
* ❌ Use prefix match for root route (`/`)
* ❌ Mix internal and external links without visual distinction
* ❌ Create deeply nested navigation (use breadcrumbs instead)

## Comparison: Auto vs Manual

| Aspect          | Auto-Resolved              | Manual Override              |
| --------------- | -------------------------- | ---------------------------- |
| **Title**       | From resource `meta.title` | Specify `title` prop         |
| **Icon**        | From module `meta.icon`    | Specify `icon` prop          |
| **Effort**      | Less code, DRY             | More flexible                |
| **Maintenance** | Single source of truth     | Must update in 2 places      |
| **Use When**    | Standard navigation        | Custom items, external links |

## TypeScript

Full type safety:

```typescript
import { type SidebarItemProps, type SidebarItemRenderProps } from "@tailor-platform/app-shell";

// Type-safe props
const itemProps: SidebarItemProps = {
  to: "/dashboard",
  title: "Dashboard",
  activeMatch: "prefix",
};

// Type-safe render function
const customRender = (props: SidebarItemRenderProps) => {
  // props.title, props.icon, props.isActive are all typed
  return <div>{props.title}</div>;
};
```

## Troubleshooting

### Title/Icon not showing

**Problem:** SidebarItem doesn't display title or icon

**Solutions:**

1. Check that the resource has `meta.title` defined
2. Verify the `to` prop matches the resource path exactly
3. Ensure the module has `meta.icon` for icon display
4. Try manually specifying `title` and `icon` props

### Active state not working

**Problem:** Item isn't highlighted when on that page

**Solutions:**

1. Check that the `to` prop matches the current route
2. Use `exact` match for root routes (`/`)
3. Use `prefix` match for parent routes with children
4. Verify you're using React Router's `<Link>` correctly

### External link not opening in new tab

**Problem:** External link opens in same tab

**Solution:** Add `external` prop:

```tsx
<SidebarItem to="https://..." external />
```

## Related Components

* [SidebarGroup](sidebar-group) - Group multiple items
* [DefaultSidebar](sidebar-layout) - Container for sidebar items
* [WithGuard](with-guard) - Conditional rendering

## Related Concepts

* [Sidebar Navigation](../concepts/sidebar-navigation) - Sidebar customization guide
* [Modules and Resources](../concepts/modules-and-resources) - Define routes and meta

## API Reference

* [usePageMeta](../api/use-page-meta) - Hook for resolving page metadata

---

---
url: https://docs.tailor.tech/app-shell/components/sidebar-layout.md
description: >-
  The default layout component with sidebar navigation, breadcrumbs, and theme
  toggle
---

# SidebarLayout

`SidebarLayout` is the default layout component that provides a responsive sidebar navigation, breadcrumb trail, and theme toggle. It's designed to work seamlessly with AppShell's module system.

## Import

```tsx
import { SidebarLayout } from "@tailor-platform/app-shell";
```

## Basic Usage

```tsx
import { AppShell, SidebarLayout } from "@tailor-platform/app-shell";

function App() {
  return (
    <AppShell modules={modules}>
      <SidebarLayout />
    </AppShell>
  );
}
```

This gives you:

* ✅ Responsive sidebar with auto-generated navigation from modules
* ✅ Breadcrumb navigation
* ✅ Theme toggle (light/dark mode)
* ✅ Mobile-friendly collapsible sidebar

## Props

### children

* **Type:** `(props: { Outlet: () => React.ReactNode }) => React.ReactNode` (optional)
* **Description:** Custom content renderer for adding headers, footers, or wrapping the outlet

```tsx
<SidebarLayout>
  {({ Outlet }) => (
    <>
      <CustomHeader />
      <Outlet />
      <CustomFooter />
    </>
  )}
</SidebarLayout>
```

The `Outlet` component renders your current route's component.

### sidebar

* **Type:** `React.ReactNode` (optional)
* **Default:** `<SidebarLayout.DefaultSidebar />`
* **Description:** Replaces the whole sidebar region. Omit it for the built-in sidebar.

```tsx
import { SidebarLayout, SidebarItem } from "@tailor-platform/app-shell";

<SidebarLayout
  sidebar={
    <SidebarLayout.DefaultSidebar>
      <SidebarItem label="Custom Link" href="/custom" />
    </SidebarLayout.DefaultSidebar>
  }
/>;
```

> `SidebarLayout.DefaultSidebar` is the same component as the top-level
> `DefaultSidebar` export (kept for backwards compatibility). The namespaced form
> is preferred for discoverability — it pairs with
> [`SidebarLayout.DefaultHeader`](#header).

### defaultOpen

* **Type:** `boolean` (optional)
* **Default:** `true`
* **Description:** Whether the sidebar is open by default on desktop. Has no effect when `collapsible` is `false`.

```tsx
// Sidebar closed by default on desktop
<SidebarLayout defaultOpen={false} />
```

### collapsible

* **Type:** `boolean` (optional)
* **Default:** `true`
* **Description:** Whether the sidebar can be collapsed. When set to `false`, the sidebar is always visible and toggle buttons are hidden. `defaultOpen` is ignored when this is `false`.

```tsx
// Non-collapsible sidebar (always visible, toggle buttons hidden)
<SidebarLayout collapsible={false} />
```

### header

* **Type:** `React.ReactNode` (optional)
* **Default:** `<SidebarLayout.DefaultHeader />`
* **Description:** Replaces the whole top-bar region. Omit it for the built-in header.

Like `sidebar`, `header` is a full-region slot. There are three levels of customization:

**1. Default** — omit `header` entirely:

```tsx
<SidebarLayout />
```

**2. Extend the built-in header** — pass `SidebarLayout.DefaultHeader` and use its
`actions` slot. This is the common case (e.g. adding a notification bell) and
keeps the trigger + breadcrumb without reconstructing them:

```tsx
import { SidebarLayout, AppearanceSwitcher, Button } from "@tailor-platform/app-shell";
import { BellIcon } from "lucide-react";

<SidebarLayout
  header={
    <SidebarLayout.DefaultHeader
      actions={[
        <Button key="bell" variant="outline" size="icon" aria-label="Notifications">
          <BellIcon />
        </Button>,
        // `actions` REPLACES the default right-hand cluster, so include the
        // appearance switcher explicitly to keep it.
        <AppearanceSwitcher key="appearance" />,
      ]}
    />
  }
/>;
```

**3. Replace it entirely** — supply your own node:

```tsx
<SidebarLayout header={<MyCustomHeader />} />
```

#### `SidebarLayout.DefaultHeader`

The built-in header: sidebar trigger + breadcrumb on the left, and the `actions`
cluster on the right.

* **`actions`** — `React.ReactNode | React.ReactNode[]` (optional). The entire
  right-hand cluster, laid out in a horizontal, vertically-centered row with
  consistent spacing.
  * **Default:** `[<AppearanceSwitcher />]` — so out-of-the-box behavior is
    unchanged.
  * ⚠️ **`actions` replaces the whole right-hand cluster, including the
    appearance switcher.** If you pass your own actions and still want the
    switcher, include `<AppearanceSwitcher />` in the array (it is a public
    export). `actions={[]}` renders an empty right side.

This is the supported extension point for the top bar — it replaces fragile
workarounds that queried the header DOM and injected a React portal.

## Features

### Responsive Sidebar

The sidebar automatically adapts to different screen sizes:

* **Desktop** (≥ 768px): Full sidebar visible by default
* **Tablet/Mobile** (< 768px): Collapsible sidebar with hamburger menu

Users can toggle the sidebar using:

* Hamburger menu button (top left)
* Keyboard shortcut: `Cmd + B` / `Ctrl + B`

### Breadcrumb Navigation

Breadcrumbs are automatically generated based on the current route:

```
Dashboard > Products > Product Details
```

Breadcrumbs update automatically as users navigate through your application.

### Theme Toggle

The built-in header renders an [`AppearanceSwitcher`](appearance-switcher) — a palette-icon button whose dropdown switches the color theme (persisted to localStorage). To add your own controls (notifications, user menu, etc.) alongside it, pass [`SidebarLayout.DefaultHeader`](#header) with an `actions` array that includes `<AppearanceSwitcher />`.

## Customization Examples

### Custom Header and Footer

```tsx
import { SidebarLayout } from "@tailor-platform/app-shell";

const CustomHeader = () => (
  <div className="astw:bg-blue-500 astw:text-white astw:p-4">
    <h2>Welcome to My App</h2>
  </div>
);

const CustomFooter = () => (
  <footer className="astw:p-4 astw:text-sm astw:text-gray-600">© 2026 My Company</footer>
);

function App() {
  return (
    <AppShell modules={modules}>
      <SidebarLayout>
        {({ Outlet }) => (
          <div className="astw:flex astw:flex-col astw:h-full">
            <CustomHeader />
            <main className="astw:flex-1 astw:overflow-auto">
              <Outlet />
            </main>
            <CustomFooter />
          </div>
        )}
      </SidebarLayout>
    </AppShell>
  );
}
```

### Custom Sidebar

```tsx
import {
  SidebarLayout,
  DefaultSidebar,
  SidebarItem,
  SidebarGroup,
  SidebarSeparator,
} from "@tailor-platform/app-shell";
import { HelpCircle, ExternalLink } from "lucide-react";

function App() {
  return (
    <AppShell modules={modules}>
      <SidebarLayout
        sidebar={
          <DefaultSidebar>
            {/* Auto-generated navigation from modules */}

            {/* Add custom items */}
            <SidebarSeparator />
            <SidebarGroup label="Help">
              <SidebarItem
                label="Documentation"
                icon={<HelpCircle />}
                href="https://docs.example.com"
                external
              />
              <SidebarItem
                label="Support"
                icon={<ExternalLink />}
                href="https://support.example.com"
                external
              />
            </SidebarGroup>
          </DefaultSidebar>
        }
      />
    </AppShell>
  );
}
```

### Wrapping Content in a Container

```tsx
<SidebarLayout>
  {({ Outlet }) => (
    <div className="astw:container astw:mx-auto astw:p-6 astw:max-w-7xl">
      <Outlet />
    </div>
  )}
</SidebarLayout>
```

### Adding a Global Banner

```tsx
<SidebarLayout>
  {({ Outlet }) => (
    <>
      <div className="astw:bg-yellow-100 astw:border-b astw:border-yellow-200 astw:p-3 astw:text-center">
        <p className="astw:text-sm">🎉 New features available! Check out our latest updates.</p>
      </div>
      <Outlet />
    </>
  )}
</SidebarLayout>
```

## Layout Structure

The SidebarLayout component creates the following structure:

```
┌─────────────────────────────────────────────┐
│ Sidebar          │ Header (Breadcrumbs +   │
│                  │         Theme Toggle)    │
│ - Dashboard      ├─────────────────────────┤
│ - Products       │                         │
│ - Orders         │                         │
│                  │      Page Content       │
│ [Settings ▼]     │        (Outlet)         │
│                  │                         │
│                  │                         │
└─────────────────────────────────────────────┘
```

Mobile view (sidebar collapsed):

```
┌─────────────────────────────────┐
│ [☰] Breadcrumbs     [Theme]     │
├─────────────────────────────────┤
│                                 │
│         Page Content            │
│           (Outlet)              │
│                                 │
└─────────────────────────────────┘
```

## Accessing the content scroll container

The AppShell is viewport-bounded (`h-svh`), so the **document itself does not scroll** — the content area does. Code that previously relied on `window`/document scroll (reading `window.scrollY`, listening to `window`'s `scroll` event, `window.scrollTo(...)`, or an `IntersectionObserver` with the default viewport root) should target the content scroll container instead.

Use the `useAppShellScrollContainer()` hook to get a ref to that element from any page:

```tsx
import { useAppShellScrollContainer } from "@tailor-platform/app-shell";
import { useEffect, useState } from "react";

function ReadingProgress() {
  const scrollRef = useAppShellScrollContainer();
  const [progress, setProgress] = useState(0);

  useEffect(() => {
    const el = scrollRef.current;
    if (!el) return;
    const onScroll = () => {
      const max = el.scrollHeight - el.clientHeight;
      setProgress(max > 0 ? el.scrollTop / max : 0);
    };
    onScroll();
    el.addEventListener("scroll", onScroll, { passive: true });
    return () => el.removeEventListener("scroll", onScroll);
  }, [scrollRef]);

  return <progress value={progress} />;
}
```

The same element handles imperative scrolling (`scrollRef.current?.scrollTo({ top: 0, behavior: "smooth" })`) and works as an `IntersectionObserver` root (`new IntersectionObserver(cb, { root: scrollRef.current })`).

Notes:

* The element mounts with the layout, above your page, so read `ref.current` inside an effect — it is populated by the time effects run, not during render.
* On a [`<Layout fill>`](layout.md#fill-mode) page this element does **not** scroll; its children (e.g. a `DataTable`) manage their own scrolling.
* Outside a `SidebarLayout` (a fully custom layout) the returned ref's `current` is always `null` — such layouts own their own scroll region.
* For non-React access (CSS, tests, plain DOM) the container also carries a `data-appshell-scroll-container` attribute: `document.querySelector("[data-appshell-scroll-container]")`.

## Styling

The sidebar and layout use Tailwind CSS classes prefixed with `astw:` to avoid conflicts with your application styles.

To customize the appearance, you can:

1. **Override CSS variables** in your theme.css:

   ```css
   :root {
     --sidebar-width: 280px; /* Default: 256px */
   }
   ```

2. **Use custom sidebar component** with your own styling

3. **Wrap Outlet** with container classes as shown in examples above

## Accessibility

SidebarLayout includes built-in accessibility features:

* **Keyboard navigation**: Navigate sidebar items with arrow keys
* **ARIA labels**: Proper labels for screen readers
* **Focus management**: Focus trap when sidebar is open on mobile
* **Responsive**: Works with keyboard and touch inputs

## Related Components

* [AppShell](app-shell) - Root component
* [DefaultHeader](default-header) - Built-in header (`SidebarLayout.DefaultHeader`)
* [DefaultSidebar](default-sidebar) - Built-in sidebar (`SidebarLayout.DefaultSidebar`)
* [AppearanceSwitcher](appearance-switcher) - Color-theme dropdown, composable into header `actions`
* [SidebarItem](sidebar-item) - Individual sidebar navigation items
* [SidebarGroup](sidebar-group) - Group sidebar items

## Related Concepts

* [Modules and Resources](../concepts/modules-and-resources) - How navigation is generated
* [Routing and Navigation](../concepts/routing-navigation) - Navigation between pages
* [Styling and Theming](../concepts/styling-theming) - Customize appearance

## API Reference

* [useTheme](../api/use-theme) - Access theme context

---

---
url: https://docs.tailor.tech/app-shell/components/table.md
description: Semantic HTML table with pre-styled sub-components
---

# Table

The `Table` component provides a set of pre-styled, semantic HTML table sub-components. It wraps a standard `<table>` element in a horizontally scrollable container.

[Live preview in the UI Catalogue →](https://ui.tailor.tech/components/table)

## Import

```tsx
import { Table } from "@tailor-platform/app-shell";
```

## Basic Usage

```tsx
<Table.Root>
  <Table.Header>
    <Table.Row>
      <Table.Head>Name</Table.Head>
      <Table.Head>Email</Table.Head>
      <Table.Head>Role</Table.Head>
    </Table.Row>
  </Table.Header>
  <Table.Body>
    <Table.Row>
      <Table.Cell>Alice</Table.Cell>
      <Table.Cell>alice@example.com</Table.Cell>
      <Table.Cell>Admin</Table.Cell>
    </Table.Row>
  </Table.Body>
</Table.Root>
```

## Sub-components

| Sub-component   | HTML element | Description                            |
| --------------- | ------------ | -------------------------------------- |
| `Table.Root`    | `<table>`    | Root element with scrollable container |
| `Table.Header`  | `<thead>`    | Table header section                   |
| `Table.Body`    | `<tbody>`    | Table body section                     |
| `Table.Footer`  | `<tfoot>`    | Table footer section                   |
| `Table.Row`     | `<tr>`       | Table row (hover and selection styles) |
| `Table.Head`    | `<th>`       | Header cell                            |
| `Table.Cell`    | `<td>`       | Data cell                              |
| `Table.Caption` | `<caption>`  | Table caption                          |

## Props

### Table.Root Props

| Prop                 | Type                        | Default | Description                                                       |
| -------------------- | --------------------------- | ------- | ----------------------------------------------------------------- |
| `className`          | `string`                    | -       | Additional CSS classes for the `<table>` element                  |
| `containerClassName` | `string`                    | -       | Additional CSS classes for the outer scrollable `<div>` container |
| `containerRef`       | `React.Ref<HTMLDivElement>` | -       | Ref forwarded to the outer scrollable `<div>` container           |

All other standard HTML `<table>` props are accepted.

All other sub-components (`Table.Header`, `Table.Body`, `Table.Footer`, `Table.Row`, `Table.Head`, `Table.Cell`, `Table.Caption`) accept `className` and their corresponding standard HTML element props.

`Table.Head` and `Table.Cell` also accept `align?: "left" | "center" | "right"` for semantic text alignment without relying on utility-class overrides.

## Examples

### With Footer

```tsx
<Table.Root>
  <Table.Header>
    <Table.Row>
      <Table.Head>Product</Table.Head>
      <Table.Head>Qty</Table.Head>
      <Table.Head>Price</Table.Head>
    </Table.Row>
  </Table.Header>
  <Table.Body>
    <Table.Row>
      <Table.Cell>Widget A</Table.Cell>
      <Table.Cell>10</Table.Cell>
      <Table.Cell>$100.00</Table.Cell>
    </Table.Row>
    <Table.Row>
      <Table.Cell>Widget B</Table.Cell>
      <Table.Cell>5</Table.Cell>
      <Table.Cell>$75.00</Table.Cell>
    </Table.Row>
  </Table.Body>
  <Table.Footer>
    <Table.Row>
      <Table.Cell colSpan={2}>Total</Table.Cell>
      <Table.Cell>$175.00</Table.Cell>
    </Table.Row>
  </Table.Footer>
</Table.Root>
```

### With Caption

```tsx
<Table.Root>
  <Table.Caption>Order line items</Table.Caption>
  <Table.Header>
    <Table.Row>
      <Table.Head>Item</Table.Head>
      <Table.Head>Status</Table.Head>
    </Table.Row>
  </Table.Header>
  <Table.Body>
    <Table.Row>
      <Table.Cell>Item 1</Table.Cell>
      <Table.Cell>Shipped</Table.Cell>
    </Table.Row>
  </Table.Body>
</Table.Root>
```

### Right-aligned numeric columns

```tsx
<Table.Root>
  <Table.Header>
    <Table.Row>
      <Table.Head>Item</Table.Head>
      <Table.Head align="right">Amount</Table.Head>
    </Table.Row>
  </Table.Header>
  <Table.Body>
    <Table.Row>
      <Table.Cell>Widget A</Table.Cell>
      <Table.Cell align="right">123</Table.Cell>
    </Table.Row>
  </Table.Body>
</Table.Root>
```

### Center-aligned status column

```tsx
<Table.Root>
  <Table.Header>
    <Table.Row>
      <Table.Head>Item</Table.Head>
      <Table.Head align="center">Status</Table.Head>
    </Table.Row>
  </Table.Header>
  <Table.Body>
    <Table.Row>
      <Table.Cell>Widget A</Table.Cell>
      <Table.Cell align="center">Active</Table.Cell>
    </Table.Row>
  </Table.Body>
</Table.Root>
```

### Constrained Height with Scroll

```tsx
<Table.Root containerClassName="astw:max-h-64 astw:overflow-y-auto">
  <Table.Header>
    <Table.Row>
      <Table.Head>Name</Table.Head>
    </Table.Row>
  </Table.Header>
  <Table.Body>
    {items.map((item) => (
      <Table.Row key={item.id}>
        <Table.Cell>{item.name}</Table.Cell>
      </Table.Row>
    ))}
  </Table.Body>
</Table.Root>
```

## Related Components

* [Badge](badge) - Display status inside table cells
* [Layout](layout) - Place tables inside page layouts

---

---
url: https://docs.tailor.tech/app-shell/components/tabs.md
description: Tab navigation with a compound component API
---

# Tabs

The `Tabs` component provides tab-based navigation for toggling between related panels on the same page. It is backed by Base UI's Tabs primitive.

[Live preview in the UI Catalogue →](https://ui.tailor.tech/components/tabs)

## Import

```tsx
import { Tabs } from "@tailor-platform/app-shell";
```

## Basic Usage

```tsx
<Tabs.Root defaultValue="overview">
  <Tabs.List>
    <Tabs.Tab value="overview">Overview</Tabs.Tab>
    <Tabs.Tab value="projects">Projects</Tabs.Tab>
    <Tabs.Tab value="account">Account</Tabs.Tab>
  </Tabs.List>
  <Tabs.Panel value="overview">Overview content</Tabs.Panel>
  <Tabs.Panel value="projects">Projects content</Tabs.Panel>
  <Tabs.Panel value="account">Account content</Tabs.Panel>
</Tabs.Root>
```

## Sub-components

| Sub-component | Description                                                    |
| ------------- | -------------------------------------------------------------- |
| `Tabs.Root`   | Manages tab selection state                                    |
| `Tabs.List`   | Groups the individual tab buttons                              |
| `Tabs.Tab`    | An interactive tab button that toggles the corresponding panel |
| `Tabs.Panel`  | A panel displayed when the corresponding tab is active         |

## Props

### Tabs.Root Props

| Prop            | Type                                | Default     | Description                                                   |
| --------------- | ----------------------------------- | ----------- | ------------------------------------------------------------- |
| `defaultValue`  | `Tabs.Tab.Value`                    | `0`         | Initial active tab value (uncontrolled)                       |
| `value`         | `Tabs.Tab.Value`                    | -           | Controlled active tab value                                   |
| `onValueChange` | `(value: any) => void`              | -           | Callback when the active tab changes                          |
| `variant`       | `'default' \| 'line' \| 'capsule'`  | `'default'` | Visual style of the tabs                                      |
| `size`          | `'xs' \| 'sm' \| 'default' \| 'lg'` | `'default'` | Minimum size (`capsule` only) — mirrors Button's height tiers |
| `className`     | `string`                            | -           | Additional CSS classes for root                               |
| `children`      | `React.ReactNode`                   | -           | Tabs sub-components                                           |

### Tabs.List Props

Accepts `className` and all standard HTML `<div>` props.

### Tabs.Tab Props

| Prop       | Type             | Default | Description                        |
| ---------- | ---------------- | ------- | ---------------------------------- |
| `value`    | `Tabs.Tab.Value` | -       | **Required.** The value of the tab |
| `disabled` | `boolean`        | -       | Whether the tab is disabled        |

Also accepts `className` and all standard HTML `<button>` props.

### Tabs.Panel Props

| Prop          | Type             | Default | Description                                            |
| ------------- | ---------------- | ------- | ------------------------------------------------------ |
| `value`       | `Tabs.Tab.Value` | -       | **Required.** The value matching the corresponding tab |
| `keepMounted` | `boolean`        | `false` | Whether to keep the panel in the DOM when hidden       |

Also accepts `className` and all standard HTML `<div>` props.

## Controlled Usage

```tsx
const [activeTab, setActiveTab] = useState("overview");

<Tabs.Root value={activeTab} onValueChange={setActiveTab}>
  <Tabs.List>
    <Tabs.Tab value="overview">Overview</Tabs.Tab>
    <Tabs.Tab value="details">Details</Tabs.Tab>
  </Tabs.List>
  <Tabs.Panel value="overview">Overview content</Tabs.Panel>
  <Tabs.Panel value="details">Details content</Tabs.Panel>
</Tabs.Root>;
```

## Examples

### With Disabled Tab

```tsx
<Tabs.Root defaultValue="active">
  <Tabs.List>
    <Tabs.Tab value="active">Active</Tabs.Tab>
    <Tabs.Tab value="pending">Pending</Tabs.Tab>
    <Tabs.Tab value="archived" disabled>
      Archived
    </Tabs.Tab>
  </Tabs.List>
  <Tabs.Panel value="active">Active items</Tabs.Panel>
  <Tabs.Panel value="pending">Pending items</Tabs.Panel>
  <Tabs.Panel value="archived">Archived items</Tabs.Panel>
</Tabs.Root>
```

### Use Icons in Tab

In the `capsule` variant, a tab whose only child is an icon renders **square** —
its `min-width` matches its `min-height` — making it a natural fit for icon-only
view toggles (e.g. table/kanban). Use `size` to align the track with a sibling
`Button`: `size="default"` (36px) matches `Button`'s default height. Unsized
icons default to `16px`, so the square is consistent regardless of the icon.

> **Accessibility:** an icon-only tab has no visible text, so give each one an
> `aria-label`. Without it, screen readers announce an unnamed tab.

```tsx
<Tabs.Root defaultValue="overview" variant="capsule" size="default">
  <Tabs.List>
    <Tabs.Tab value="overview" aria-label="Overview">
      <LayoutDashboardIcon />
    </Tabs.Tab>
    <Tabs.Tab value="projects" aria-label="Projects">
      <FolderKanbanIcon />
    </Tabs.Tab>
    <Tabs.Tab value="settings" aria-label="Settings">
      <SettingsIcon />
    </Tabs.Tab>
  </Tabs.List>
  <Tabs.Panel value="overview">Overview content</Tabs.Panel>
  <Tabs.Panel value="projects">Projects content</Tabs.Panel>
  <Tabs.Panel value="settings">Settings content</Tabs.Panel>
</Tabs.Root>
```

### Sizing the capsule variant

`size` mirrors `Button`'s height tiers, so a capsule can sit flush next to a
button. The value sets a **minimum** height — taller content still grows.

| `size`    | Track height | Matches Button |
| --------- | ------------ | -------------- |
| `xs`      | 28px         | `size="xs"`    |
| `sm`      | 32px         | `size="sm"`    |
| `default` | 36px         | default        |
| `lg`      | 40px         | `size="lg"`    |

---

---
url: https://docs.tailor.tech/app-shell/components/textarea.md
description: >-
  Styled multi-line text input sized by rows, with automatic Field / React Hook
  Form integration
---

# Textarea

The `Textarea` component is a styled multi-line text input. It wraps Base UI's field control rendered as a `<textarea>`, so it works with [`Field`](form) and React Hook Form the same way `Input`, `Checkbox`, and `Select` do — dropped inside a `Field.Root` it inherits label association, `aria-describedby`, `disabled`, and the invalid (error) state automatically.

Unlike `Input`, it has no fixed height: `rows` sets the visible line count (floored at `min-h-16`) and the user can drag the box taller, so long text stays readable instead of scrolling inside a single-line window.

## Import

```tsx
import { Textarea } from "@tailor-platform/app-shell";
```

## Basic Usage

```tsx
<Textarea placeholder="Add a note…" />
```

## Props

Accepts Base UI's field-control props plus the standard HTML `<textarea>` props, minus `cols` and `wrap` — the control is always `w-full`, so `cols` could never affect its width, and every `wrap` value depends on `cols` being set. The most common:

| Prop            | Type                                    | Default | Description                                             |
| --------------- | --------------------------------------- | ------- | ------------------------------------------------------- |
| `value`         | `string`                                | -       | Controlled value.                                       |
| `defaultValue`  | `string`                                | -       | Initial value when uncontrolled.                        |
| `onChange`      | `(event) => void`                       | -       | Native change handler.                                  |
| `onValueChange` | `(value: string, eventDetails) => void` | -       | Called with the next string value.                      |
| `rows`          | `number`                                | -       | Visible line count — the height knob.                   |
| `placeholder`   | `string`                                | -       | Placeholder text.                                       |
| `disabled`      | `boolean`                               | `false` | Disables the control.                                   |
| `required`      | `boolean`                               | `false` | Marks the control required for native/Field validation. |
| `readOnly`      | `boolean`                               | `false` | Renders the value without allowing edits.               |
| `name`          | `string`                                | -       | Field name for native form submission.                  |
| `className`     | `string`                                | -       | Additional CSS classes.                                 |

## Examples

### Controlled

```tsx
const [note, setNote] = useState("");

<Textarea value={note} onChange={(e) => setNote(e.target.value)} placeholder="Add a note…" />;
```

### Height

`rows` sets the visible line count, and the user can drag the box taller for a long value.

`min-h-16` (64px) is a hard floor, so `rows={1}` and `rows={2}` both render at 64px — `rows` only starts moving the height from 3 up. There is no supported way to go below the floor.

```tsx
<Textarea rows={8} placeholder="Paste the incident log…" />
```

> The box does not auto-grow as you type. `field-sizing: content` would do that, but the browser then ignores `rows` — leaving height settable only through a `min-h-*` utility, which a consuming app can't rely on because `astw:` utilities exist only if they were compiled into this package's CSS.

### Disabled

```tsx
<Textarea value="Read-only value" disabled />
```

## Use With Field

Placed inside a `Field.Root`, `Textarea` picks up the field's label, description, and invalid/disabled state automatically — no `error` prop of its own.

```tsx
<Field.Root name="description">
  <Field.Label>Description</Field.Label>
  <Textarea placeholder="What changed?" />
  <Field.Description>Optional — visible to the whole team.</Field.Description>
</Field.Root>
```

## React Hook Form

Drive it with a `Controller`. Spreading `field` wires `value`/`onChange`/`onBlur`, and spreading `fieldState` onto `Field.Root` wires the error/invalid state.

```tsx
import { useForm, Controller } from "react-hook-form";
import { Field, Textarea } from "@tailor-platform/app-shell";

const { control } = useForm({ defaultValues: { description: "" } });

<Controller
  name="description"
  control={control}
  rules={{ required: "Description is required." }}
  render={({ field, fieldState }) => (
    <Field.Root name={field.name} {...fieldState}>
      <Field.Label>Description</Field.Label>
      <Textarea {...field} />
      <Field.Error match={fieldState.invalid}>{fieldState.error?.message}</Field.Error>
    </Field.Root>
  )}
/>;
```

## TypeScript

```typescript
import { type TextareaProps } from "@tailor-platform/app-shell";
```

## Related Components

* [Input](input) - Single-line text input with the same styling and `Field` integration
* [Form](form) - Form root and `Field` composition
* [Button](button) - Pair with a textarea in a composer action row

---

---
url: https://docs.tailor.tech/app-shell/components/timeline.md
description: >-
  Composable primitives for building time-based layouts with axis guides, row
  backgrounds, intervals, and dependency links
---

# Timeline

`Timeline` provides composable primitives for building time-based layouts such as Gantt charts, schedules, and project timelines. It is a compound component with five sub-components: `Root`, `Viewport`, `Row`, `Interval`, and `Link`.

## Import

```tsx
import { Timeline } from "@tailor-platform/app-shell";
```

## Basic Usage

```tsx
import { Timeline } from "@tailor-platform/app-shell";

<Timeline.Root start={0} end={100}>
  <Timeline.Viewport
    axis={{
      guides: [{ at: 0 }, { at: 50 }, { at: 100 }],
      levels: [
        {
          kind: "spans",
          items: [
            { start: 0, end: 50, label: "Phase 1" },
            { start: 50, end: 100, label: "Phase 2" },
          ],
        },
      ],
    }}
  >
    <Timeline.Row height={40}>
      <Timeline.Interval start={10} end={35}>
        <div className="h-full rounded-md bg-primary" />
      </Timeline.Interval>
    </Timeline.Row>
  </Timeline.Viewport>
</Timeline.Root>;
```

## Sub-components

| Sub-component       | Description                                                                    |
| ------------------- | ------------------------------------------------------------------------------ |
| `Timeline.Root`     | Provides the shared time range for all nested timeline primitives              |
| `Timeline.Viewport` | Renders the axis, decorations, scrolling area, and link overlay layer          |
| `Timeline.Row`      | Defines one horizontal lane with a fixed height and optional background        |
| `Timeline.Interval` | Positions content across a time range inside a row                             |
| `Timeline.Link`     | Draws an orthogonal dependency connector between two named `Interval` elements |

## TimeValue

All time position props (`start`, `end`, `at`) accept either a `Date` object or a millisecond-precision number timestamp.

```tsx
// Using Date objects
<Timeline.Root start={new Date("2024-01-01")} end={new Date("2024-12-31")}>

// Using numeric timestamps
<Timeline.Root start={0} end={100}>
```

## Props

### Timeline.Root Props

| Prop        | Type              | Default | Description                                        |
| ----------- | ----------------- | ------- | -------------------------------------------------- |
| `start`     | `Date \| number`  | —       | Inclusive start of the overall timeline range      |
| `end`       | `Date \| number`  | —       | Inclusive end of the overall timeline range        |
| `children`  | `React.ReactNode` | —       | Timeline subtree, usually a `Timeline.Viewport`    |
| `className` | `string`          | —       | Additional CSS classes applied to the root element |
| `style`     | `CSSProperties`   | —       | Inline style applied to the root element           |

### Timeline.Viewport Props

| Prop           | Type                   | Default | Description                                                           |
| -------------- | ---------------------- | ------- | --------------------------------------------------------------------- |
| `children`     | `React.ReactNode`      | —       | Rows and links, in any order                                          |
| `axis`         | `TimelineAxis`         | —       | Axis configuration: guides and stacked header levels                  |
| `decorations`  | `TimelineDecorations`  | —       | Decorative layers: bands and markers                                  |
| `linkDefaults` | `TimelineLinkDefaults` | —       | Shared defaults applied to all `Timeline.Link` nodes in this viewport |
| `canvasWidth`  | `number`               | —       | Fixed canvas width in pixels for horizontally scrollable timelines    |
| `stickyAxis`   | `boolean`              | `false` | Pins the axis to the top of the viewport during vertical scrolling    |
| `className`    | `string`               | —       | Additional CSS classes applied to the scroll viewport                 |
| `style`        | `CSSProperties`        | —       | Inline style applied to the scroll viewport                           |

### Timeline.Row Props

| Prop         | Type                            | Default | Description                                                                                 |
| ------------ | ------------------------------- | ------- | ------------------------------------------------------------------------------------------- |
| `children`   | `React.ReactNode`               | —       | Row contents, typically `Timeline.Interval` elements                                        |
| `height`     | `number`                        | `32`    | Row height in pixels                                                                        |
| `background` | `TimelineRowBackground \| null` | —       | Optional background rendered in a dedicated layer, in front of bands but behind guide lines |
| `className`  | `string`                        | —       | Additional CSS classes applied to the row content container                                 |
| `style`      | `CSSProperties`                 | —       | Inline style applied to the row content container                                           |

### Timeline.Interval Props

| Prop        | Type              | Default | Description                                                         |
| ----------- | ----------------- | ------- | ------------------------------------------------------------------- |
| `start`     | `Date \| number`  | —       | Start of the interval                                               |
| `end`       | `Date \| number`  | —       | End of the interval                                                 |
| `children`  | `React.ReactNode` | —       | Rendered content for the interval                                   |
| `id`        | `string`          | —       | Stable id used by `Timeline.Link` to reference this interval        |
| `insetY`    | `number`          | `0`     | Top and bottom inset in pixels within the row                       |
| `className` | `string`          | —       | Additional CSS classes applied to the positioned interval container |
| `style`     | `CSSProperties`   | —       | Inline style applied to the positioned interval container           |

### Timeline.Link Props

| Prop          | Type                           | Default   | Description                                       |
| ------------- | ------------------------------ | --------- | ------------------------------------------------- |
| `from`        | `string`                       | —         | Source `Timeline.Interval` id                     |
| `to`          | `string`                       | —         | Target `Timeline.Interval` id                     |
| `fromAnchor`  | `"start" \| "center" \| "end"` | `"end"`   | Source anchor used for routing                    |
| `toAnchor`    | `"start" \| "center" \| "end"` | `"start"` | Target anchor used for routing                    |
| `arrow`       | `boolean`                      | —         | Overrides the viewport-level `linkDefaults.arrow` |
| `gap`         | `number`                       | —         | Overrides the viewport-level `linkDefaults.gap`   |
| `strokeWidth` | `number`                       | —         | Optional stroke width for the link path           |
| `className`   | `string`                       | —         | Additional CSS classes applied to the link SVG    |
| `style`       | `CSSProperties`                | —         | Inline style applied to the link SVG              |

## Type Reference

### TimelineAxis

Axis configuration for `Timeline.Viewport`.

| Field       | Type                  | Description                                           |
| ----------- | --------------------- | ----------------------------------------------------- |
| `guides`    | `TimelineGuide[]`     | Vertical boundary lines rendered in the axis and body |
| `levels`    | `TimelineAxisLevel[]` | Stacked header levels rendered above the body         |
| `className` | `string`              | Optional class applied to the axis container          |

### TimelineAxisLevel

A stacked axis level. Has a discriminated union `kind` field:

* `kind: "spans"` — renders labeled time ranges (`TimelineAxisSpan[]`)
* `kind: "ticks"` — renders labeled point-in-time markers (`TimelineAxisTick[]`)

| Field       | Type                                       | Default | Description                                   |
| ----------- | ------------------------------------------ | ------- | --------------------------------------------- |
| `kind`      | `"spans" \| "ticks"`                       | —       | Level rendering mode                          |
| `items`     | `TimelineAxisSpan[] \| TimelineAxisTick[]` | —       | Items to render in this level                 |
| `height`    | `number`                                   | `28`    | Height of this axis level in pixels           |
| `className` | `string`                                   | —       | Optional class applied to the level container |

### TimelineGuide

A vertical guide line rendered in both the axis and the body.

| Field           | Type             | Description                                      |
| --------------- | ---------------- | ------------------------------------------------ |
| `at`            | `Date \| number` | Time position for the guide line                 |
| `key`           | `React.Key`      | Optional stable React key                        |
| `axisClassName` | `string`         | Optional class for the axis portion of the guide |
| `axisStyle`     | `CSSProperties`  | Optional style for the axis portion of the guide |
| `bodyClassName` | `string`         | Optional class for the body portion of the guide |
| `bodyStyle`     | `CSSProperties`  | Optional style for the body portion of the guide |

### TimelineDecorations

Decorative layers rendered by `Timeline.Viewport`.

| Field     | Type               | Description                                       |
| --------- | ------------------ | ------------------------------------------------- |
| `bands`   | `TimelineBand[]`   | Background range highlights rendered behind rows  |
| `markers` | `TimelineMarker[]` | Vertical markers rendered in the axis and/or body |

### TimelineBand

A decorative horizontal band rendered behind rows.

| Field       | Type             | Description                                |
| ----------- | ---------------- | ------------------------------------------ |
| `start`     | `Date \| number` | Start of the band                          |
| `end`       | `Date \| number` | End of the band                            |
| `key`       | `React.Key`      | Optional stable React key                  |
| `color`     | `string`         | Optional background color convenience prop |
| `className` | `string`         | Optional class applied to the band element |
| `style`     | `CSSProperties`  | Optional inline style applied to the band  |

### TimelineMarker

A decorative vertical marker line.

| Field            | Type                         | Default  | Description                                        |
| ---------------- | ---------------------------- | -------- | -------------------------------------------------- |
| `at`             | `Date \| number`             | —        | Time position for the marker                       |
| `key`            | `React.Key`                  | —        | Optional stable React key                          |
| `color`          | `string`                     | —        | Optional line color convenience prop               |
| `label`          | `React.ReactNode`            | —        | Optional marker label                              |
| `placement`      | `"axis" \| "body" \| "both"` | `"body"` | Controls where the marker is rendered              |
| `className`      | `string`                     | —        | Optional class applied to the outer marker wrapper |
| `lineClassName`  | `string`                     | —        | Optional class applied to the marker line          |
| `labelClassName` | `string`                     | —        | Optional class applied to the marker label         |

### TimelineLinkDefaults

Shared defaults for all `Timeline.Link` nodes inside one viewport.

| Field         | Type            | Default        | Description                                              |
| ------------- | --------------- | -------------- | -------------------------------------------------------- |
| `routing`     | `"orthogonal"`  | `"orthogonal"` | Link routing strategy                                    |
| `arrow`       | `boolean`       | `true`         | Whether links end with an arrow marker                   |
| `gap`         | `number`        | `16`           | Horizontal gap in px used when routing out of/into items |
| `strokeWidth` | `number`        | —              | Optional default stroke width for link paths             |
| `className`   | `string`        | —              | Optional class applied to each link SVG                  |
| `style`       | `CSSProperties` | —              | Optional style applied to each link SVG                  |

### TimelineRowBackground

Background content for a row rendered in a dedicated layer (in front of bands, behind guides).

| Field       | Type            | Description                                            |
| ----------- | --------------- | ------------------------------------------------------ |
| `className` | `string`        | Optional class applied to the background layer element |
| `style`     | `CSSProperties` | Optional style applied to the background layer element |

## Examples

### Horizontal Scrolling

Use `canvasWidth` on `Timeline.Viewport` to enable horizontal scrolling:

```tsx
<Timeline.Root start={projectStart} end={projectEnd}>
  <Timeline.Viewport canvasWidth={2400} axis={axis}>
    {rows}
  </Timeline.Viewport>
</Timeline.Root>
```

### Sticky Axis

Pin the axis to the top during vertical scrolling with `stickyAxis`:

```tsx
<Timeline.Root start={0} end={100}>
  <Timeline.Viewport stickyAxis axis={axis}>
    {rows}
  </Timeline.Viewport>
</Timeline.Root>
```

### Dependency Links

Use `id` on `Timeline.Interval` and `Timeline.Link` to draw dependency connectors:

```tsx
<Timeline.Root start={0} end={100}>
  <Timeline.Viewport
    linkDefaults={{ style: { color: "var(--muted-foreground)" }, strokeWidth: 1.5 }}
  >
    <Timeline.Row height={40}>
      <Timeline.Interval id="task-a" start={10} end={40}>
        <div className="h-full rounded-md bg-primary" />
      </Timeline.Interval>
    </Timeline.Row>
    <Timeline.Row height={40}>
      <Timeline.Interval id="task-b" start={50} end={80}>
        <div className="h-full rounded-md bg-secondary" />
      </Timeline.Interval>
    </Timeline.Row>
    <Timeline.Link from="task-a" to="task-b" />
  </Timeline.Viewport>
</Timeline.Root>
```

### Background Bands and Markers

Use `decorations` to add background highlights and vertical marker lines:

```tsx
<Timeline.Viewport
  axis={axis}
  decorations={{
    bands: [
      {
        start: freezeStart,
        end: freezeEnd,
        color: "var(--destructive/10)",
        className: "astw:border-x astw:border-destructive/30",
      },
    ],
    markers: [
      {
        at: today,
        color: "var(--primary)",
        label: <span className="astw:text-xs astw:text-primary">Today</span>,
      },
    ],
  }}
>
  {rows}
</Timeline.Viewport>
```

### Row Background

Use `background` on `Timeline.Row` to apply a background that respects guide lines:

```tsx
<Timeline.Row height={40} background={{ style: { background: "var(--muted)" } }}>
  <Timeline.Interval start={10} end={35}>
    <div className="h-full rounded-md bg-primary" />
  </Timeline.Interval>
</Timeline.Row>
```

---

---
url: https://docs.tailor.tech/app-shell/components/tooltip.md
description: >-
  Hover/focus tooltip with configurable placement and shared delay via
  Tooltip.Provider
---

# Tooltip

The `Tooltip` component displays contextual information on hover or focus. It is backed by Base UI's Tooltip primitive.

[Live preview in the UI Catalogue →](https://ui.tailor.tech/components/tooltip)

## Import

```tsx
import { Tooltip } from "@tailor-platform/app-shell";
```

## Basic Usage

```tsx
<Tooltip.Root>
  <Tooltip.Trigger render={<Button variant="outline" />}>Hover me</Tooltip.Trigger>
  <Tooltip.Content>Helpful information</Tooltip.Content>
</Tooltip.Root>
```

## Sub-components

| Sub-component      | Description                                                 |
| ------------------ | ----------------------------------------------------------- |
| `Tooltip.Provider` | Provides shared delay configuration for all nested tooltips |
| `Tooltip.Root`     | Manages tooltip open/close state                            |
| `Tooltip.Trigger`  | Element that shows the tooltip on hover or focus            |
| `Tooltip.Content`  | The tooltip popup containing the help text                  |

## Props

### Tooltip.Provider Props

Wrap a section of your UI (e.g. a toolbar) with `Tooltip.Provider` to share delay settings across multiple tooltips.

| Prop         | Type              | Default | Description                                         |
| ------------ | ----------------- | ------- | --------------------------------------------------- |
| `delay`      | `number`          | `0`     | Delay in ms before the tooltip opens (milliseconds) |
| `closeDelay` | `number`          | -       | Delay in ms before the tooltip closes               |
| `timeout`    | `number`          | -       | Timeout in ms after which the tooltip auto-closes   |
| `children`   | `React.ReactNode` | -       | Nested tooltip components                           |

### Tooltip.Root Props

| Prop           | Type                      | Default | Description                       |
| -------------- | ------------------------- | ------- | --------------------------------- |
| `open`         | `boolean`                 | -       | Controlled open state             |
| `defaultOpen`  | `boolean`                 | `false` | Initial open state (uncontrolled) |
| `onOpenChange` | `(open: boolean) => void` | -       | Callback when open state changes  |
| `children`     | `React.ReactNode`         | -       | Tooltip sub-components            |

### Tooltip.Content Props

| Prop         | Type                                     | Default    | Description                                              |
| ------------ | ---------------------------------------- | ---------- | -------------------------------------------------------- |
| `side`       | `"top" \| "right" \| "bottom" \| "left"` | `"top"`    | Preferred placement of the tooltip                       |
| `align`      | `"start" \| "center" \| "end"`           | `"center"` | Alignment along the placement axis                       |
| `sideOffset` | `number`                                 | `5`        | Distance in px from the trigger                          |
| `noArrow`    | `boolean`                                | `false`    | When `true`, suppresses the arrow indicator on the popup |
| `className`  | `string`                                 | -          | Additional CSS classes                                   |
| `children`   | `React.ReactNode`                        | -          | Tooltip text or content                                  |

## Placement

```tsx
<Tooltip.Root>
  <Tooltip.Trigger render={<Button />}>Trigger</Tooltip.Trigger>
  <Tooltip.Content side="right" align="start">
    Appears on the right
  </Tooltip.Content>
</Tooltip.Root>
```

## Shared Delay with Provider

Use `Tooltip.Provider` to avoid tooltips opening immediately in dense UIs like toolbars:

```tsx
<Tooltip.Provider delay={300}>
  <Toolbar>
    <Tooltip.Root>
      <Tooltip.Trigger render={<Button size="icon" />}>
        <BoldIcon />
      </Tooltip.Trigger>
      <Tooltip.Content>Bold</Tooltip.Content>
    </Tooltip.Root>
    <Tooltip.Root>
      <Tooltip.Trigger render={<Button size="icon" />}>
        <ItalicIcon />
      </Tooltip.Trigger>
      <Tooltip.Content>Italic</Tooltip.Content>
    </Tooltip.Root>
  </Toolbar>
</Tooltip.Provider>
```

## Examples

### Icon Button with Tooltip

```tsx
import { PencilIcon } from "lucide-react";

<Tooltip.Root>
  <Tooltip.Trigger render={<Button size="icon" variant="ghost" />}>
    <PencilIcon />
    <span className="astw:sr-only">Edit</span>
  </Tooltip.Trigger>
  <Tooltip.Content>Edit order</Tooltip.Content>
</Tooltip.Root>;
```

### Controlled Tooltip

```tsx
const [open, setOpen] = useState(false);

<Tooltip.Root open={open} onOpenChange={setOpen}>
  <Tooltip.Trigger render={<Button />}>Info</Tooltip.Trigger>
  <Tooltip.Content>Additional details here</Tooltip.Content>
</Tooltip.Root>;
```

## Accessibility

* Tooltip content is rendered in a portal
* Trigger receives focus and keyboard activation support
* `sr-only` text on icon-only triggers is recommended for screen readers

## Related Components

* [Button](button) - Common trigger element for tooltips

---

---
url: https://docs.tailor.tech/app-shell/components/with-guard.md
description: >-
  Conditionally render UI elements based on guard evaluation with support for
  async permissions checks
---

# WithGuard

`WithGuard` is a component for conditionally rendering UI elements based on guard evaluation. It uses the same guard system as route-level guards, making permission logic reusable throughout your application.

[Live preview in the UI Catalogue →](https://ui.tailor.tech/components/with-guard)

## Import

```tsx
import { WithGuard, pass, hidden } from "@tailor-platform/app-shell";
```

## Basic Usage

```tsx
import { WithGuard, pass, hidden } from "@tailor-platform/app-shell";

const isAdmin = ({ context }) => (context.currentUser?.role === "admin" ? pass() : hidden());

function AdminPanel() {
  return (
    <div>
      <h1>Dashboard</h1>

      <WithGuard guards={[isAdmin]}>
        <Button>Delete All Users</Button>
      </WithGuard>
    </div>
  );
}
```

If the user is not an admin, the button won't render.

## Props

| Prop       | Type              | Default      | Description                                         |
| ---------- | ----------------- | ------------ | --------------------------------------------------- |
| `guards`   | `Guard[]`         | **Required** | Array of guard functions to evaluate                |
| `children` | `React.ReactNode` | **Required** | Content to render when all guards pass              |
| `fallback` | `React.ReactNode` | `null`       | Content to render when any guard returns `hidden()` |
| `loading`  | `React.ReactNode` | `null`       | Content to show while async guards are evaluating   |

## Guard Functions

WithGuard uses the same `Guard` type as route guards:

```typescript
type Guard = (ctx: GuardContext) => GuardResult | Promise<GuardResult>;

type GuardResult =
  | { type: "pass" } // Allow rendering
  | { type: "hidden" }; // Hide content (render fallback)
```

**Note:** Unlike route guards, `redirectTo()` is **not supported** in WithGuard. Use `hidden()` with a fallback that handles navigation if needed.

### Creating Guards

```tsx
import { type Guard, pass, hidden } from "@tailor-platform/app-shell";

// Simple guard
const requireAuth: Guard = ({ context }) => {
  return context.currentUser ? pass() : hidden();
};

// Async guard with API call
const hasPermission: Guard = async ({ context }) => {
  const canAccess = await fetch("/api/permissions/admin")
    .then((r) => r.json())
    .then((data) => data.allowed);

  return canAccess ? pass() : hidden();
};

// Parameterized guard (curried function)
const isOwner =
  (resourceId: string): Guard =>
  ({ context }) => {
    return context.currentUser?.id === resourceId ? pass() : hidden();
  };
```

## Examples

### Simple Role Check

```tsx
const isAdmin = ({ context }) => (context.currentUser?.role === "admin" ? pass() : hidden());

<WithGuard guards={[isAdmin]}>
  <Button>Admin Settings</Button>
</WithGuard>;
```

### With Fallback

Show alternative content when guard fails:

```tsx
<WithGuard guards={[isAdmin]} fallback={<p>You need admin access to view this.</p>}>
  <AdminPanel />
</WithGuard>
```

### With Loading State

Show loading spinner while checking permissions:

```tsx
const checkPermission: Guard = async ({ context }) => {
  const allowed = await api.checkPermission("admin");
  return allowed ? pass() : hidden();
};

<WithGuard guards={[checkPermission]} loading={<Spinner />} fallback={<UpgradePrompt />}>
  <PremiumFeature />
</WithGuard>;
```

### Multiple Guards

All guards must pass for content to render:

```tsx
const isAdmin = ({ context }) => (context.currentUser?.role === "admin" ? pass() : hidden());

const hasFeatureFlag = ({ context }) => (context.featureFlags?.betaFeatures ? pass() : hidden());

<WithGuard guards={[isAdmin, hasFeatureFlag]}>
  <BetaAdminFeature />
</WithGuard>;
```

### Parameterized Guards

Use curried functions to create reusable parameterized guards:

```tsx
const isOwner =
  (resourceId: string): Guard =>
  ({ context }) => {
    return context.currentUser?.id === resourceId ? pass() : hidden();
  };

function ResourceActions({ resourceId }) {
  return (
    <WithGuard guards={[isOwner(resourceId)]}>
      <Button>Edit</Button>
      <Button>Delete</Button>
    </WithGuard>
  );
}
```

### In Sidebar Navigation

Conditionally show navigation items:

```tsx
import { DefaultSidebar, SidebarItem, WithGuard } from "@tailor-platform/app-shell";

const isAdmin = ({ context }) => (context.currentUser?.role === "admin" ? pass() : hidden());

<DefaultSidebar>
  <SidebarItem to="/dashboard" />
  <SidebarItem to="/products" />

  <WithGuard guards={[isAdmin]}>
    <SidebarItem to="/admin" />
    <SidebarItem to="/settings" />
  </WithGuard>
</DefaultSidebar>;
```

### Feature Flags

Toggle features based on flags:

```tsx
const hasBetaFeature = ({ context }) => (context.featureFlags?.newDashboard ? pass() : hidden());

<WithGuard guards={[hasBetaFeature]} fallback={<OldDashboard />}>
  <NewDashboard />
</WithGuard>;
```

### Subscription Tiers

Show features based on user's subscription:

```tsx
const isPremium = ({ context }) =>
  context.currentUser?.subscription === "premium" ? pass() : hidden();

<WithGuard
  guards={[isPremium]}
  fallback={
    <Card>
      <h3>Premium Feature</h3>
      <p>Upgrade to access advanced analytics.</p>
      <Button>Upgrade Now</Button>
    </Card>
  }
>
  <AdvancedAnalytics />
</WithGuard>;
```

### Dynamic Permissions

Check permissions from API:

```tsx
const canDeleteOrder =
  (orderId: string): Guard =>
  async ({ context }) => {
    const response = await fetch(`/api/orders/${orderId}/permissions`);
    const { canDelete } = await response.json();
    return canDelete ? pass() : hidden();
  };

function OrderActions({ orderId }) {
  return (
    <div>
      <Button>View</Button>
      <Button>Edit</Button>
      <WithGuard guards={[canDeleteOrder(orderId)]} loading={<Spinner size="sm" />}>
        <Button variant="destructive">Delete</Button>
      </WithGuard>
    </div>
  );
}
```

### Combining with Route Guards

Reuse the same guards for routes and UI:

```tsx
// guards.ts
export const requireAuth: Guard = ({ context }) => {
  return context.currentUser ? pass() : hidden();
};

export const isAdmin: Guard = ({ context }) => {
  return context.currentUser?.role === "admin" ? pass() : hidden();
};

// routes.tsx
const adminModule = defineModule({
  path: "admin",
  component: AdminPage,
  guards: [requireAuth, isAdmin], // Route-level
});

// component.tsx
<WithGuard guards={[requireAuth, isAdmin]}>
  {" "}
  {/* UI-level */}
  <AdminSettings />
</WithGuard>;
```

## Guard Evaluation

Guards are evaluated in order and stop at the first non-pass result:

```tsx
const guards = [guardA, guardB, guardC];

// If guardA returns hidden(), guardB and guardC are NOT evaluated
<WithGuard guards={guards}>
  <Content />
</WithGuard>;
```

## Performance

### Caching

WithGuard caches guard results based on `contextData` reference:

* Guards re-evaluate when `contextData` changes
* Guards do NOT re-evaluate when props change (except `guards` array)

### Suspense Integration

Async guards use React Suspense:

* Shows `loading` prop while evaluating
* Renders `children` or `fallback` when complete
* Automatically suspends during evaluation

## Context Data

Guards receive the same context as route guards:

```typescript
// Define context type
declare module "@tailor-platform/app-shell" {
  interface AppShellRegister {
    contextData: {
      currentUser: User | null;
      featureFlags: FeatureFlags;
      permissions: string[];
    };
  }
}

// Use in guards
const hasPermission =
  (perm: string): Guard =>
  ({ context }) => {
    return context.permissions.includes(perm) ? pass() : hidden();
  };
```

## Comparison: WithGuard vs Route Guards

| Feature                     | WithGuard                | Route Guards                |
| --------------------------- | ------------------------ | --------------------------- |
| **Purpose**                 | Conditional UI rendering | Route access control        |
| **Location**                | Inside components        | Module/resource definitions |
| **Supports `pass()`**       | ✅ Yes                   | ✅ Yes                      |
| **Supports `hidden()`**     | ✅ Yes                   | ✅ Yes                      |
| **Supports `redirectTo()`** | ❌ No                    | ✅ Yes                      |
| **Async guards**            | ✅ Yes                   | ✅ Yes                      |
| **Reusable**                | ✅ Yes                   | ✅ Yes                      |

## Best Practices

### Do:

* ✅ Reuse guards between routes and UI
* ✅ Use descriptive guard names (`isAdmin`, `canEdit`)
* ✅ Provide fallback for better UX
* ✅ Show loading state for async guards
* ✅ Cache expensive permission checks

### Don't:

* ❌ Use `redirectTo()` in WithGuard (not supported)
* ❌ Make guards too complex (extract to functions)
* ❌ Forget to handle loading states
* ❌ Skip fallback when hiding important features
* ❌ Duplicate permission logic (reuse guards)

## Accessibility

* Content is fully removed from DOM when hidden (not just visually)
* Screen readers won't announce hidden content
* Loading states should be announced to screen readers
* Fallback content should be accessible

## TypeScript

Full type safety with TypeScript:

```typescript
import { type Guard, type WithGuardProps } from "@tailor-platform/app-shell";

// Type-safe guard
const isAdmin: Guard = ({ context }) => {
  // context is fully typed
  return context.currentUser?.role === "admin" ? pass() : hidden();
};

// Type-safe props
const guardProps: WithGuardProps = {
  guards: [isAdmin],
  children: <AdminPanel />,
  fallback: <AccessDenied />,
};
```

## Troubleshooting

### Guard not re-evaluating

**Problem:** Guard doesn't update when data changes

**Solution:** Ensure `contextData` reference changes:

```tsx
// ❌ Bad - mutating object
context.currentUser.role = "admin";

// ✅ Good - new reference
setContextData({
  ...contextData,
  currentUser: { ...currentUser, role: "admin" },
});
```

### Infinite loading

**Problem:** Loading state never resolves

**Solution:** Ensure async guards return a result:

```tsx
// ❌ Bad - no return
const checkPermission: Guard = async ({ context }) => {
  await fetch("/api/check");
  // Missing return!
};

// ✅ Good - returns result
const checkPermission: Guard = async ({ context }) => {
  const allowed = await fetch("/api/check").then((r) => r.json());
  return allowed ? pass() : hidden();
};
```

## Related Components

* [AppShell](app-shell) - Context provider for guards
* [SidebarItem](sidebar-item) - Use WithGuard in navigation

## Related Concepts

* [Guards and Permissions](../api/guards/overview) - Comprehensive guard guide
* [Modules and Resources](../concepts/modules-and-resources) - Route-level guards

## API Reference

* [pass()](../api/guards/pass) - Allow access guard
* [hidden()](../api/guards/hidden) - Hide content guard
* [Guards Overview](../api/guards/overview) - Complete guard reference

---

---
url: https://docs.tailor.tech/app-shell/api/create-ai-gateway-client.md
description: Create a low-level AI Gateway client that reuses AppShell authentication
---

# createAIGatewayClient

Creates a small AI Gateway transport client for text-only chat completions.

## Signature

```typescript
function createAIGatewayClient(config: {
  gatewayUri: string;
  authClient: AuthClient;
}): AIGatewayClient;
```

## Parameters

### `gatewayUri`

* **Type:** `string`
* **Required:** Yes
* **Description:** Base URL of the AI Gateway

### `authClient`

* **Type:** `AuthClient`
* **Required:** Yes
* **Description:** Auth client used for authenticated requests via `authClient.fetch(...)`

## Return Value

```typescript
interface AIGatewayClient {
  streamChatCompletion(request: AIGatewayChatRequest): AsyncIterable<AIChatCompletionEvent>;
}
```

The iterable yields completion events:

* `text-delta` — append `event.text` to build the assistant response
* `done` — terminal event with an optional `finishReason`

## Related Types

```typescript
type AIGatewayChatMessage =
  | {
      role: "system" | "user";
      content: string;
    }
  | {
      role: "assistant";
      content?: string;
    };

interface AIGatewayChatRequest {
  model: string;
  messages: AIGatewayChatMessage[];
  signal?: AbortSignal;
}

type AIChatCompletionEvent =
  | {
      type: "text-delta";
      text: string;
    }
  | {
      type: "done";
      finishReason?: string;
    };
```

## Usage

```typescript
import { createAuthClient, createAIGatewayClient } from "@tailor-platform/app-shell";

const authClient = createAuthClient({
  clientId: "your-client-id",
  appUri: "https://xyz.erp.dev",
});

const aiClient = createAIGatewayClient({
  gatewayUri: "https://your-ai-gateway.example.com",
  authClient,
});

let text = "";
for await (const event of aiClient.streamChatCompletion({
  model: "gpt-5-mini",
  messages: [{ role: "user", content: "Hello" }],
})) {
  if (event.type === "text-delta") {
    text += event.text;
  }
}

console.log(text);
```

## Notes

* AppShell chooses the appropriate AI Gateway transport automatically
* The low-level API is intentionally narrow: text deltas plus completion metadata
* `request.signal` is passed through so callers can abort in-flight work

## Related

* [Authentication Concept](../concepts/authentication)
* [useAIChat](use-ai-chat)

---

---
url: https://docs.tailor.tech/app-shell/api/create-typed-paths.md
description: Generate type-safe route paths from file-based routing
---

# createTypedPaths

Generates type-safe route path helpers from file-based routing structure. Only available when using the Vite plugin.

## Signature

```typescript
function createTypedPaths<T extends Record<string, PageEntry>>(pages: T): TypedPaths<T>;
```

## Parameters

### `pages`

* **Type:** `Record<string, PageEntry>`
* **Required:** Yes
* **Description:** Pages object from virtual module (auto-generated by Vite plugin)

## Return Value

Type-safe path builder functions for each route.

## Usage

### Basic Usage

```typescript
import { createTypedPaths } from "@tailor-platform/app-shell";
import pages from "virtual:app-shell-pages";

const paths = createTypedPaths(pages);

// Type-safe navigation
navigate(paths.products.detail({ id: "123" }));
// Result: "/products/123"
```

### With useNavigate

```typescript
import { useNavigate } from "@tailor-platform/app-shell";

function ProductCard({ product }: { product: Product }) {
  const navigate = useNavigate();
  const paths = createTypedPaths(pages);

  const handleClick = () => {
    navigate(paths.products.detail({ id: product.id }));
  };

  return <button onClick={handleClick}>View Details</button>;
}
```

### With Link Component

```typescript
import { Link } from "@tailor-platform/app-shell";

function ProductLink({ id }: { id: string }) {
  const paths = createTypedPaths(pages);

  return (
    <Link to={paths.products.detail({ id })}>
      View Product
    </Link>
  );
}
```

### Nested Routes

```typescript
// File structure:
// pages/
//   orders/
//     page.tsx
//     [id]/
//       page.tsx
//       edit/
//         page.tsx

paths.orders.index(); // "/orders"
paths.orders.detail({ id: "1" }); // "/orders/1"
paths.orders.edit({ id: "1" }); // "/orders/1/edit"
```

## TypeScript Benefits

```typescript
// ✅ Type-safe parameters
paths.products.detail({ id: "123" }); // Valid

// ❌ Type error - missing required param
paths.products.detail(); // Error: Argument required

// ❌ Type error - wrong param name
paths.products.detail({ productId: "123" }); // Error: Unknown key
```

## File-Based Routing Only

This function is only available when using the Vite plugin with file-based routing.

See [File-Based Routing](../concepts/file-based-routing) for setup.

## Related

* [File-Based Routing](../concepts/file-based-routing) - Setup guide
* [useNavigate](router/use-navigate) - Programmatic navigation

---

---
url: https://docs.tailor.tech/app-shell/api/define-i18n-labels.md
description: Define internationalized labels for multi-language support
---

# defineI18nLabels

Creates internationalized labels that automatically resolve based on the current locale.

## Signature

```typescript
function defineI18nLabels<T extends Record<string, Record<string, string>>>(
  labels: T,
): I18nLabels<T>;
```

## Parameters

### `labels`

* **Type:** `Record<string, Record<string, string>>`
* **Required:** Yes
* **Description:** Object mapping label keys to locale-specific strings

## Return Value

```typescript
{
  t: (key: keyof T) => LocalizedString;
}
```

## Usage

### Basic Labels

```typescript
import { defineI18nLabels } from "@tailor-platform/app-shell";

const labels = defineI18nLabels({
  dashboard: {
    en: "Dashboard",
    ja: "ダッシュボード",
  },
  products: {
    en: "Products",
    ja: "商品",
  },
  settings: {
    en: "Settings",
    ja: "設定",
  },
});

// Use in modules
const dashboardModule = defineModule({
  path: "dashboard",
  meta: {
    title: labels.t("dashboard"),
  },
  component: DashboardPage,
});
```

### Multiple Locales

```typescript
const labels = defineI18nLabels({
  welcome: {
    en: "Welcome",
    ja: "ようこそ",
    es: "Bienvenido",
    fr: "Bienvenue",
  },
});
```

### In Components

```typescript
function WelcomeMessage() {
  const labels = defineI18nLabels({
    greeting: {
      en: "Hello",
      ja: "こんにちは",
    },
  });

  return <h1>{labels.t("greeting")}</h1>;
}
```

### With SidebarGroup

```typescript
import { SidebarGroup } from "@tailor-platform/app-shell";

const labels = defineI18nLabels({
  admin: {
    en: "Administration",
    ja: "管理",
  },
});

<SidebarGroup title={labels.t("admin")}>
  <SidebarItem to="/admin/users" />
</SidebarGroup>
```

## Setting Locale

The active locale is controlled by the `locale` prop on `AppShell`:

```typescript
<AppShell locale="ja" modules={modules}>
  <SidebarLayout />
</AppShell>
```

Supported locales: `en`, `ja`

If not specified, auto-detects from browser settings.

## TypeScript

Full type safety:

```typescript
const labels = defineI18nLabels({
  dashboard: { en: "Dashboard", ja: "ダッシュボード" },
  products: { en: "Products", ja: "商品" },
});

labels.t("dashboard"); // ✅ Valid
labels.t("invalid"); // ❌ Type error
```

## Related

* [defineModule](define-module) - Use labels in modules

---

---
url: https://docs.tailor.tech/app-shell/api/define-module.md
description: Define a top-level module that appears in the main navigation
---

# defineModule

Creates a top-level module that appears in the main navigation. Modules can contain resources and optionally have their own landing page component.

## Signature

```typescript
function defineModule(props: DefineModuleProps): Module;
```

## Parameters

### `path`

* **Type:** `string`
* **Required:** Yes
* **Description:** URL path segment for the module

```typescript
defineModule({
  path: "products", // URL: /products
});
```

### `component`

* **Type:** `(props: ResourceComponentProps) => React.ReactNode`
* **Required:** No
* **Description:** Landing page component for the module. If omitted, the module redirects to its first resource, and its breadcrumb segment is rendered as plain text (not a link).

**ResourceComponentProps:**

```typescript
{
  title: string;          // Resolved title
  icon?: React.ReactNode; // Module icon
  resources?: Resource[]; // Child resources
}
```

### `resources`

* **Type:** `Resource[]`
* **Required:** Yes
* **Description:** Array of resources within this module. Define using `defineResource()`.

### `meta`

* **Type:** `object`
* **Required:** No
* **Description:** Metadata configuration for the module

**meta.title**

* **Type:** `string | LocalizedString`
* **Default:** Capitalized `path`
* **Description:** Display title in navigation and breadcrumbs

**meta.icon**

* **Type:** `React.ReactNode`
* **Description:** Icon displayed in sidebar navigation

**meta.breadcrumbTitle**

* **Type:** `string | ((segment: string) => string)`
* **Description:** Custom breadcrumb segment title override

### `guards`

* **Type:** `Guard[]`
* **Required:** No
* **Description:** Access control guards executed in order. If any guard returns non-pass, access is denied.

See [Guards Overview](guards/overview) for details.

### `errorBoundary`

* **Type:** `React.ReactNode`
* **Required:** No
* **Description:** Error boundary component for this module and its child resources. Use `useRouteError` hook to access error details.

## Return Type

```typescript
Module;
```

A module object that can be passed to the `modules` prop of `AppShell`.

## Examples

### Basic Module

```typescript
import { defineModule } from "@tailor-platform/app-shell";

const dashboardModule = defineModule({
  path: "dashboard",
  component: () => <h1>Dashboard</h1>,
  resources: [],
});
```

### Module with Icon and Title

```typescript
import { Home } from "lucide-react";

const dashboardModule = defineModule({
  path: "dashboard",
  meta: {
    title: "Dashboard",
    icon: <Home />,
  },
  component: DashboardPage,
  resources: [],
});
```

### Module with Resources

```typescript
const productsModule = defineModule({
  path: "products",
  component: ProductsListPage,
  resources: [
    defineResource({
      path: ":id",
      component: ProductDetailPage,
    }),
    defineResource({
      path: "categories",
      component: CategoriesPage,
    }),
  ],
});
```

### Module without Component (Auto-redirect)

```typescript
const dashboardModule = defineModule({
  path: "dashboard",
  // No component - automatically redirects to first resource
  resources: [
    defineResource({
      path: "overview",
      component: OverviewPage,
    }),
    defineResource({
      path: "analytics",
      component: AnalyticsPage,
    }),
  ],
});
```

### Module with Guards

```typescript
import { pass, hidden } from "@tailor-platform/app-shell";

const adminModule = defineModule({
  path: "admin",
  component: AdminPage,
  resources: [adminResources],
  guards: [
    ({ context }) => {
      return context.currentUser?.role === "admin" ? pass() : hidden();
    },
  ],
});
```

### Module with Error Boundary

```typescript
import { useRouteError } from "@tailor-platform/app-shell";

const ErrorBoundary = () => {
  const error = useRouteError() as Error;
  return (
    <div>
      <h1>Module Error</h1>
      <p>{error.message}</p>
    </div>
  );
};

const productsModule = defineModule({
  path: "products",
  component: ProductsPage,
  resources: [],
  errorBoundary: <ErrorBoundary />,
});
```

### Module with Internationalization

```typescript
import { defineI18nLabels } from "@tailor-platform/app-shell";

const labels = defineI18nLabels({
  dashboard: {
    en: "Dashboard",
    ja: "ダッシュボード",
  },
});

const dashboardModule = defineModule({
  path: "dashboard",
  meta: {
    title: labels.t("dashboard"),
  },
  component: DashboardPage,
  resources: [],
});
```

## TypeScript

```typescript
import { type DefineModuleProps, type Module } from "@tailor-platform/app-shell";

const props: DefineModuleProps = {
  path: "products",
  component: ProductsPage,
  resources: [],
};

const module: Module = defineModule(props);
```

## Related

* [defineResource](define-resource) - Define nested resources
* [Guards Overview](guards/overview) - Access control
* [defineI18nLabels](define-i18n-labels) - Internationalization
* [Modules & Resources Concept](../concepts/modules-and-resources) - Detailed guide

---

---
url: https://docs.tailor.tech/app-shell/api/define-resource.md
description: Define a nested resource (page) within a module
---

# defineResource

Creates a nested resource (page) within a module. Resources represent individual pages in your application hierarchy.

## Signature

```typescript
function defineResource(props: DefineResourceProps): Resource;
```

## Parameters

### `path`

* **Type:** `string`
* **Required:** Yes
* **Description:** URL path segment for the resource. Supports dynamic parameters with `:param` syntax.

```typescript
defineResource({
  path: ":id", // Dynamic: /products/:id
  path: "categories", // Static: /products/categories
});
```

### `component`

* **Type:** `(props: ResourceComponentProps) => React.ReactNode`
* **Required:** Yes
* **Description:** Page component to render

**ResourceComponentProps:**

```typescript
{
  title: string;          // Resolved title
  icon?: React.ReactNode; // Inherited from module
  resources?: Resource[]; // Child resources
}
```

### `meta`

* **Type:** `object`
* **Required:** No
* **Description:** Metadata configuration

**meta.title**

* **Type:** `string | LocalizedString`
* **Default:** Capitalized `path`
* **Description:** Display title in navigation and breadcrumbs

**meta.icon**

* **Type:** `React.ReactNode`
* **Description:** Icon override (inherits from module by default)

**meta.breadcrumbTitle**

* **Type:** `string | ((segment: string) => string)`
* **Description:** Custom breadcrumb segment title

### `subResources`

* **Type:** `Resource[]`
* **Required:** No
* **Description:** Nested resources within this resource

### `guards`

* **Type:** `Guard[]`
* **Required:** No
* **Description:** Access control guards

See [Guards Overview](guards/overview) for details.

### `errorBoundary`

* **Type:** `React.ReactNode`
* **Required:** No
* **Description:** Error boundary component for this resource

## Return Type

```typescript
Resource;
```

A resource object used in the `resources` array of `defineModule`.

## Examples

### Basic Resource

```typescript
import { defineResource } from "@tailor-platform/app-shell";

const detailResource = defineResource({
  path: ":id",
  component: () => <div>Detail Page</div>,
});
```

### Resource with Title

```typescript
const categoriesResource = defineResource({
  path: "categories",
  meta: {
    title: "Product Categories",
  },
  component: CategoriesPage,
});
```

### Dynamic Route with useParams

```typescript
import { useParams } from "@tailor-platform/app-shell";

const productDetailResource = defineResource({
  path: ":id",
  meta: {
    title: "Product Details",
  },
  component: () => {
    const { id } = useParams();
    return <div>Product {id}</div>;
  },
});
```

### Nested Resources

```typescript
const ordersResource = defineResource({
  path: "orders",
  component: OrdersListPage,
  subResources: [
    defineResource({
      path: ":id",
      component: OrderDetailPage,
      subResources: [
        defineResource({
          path: "edit",
          component: OrderEditPage,
        }),
      ],
    }),
  ],
});

// URLs:
// /orders
// /orders/:id
// /orders/:id/edit
```

### Resource with Guards

```typescript
import { pass, hidden } from "@tailor-platform/app-shell";

const adminSettingsResource = defineResource({
  path: "admin-settings",
  component: AdminSettingsPage,
  guards: [
    ({ context }) => {
      return context.currentUser?.role === "admin" ? pass() : hidden();
    },
  ],
});
```

### Resource with Error Boundary

```typescript
import { useRouteError } from "@tailor-platform/app-shell";

const ErrorBoundary = () => {
  const error = useRouteError() as Error;
  return <div>Error: {error.message}</div>;
};

const detailResource = defineResource({
  path: ":id",
  component: DetailPage,
  errorBoundary: <ErrorBoundary />,
});
```

### Resource with Custom Breadcrumb

```typescript
const orderResource = defineResource({
  path: ":id",
  meta: {
    breadcrumbTitle: (segment) => `Order #${segment}`,
  },
  component: OrderDetailPage,
});

// Breadcrumb shows: "Orders > Order #12345"
// Instead of: "Orders > 12345"
```

### Multiple Resources

```typescript
const productsModule = defineModule({
  path: "products",
  component: ProductsPage,
  resources: [
    defineResource({
      path: ":id",
      meta: { title: "Product Details" },
      component: ProductDetailPage,
    }),
    defineResource({
      path: "categories",
      meta: { title: "Categories" },
      component: CategoriesPage,
    }),
    defineResource({
      path: "brands",
      meta: { title: "Brands" },
      component: BrandsPage,
    }),
  ],
});
```

## Navigation Behavior

Resources appear in:

* ✅ Sidebar navigation (top-level resources only)
* ✅ Breadcrumbs (all levels)
* ✅ CommandPalette search (all levels)
* ❌ Main navigation menu (use modules instead)

### Example Navigation

```typescript
defineModule({
  path: "products",
  component: ProductsPage,
  resources: [
    defineResource({
      path: "all",
      component: AllProductsPage, // Appears in sidebar
    }),
    defineResource({
      path: ":id",
      component: ProductDetailPage,
      subResources: [
        defineResource({
          path: "edit",
          component: EditPage, // Only in breadcrumbs, not sidebar
        }),
      ],
    }),
  ],
});
```

**Sidebar:**

```
› Products
  - All Products
```

**Breadcrumbs (on edit page):**

```
Products > Product Details > Edit
```

## TypeScript

```typescript
import { type DefineResourceProps, type Resource } from "@tailor-platform/app-shell";

const props: DefineResourceProps = {
  path: ":id",
  component: DetailPage,
  guards: [],
};

const resource: Resource = defineResource(props);
```

## Related

* [defineModule](define-module) - Define top-level modules
* [Guards Overview](guards/overview) - Access control
* [useParams](router/use-params) - Access route parameters
* [Modules & Resources Concept](../concepts/modules-and-resources) - Detailed guide

---

---
url: https://docs.tailor.tech/app-shell/api/use-ai-chat.md
description: Simple text-only chat hook for AI Gateway
---

# useAIChat

React hook for simple text-only chat on top of `createAIGatewayClient`.

## Signature

```typescript
const useAIChat: (config: { client: AIGatewayClient; model: string }) => {
  messages: AIChatMessage[];
  status: "ready" | "submitted" | "streaming" | "error";
  error?: Error;
  sendMessage: (message: string) => Promise<boolean>;
  stop: () => void;
};
```

## Return Value

### `messages`

```typescript
interface AIChatMessage {
  id: string;
  role: "user" | "assistant";
  content: string;
}
```

### `status`

* **Type:** `"ready" | "submitted" | "streaming" | "error"`
* **Description:** Current request state

### `error`

* **Type:** `Error | undefined`
* **Description:** Last request error, if any

### `sendMessage()`

* **Type:** `(message: string) => Promise<boolean>`
* **Description:** Appends a user message and streams the assistant response
* **Returns:** `true` when the request completes successfully, `false` when the call is ignored, stopped, or fails

### `stop()`

* **Type:** `() => void`
* **Description:** Aborts the current request if one is in progress

## Usage

```tsx
import { createAuthClient, createAIGatewayClient, useAIChat } from "@tailor-platform/app-shell";

const authClient = createAuthClient({
  clientId: "your-client-id",
  appUri: "https://xyz.erp.dev",
});

const aiClient = createAIGatewayClient({
  gatewayUri: "https://your-ai-gateway.example.com",
  authClient,
});

export function ChatScreen() {
  const { messages, sendMessage, status, stop, error } = useAIChat({
    client: aiClient,
    model: "gpt-5-mini",
  });

  return (
    <div>
      {messages.map((message) => (
        <div key={message.id}>
          {message.role}: {message.content}
        </div>
      ))}

      <button
        onClick={() => void sendMessage("Hello")}
        disabled={status === "submitted" || status === "streaming"}
      >
        Send
      </button>
      <button onClick={stop} disabled={status !== "submitted" && status !== "streaming"}>
        Stop
      </button>
      {error ? <div>{error.message}</div> : null}
    </div>
  );
}
```

## Notes

* AppShell chooses the appropriate AI Gateway transport automatically
* The hook is intentionally text-only
* System prompts and custom history shaping should use the low-level client directly
* `stop()` keeps any already-streamed assistant text and ignores late chunks from the stopped request

## Related

* [createAIGatewayClient](create-ai-gateway-client)

---

---
url: https://docs.tailor.tech/app-shell/api/use-app-shell.md
description: Hook to access AppShell context data and configuration
---

# useAppShell

React hook to access AppShell context data and configuration within your components.

## Signature

```typescript
const useAppShell: () => {
  context: ContextData;
  contextData: ContextData;
  configurations: AppShellConfig;
};
```

## Return Value

### `context` / `contextData`

* **Type:** `ContextData`
* **Description:** Custom context data passed to AppShell. Same as the `contextData` prop.

### `configurations`

* **Type:** `AppShellConfig`
* **Description:** AppShell configuration (locale, basePath, etc.)

## Usage

### Basic Access

```typescript
import { useAppShell } from "@tailor-platform/app-shell";

function MyComponent() {
  const { context } = useAppShell();

  return <div>Welcome, {context.currentUser?.name}</div>;
}
```

### Access Configuration

```typescript
function LocaleDisplay() {
  const { configurations } = useAppShell();

  return <div>Current locale: {configurations.locale}</div>;
}
```

## Context Data

Define your context type with module augmentation:

```typescript
// types.d.ts
declare module "@tailor-platform/app-shell" {
  interface AppShellRegister {
    contextData: {
      currentUser: User | null;
      permissions: string[];
      tenantId: string;
    };
  }
}

// App.tsx
<AppShell
  modules={modules}
  contextData={{
    currentUser,
    permissions,
    tenantId,
  }}
/>

// MyComponent.tsx
const { context } = useAppShell();
context.currentUser  // Fully typed!
context.permissions  // Fully typed!
```

## Examples

### Display User Info

```typescript
function UserInfo() {
  const { context } = useAppShell();

  if (!context.currentUser) {
    return <div>Not logged in</div>;
  }

  return (
    <div>
      <h2>{context.currentUser.name}</h2>
      <p>{context.currentUser.email}</p>
    </div>
  );
}
```

### Check Permissions

```typescript
function DeleteButton() {
  const { context } = useAppShell();
  const canDelete = context.permissions.includes("users:delete");

  if (!canDelete) {
    return null;
  }

  return <Button variant="destructive">Delete</Button>;
}
```

### Feature Flags

```typescript
function BetaFeature() {
  const { context } = useAppShell();

  if (!context.featureFlags?.newDashboard) {
    return <OldDashboard />;
  }

  return <NewDashboard />;
}
```

## Related

* [AppShell Component](../components/app-shell) - Root component
* [Guards Overview](guards/overview) - Access control using context

---

---
url: https://docs.tailor.tech/app-shell/api/use-app-shell-config.md
description: Hook to access AppShell configuration data
---

# useAppShellConfig

React hook to access only the AppShell configuration (title, icon, basePath, modules, settingsResources). This is a lighter alternative to `useAppShell` when you only need configuration data.

## Signature

```typescript
const useAppShellConfig: () => AppShellConfig;
```

## Return Value

| Property            | Type                           | Description                                      |
| ------------------- | ------------------------------ | ------------------------------------------------ |
| `title`             | `string \| undefined`          | App title                                        |
| `icon`              | `React.ReactNode \| undefined` | App icon                                         |
| `basePath`          | `string \| undefined`          | Base path for all routes                         |
| `modules`           | `Module[]`                     | Registered modules                               |
| `settingsResources` | `Resource[]`                   | Resources that appear only in Settings menu      |
| `appInfo`           | `AppInfo \| undefined`         | Configuration for the built-in `/__appinfo` page |

## Usage

### Display App Info

```typescript
import { useAppShellConfig } from "@tailor-platform/app-shell";

function AppInfo() {
  const { title, basePath } = useAppShellConfig();

  return (
    <div>
      <h2>{title}</h2>
      <p>Base: {basePath}</p>
    </div>
  );
}
```

### Access Modules

```typescript
function ModuleList() {
  const { modules } = useAppShellConfig();

  return (
    <ul>
      {modules.map((module) => (
        <li key={module.path}>{module.meta?.title}</li>
      ))}
    </ul>
  );
}
```

### Build Custom Navigation

```typescript
function CustomNav() {
  const { modules } = useAppShellConfig();

  return (
    <nav>
      {modules.map((module) => (
        <a key={module.path} href={`/${module.path}`}>
          {module.meta?.title}
        </a>
      ))}
    </nav>
  );
}
```

### Settings Resources

```typescript
function SettingsMenu() {
  const { settingsResources } = useAppShellConfig();

  return (
    <div>
      <h3>Settings</h3>
      {settingsResources.map((resource) => (
        <button key={resource.path}>
          {resource.meta?.title}
        </button>
      ))}
    </div>
  );
}
```

## When to Use

Use `useAppShellConfig` when you only need configuration data:

```typescript
// ✅ Good - only need config
const { modules } = useAppShellConfig();

// ❌ Overkill - useAppShell returns more data
const { configurations } = useAppShell();
const modules = configurations.modules;
```

## Comparison with Other Hooks

| Hook                | Returns               | Use When            |
| ------------------- | --------------------- | ------------------- |
| `useAppShellConfig` | Configuration only    | Need config data    |
| `useAppShellData`   | Context data only     | Need custom context |
| `useAppShell`       | Both config + context | Need both           |

## Related

* [useAppShell](use-app-shell) - Full context access
* [useAppShellData](use-app-shell-data) - Context data only
* [AppShell Component](../components/app-shell) - Root component

---

---
url: https://docs.tailor.tech/app-shell/api/use-app-shell-data.md
description: Hook to access custom context data passed to AppShell
---

# useAppShellData

React hook to access only the custom context data. This is a lighter alternative to `useAppShell` when you only need the contextData.

## Signature

```typescript
const useAppShellData: () => ContextData;
```

## Return Value

| Type          | Description                                                               |
| ------------- | ------------------------------------------------------------------------- |
| `ContextData` | Custom context data passed to AppShell (type-safe via `AppShellRegister`) |

## Usage

### Basic Access

```typescript
import { useAppShellData } from "@tailor-platform/app-shell";

function UserProfile() {
  const contextData = useAppShellData();

  return (
    <div>
      <p>Welcome, {contextData.currentUser?.name}</p>
      <p>Role: {contextData.currentUser?.role}</p>
    </div>
  );
}
```

### Display User Info

```typescript
function UserInfo() {
  const data = useAppShellData();

  if (!data.currentUser) {
    return <div>Not logged in</div>;
  }

  return (
    <div>
      <h2>{data.currentUser.name}</h2>
      <p>{data.currentUser.email}</p>
    </div>
  );
}
```

### Check Permissions

```typescript
function AdminPanel() {
  const { permissions } = useAppShellData();
  const canManageUsers = permissions.includes("users:manage");

  if (!canManageUsers) {
    return <AccessDenied />;
  }

  return <UserManagement />;
}
```

### Feature Flags

```typescript
function BetaFeature() {
  const { featureFlags } = useAppShellData();

  if (!featureFlags?.newEditor) {
    return <LegacyEditor />;
  }

  return <NewEditor />;
}
```

## Type Safety

Define your context type with module augmentation:

```typescript
// types.d.ts
declare module "@tailor-platform/app-shell" {
  interface AppShellRegister {
    contextData: {
      currentUser: User | null;
      permissions: string[];
      tenantId: string;
      featureFlags: {
        newEditor: boolean;
        betaDashboard: boolean;
      };
    };
  }
}
```

Now `useAppShellData()` returns fully typed data:

```typescript
const data = useAppShellData();
data.currentUser; // Type: User | null
data.permissions; // Type: string[]
data.featureFlags; // Type: { newEditor: boolean, betaDashboard: boolean }
```

## When to Use

Use `useAppShellData` when you only need context data:

```typescript
// ✅ Good - only need context
const data = useAppShellData();

// ❌ Overkill - useAppShell returns more than needed
const { context } = useAppShell();
```

## Comparison with Other Hooks

| Hook                | Returns               | Use When            |
| ------------------- | --------------------- | ------------------- |
| `useAppShellData`   | Context data only     | Need custom context |
| `useAppShellConfig` | Configuration only    | Need config data    |
| `useAppShell`       | Both config + context | Need both           |

## Related

* [useAppShell](use-app-shell) - Full context access
* [useAppShellConfig](use-app-shell-config) - Configuration only
* [AppShell Component](../components/app-shell) - Root component
* [Guards Overview](guards/overview) - Using context in guards

---

---
url: https://docs.tailor.tech/app-shell/api/use-auth.md
description: Hook for accessing authentication state and methods
---

# useAuth

React hook to access authentication state and methods when using `AuthProvider`.

## Signature

```typescript
const useAuth: () => {
  error: string | null;
  isAuthenticated: boolean;
  isReady: boolean;
  login: () => Promise<void>;
  logout: () => Promise<void>;
  checkAuthStatus: () => Promise<AuthState>;
};
```

## Return Value

### `error`

* **Type:** `string | null`
* **Description:** Error message if authentication failed

### `isAuthenticated`

* **Type:** `boolean`
* **Description:** Whether the user is currently authenticated

### `isReady`

* **Type:** `boolean`
* **Description:** Whether the initial auth check has completed. Always check this before rendering authenticated content to avoid flashing unauthenticated state.

### `login()`

* **Type:** `() => Promise<void>`
* **Description:** Initiates the login process. Redirects to Tailor Platform authentication page.

### `logout()`

* **Type:** `() => Promise<void>`
* **Description:** Logs out the current user. Clears tokens and session.

### `checkAuthStatus()`

* **Type:** `() => Promise<AuthState>`
* **Description:** Checks current auth status. Makes network request to verify and refresh tokens if needed.

## Usage

### Basic Authentication Flow

```typescript
import { useAuth } from "@tailor-platform/app-shell";

function MyComponent() {
  const { isAuthenticated, isReady, login, logout } = useAuth();

  if (!isReady) {
    return <div>Loading...</div>;
  }

  if (!isAuthenticated) {
    return <button onClick={login}>Log In</button>;
  }

  return (
    <div>
      <p>You are logged in!</p>
      <button onClick={logout}>Log Out</button>
    </div>
  );
}
```

### Protected Content

```typescript
function ProtectedPage() {
  const { isAuthenticated, isReady } = useAuth();

  if (!isReady) {
    return <Spinner />;
  }

  if (!isAuthenticated) {
    return <LoginPrompt />;
  }

  return <SecureContent />;
}
```

### Handle Auth Errors

```typescript
function AuthStatus() {
  const { isAuthenticated, error, login } = useAuth();

  if (error) {
    return (
      <div>
        <p>Authentication failed: {error}</p>
        <button onClick={login}>Retry</button>
      </div>
    );
  }

  return <div>Status: {isAuthenticated ? "Logged in" : "Logged out"}</div>;
}
```

## With AuthProvider

```typescript
import { AuthProvider, AppShell, useAuth } from "@tailor-platform/app-shell";

function App() {
  return (
    <AuthProvider
      apiEndpoint="https://api.tailor.tech"
      clientId="your-client-id"
      redirectUri="http://localhost:3000/callback"
      autoLogin={true}
    >
      <AppShell modules={modules}>
        <SidebarLayout />
      </AppShell>
    </AuthProvider>
  );
}
```

## Related

* [Authentication Concept](../concepts/authentication) - Authentication guide
* [AuthProvider](../components/app-shell) - Auth provider setup

---

---
url: https://docs.tailor.tech/app-shell/api/use-override-breadcrumb.md
description: Hook for dynamically overriding breadcrumb titles from within page components
---

# useOverrideBreadcrumb

React hook to dynamically override the breadcrumb title for the current page. Useful for displaying data-driven titles (e.g., record names fetched from an API) instead of static route-based titles.

## Signature

```typescript
function useOverrideBreadcrumb(title: string | undefined): void;
```

## Parameters

### `title`

* **Type:** `string | undefined`
* **Required:** Yes
* **Description:** The title to display in the breadcrumb for the current path. When `undefined`, any previous override is removed and the default title (from `defineResource`) is restored.

## Usage

### With `defineResource`

```tsx
import { useOverrideBreadcrumb } from "@tailor-platform/app-shell";

defineResource({
  path: ":id",
  component: () => {
    const { id } = useParams();
    const { data } = useQuery(GET_ORDER, { variables: { id } });

    // Update breadcrumb with the order name
    useOverrideBreadcrumb(data?.order?.name);

    return <OrderDetail />;
  },
});
```

### With file-based routing

```tsx
import { useOverrideBreadcrumb, useParams } from "@tailor-platform/app-shell";

const OrderDetailPage = () => {
  const { id } = useParams();
  const { data } = useQuery(GET_ORDER, { variables: { id } });

  // Update breadcrumb with the order name
  useOverrideBreadcrumb(data?.order?.name);

  return <div>...</div>;
};

export default OrderDetailPage;
```

## Notes

* The hook updates reactively — pass the result of a data-fetching query directly and the breadcrumb updates when the data resolves.
* When `title` is `undefined` (e.g., while data is loading), the override is cleared and the default title is shown.
* The override is automatically cleaned up when the component unmounts.

## Related

* [defineResource](define-resource) - Define routes and their default breadcrumb titles
* [Routing and Navigation](../concepts/routing-navigation) - Overview of breadcrumb behavior

---

---
url: https://docs.tailor.tech/app-shell/api/use-page-meta.md
description: Hook to resolve page metadata from route path
---

# usePageMeta

React hook to resolve page metadata (title, icon) from a route path.

## Signature

```typescript
const usePageMeta: (path: string) => {
  title: string;
  icon?: React.ReactNode;
} | null;
```

## Parameters

### `path`

* **Type:** `string`
* **Required:** Yes
* **Description:** Route path to look up metadata for

## Return Value

Returns an object with `title` and optional `icon`, or `null` if path not found.

## Usage

### Resolve Title and Icon

```typescript
import { usePageMeta } from "@tailor-platform/app-shell";

function NavigationItem({ path }: { path: string }) {
  const meta = usePageMeta(path);

  if (!meta) {
    return null;
  }

  return (
    <div>
      {meta.icon}
      <span>{meta.title}</span>
    </div>
  );
}
```

### Custom Link Component

```typescript
function CustomLink({ to }: { to: string }) {
  const meta = usePageMeta(to);

  return (
    <a href={to}>
      {meta?.icon}
      {meta?.title || to}
    </a>
  );
}
```

### Breadcrumb Builder

```typescript
function Breadcrumb({ paths }: { paths: string[] }) {
  return (
    <div>
      {paths.map((path) => {
        const meta = usePageMeta(path);
        return <span key={path}>{meta?.title}</span>;
      })}
    </div>
  );
}
```

## Notes

* Used internally by `SidebarItem` to auto-resolve titles and icons
* Returns `null` if the path doesn't match any defined route
* Resolves from module and resource `meta` properties

## Related

* [SidebarItem](../components/sidebar-item) - Uses usePageMeta internally
* [defineModule](define-module) - Define meta.title and meta.icon

---

---
url: https://docs.tailor.tech/app-shell/api/use-register-command-palette-actions.md
description: Hook for registering contextual page actions into the CommandPalette
---

# useRegisterCommandPaletteActions

React hook that declaratively registers page-level actions into the CommandPalette's **Actions** section. Actions are searchable and triggerable via the `Cmd+K` / `Ctrl+K` shortcut. They are automatically unregistered when the calling component unmounts.

## Import

```tsx
import {
  useRegisterCommandPaletteActions,
  type CommandPaletteAction,
} from "@tailor-platform/app-shell";
```

## Signature

```typescript
function useRegisterCommandPaletteActions(group: string, actions: CommandPaletteAction[]): void;
```

## Parameters

| Parameter | Type                     | Description                                               |
| --------- | ------------------------ | --------------------------------------------------------- |
| `group`   | `string`                 | Display group name shown in the palette for these actions |
| `actions` | `CommandPaletteAction[]` | List of actions to register                               |

## `CommandPaletteAction`

```typescript
type CommandPaletteAction = {
  key: string;
  label: string;
  icon?: ReactNode;
  group?: string;
  onSelect: () => void | Promise<void>;
};
```

| Property   | Type                          | Description                                                                   |
| ---------- | ----------------------------- | ----------------------------------------------------------------------------- |
| `key`      | `string`                      | Unique key for React reconciliation                                           |
| `label`    | `string`                      | Visible label shown in the palette; also used for search matching             |
| `icon`     | `ReactNode`                   | Optional icon rendered next to the label                                      |
| `group`    | `string`                      | Optional group override; defaults to the `group` parameter passed to the hook |
| `onSelect` | `() => void \| Promise<void>` | Callback invoked when the user selects the action                             |

## Usage

```tsx
import { useRegisterCommandPaletteActions } from "@tailor-platform/app-shell";

function OrderDetailPage() {
  const [loading, setLoading] = useState(false);

  const handleConfirm = async () => {
    setLoading(true);
    try {
      await confirmOrder(orderId);
    } finally {
      setLoading(false);
    }
  };

  useRegisterCommandPaletteActions("Order Actions", [
    { key: "confirm", label: "Confirm order", onSelect: handleConfirm },
    { key: "cancel", label: "Cancel order", icon: <XIcon />, onSelect: handleCancel },
  ]);

  return <div>{/* page content */}</div>;
}
```

## Behavior

* Actions are registered while the component is mounted and removed on unmount.
* Re-rendering with a new `actions` array replaces the previously registered set.
* `icon` changes alone do not trigger re-registration. If you need to reflect a dynamic icon update, also change the action's `key` or `label`.
* The hook requires `CommandPaletteProvider`, which is mounted automatically by `AppShell`.

## Related

* [CommandPalette](../components/command-palette) — Keyboard-driven navigation and action palette
* [ActionPanel](../components/action-panel) — Automatically uses this hook to expose its actions in the palette

---

---
url: https://docs.tailor.tech/app-shell/api/use-resolved-locale.md
description: Hook to access the full BCP-47 locale and language code from AppShell context
---

# useResolvedLocale

React hook that returns the full BCP-47 locale (e.g. `"en-GB"`) and the language code (e.g. `"en"`) from the AppShell context. Use this for `Intl` APIs and date formatting that require a specific locale.

## Signature

```typescript
const useResolvedLocale: () => {
  locale: string;
  language: string;
};
```

## Return Value

### `locale`

* **Type:** `string`
* **Description:** Full BCP-47 locale tag (e.g. `"en-GB"`, `"ja-JP"`). Sourced from the `locale` prop passed to `AppShell`, or auto-detected from the browser when omitted.

### `language`

* **Type:** `string`
* **Description:** Language subtag only (e.g. `"en"`, `"ja"`). Used for resolving built-in UI label tables.

## Usage

```typescript
import { useResolvedLocale } from "@tailor-platform/app-shell";

function DateDisplay({ date }: { date: Date }) {
  const { locale } = useResolvedLocale();

  return (
    <span>
      {new Intl.DateTimeFormat(locale, { dateStyle: "long" }).format(date)}
    </span>
  );
}
```

### Locale-aware number formatting

```typescript
function PriceDisplay({ amount }: { amount: number }) {
  const { locale } = useResolvedLocale();

  return (
    <span>
      {new Intl.NumberFormat(locale, { style: "currency", currency: "USD" }).format(amount)}
    </span>
  );
}
```

## Related

* [AppShell](../components/app-shell) — configure locale via the `locale` prop
* [useTimeZone](use-time-zone) — access the configured IANA timezone
* [DatePicker](../components/date-picker) — date input components that consume this locale automatically

---

---
url: https://docs.tailor.tech/app-shell/api/use-route-error.md
description: Hook to access error details in custom error boundaries
---

# useRouteError

React Router hook to access error details within a custom error boundary component. Re-exported from `react-router` for convenience.

## Signature

```typescript
const useRouteError: () => unknown;
```

## Return Value

| Type      | Description                                                                  |
| --------- | ---------------------------------------------------------------------------- |
| `unknown` | The error that was thrown (typically `Error` object or route error response) |

## Usage

### Basic Error Boundary

```typescript
import { useRouteError } from "@tailor-platform/app-shell";

function ErrorBoundary() {
  const error = useRouteError();

  const message = error instanceof Error
    ? error.message
    : "An unexpected error occurred";

  return (
    <div>
      <h1>Something went wrong</h1>
      <p>{message}</p>
      <button onClick={() => window.location.reload()}>
        Try Again
      </button>
    </div>
  );
}
```

### Use in Module Definition

```typescript
import { defineModule } from "@tailor-platform/app-shell";

const myModule = defineModule({
  path: "dashboard",
  component: DashboardPage,
  errorBoundary: <ErrorBoundary />,
  resources: [...]
});
```

### Use in Resource Definition

```typescript
const productsModule = defineModule({
  path: "products",
  component: ProductsPage,
  resources: [
    defineResource({
      path: ":id",
      component: ProductDetail,
      errorBoundary: <ErrorBoundary />,
    }),
  ],
});
```

### Advanced Error Handling

```typescript
import { isRouteErrorResponse, useRouteError } from "@tailor-platform/app-shell";

function ErrorBoundary() {
  const error = useRouteError();

  // Handle route error responses (404, 500, etc.)
  if (isRouteErrorResponse(error)) {
    return (
      <div>
        <h1>{error.status} {error.statusText}</h1>
        <p>{error.data}</p>
      </div>
    );
  }

  // Handle JavaScript errors
  if (error instanceof Error) {
    return (
      <div>
        <h1>Error</h1>
        <p>{error.message}</p>
        <pre>{error.stack}</pre>
      </div>
    );
  }

  // Handle unknown errors
  return (
    <div>
      <h1>Unknown Error</h1>
      <p>Something went wrong</p>
    </div>
  );
}
```

### With Error Logging

```typescript
function ErrorBoundary() {
  const error = useRouteError();

  useEffect(() => {
    // Log to error tracking service
    console.error("Route error:", error);
    // analytics.trackError(error);
  }, [error]);

  return (
    <div>
      <h1>Error</h1>
      <p>We've been notified and will fix this soon.</p>
    </div>
  );
}
```

### Custom Error Pages

```typescript
function ErrorBoundary() {
  const error = useRouteError();

  if (isRouteErrorResponse(error)) {
    if (error.status === 404) {
      return <NotFoundPage />;
    }

    if (error.status === 403) {
      return <AccessDeniedPage />;
    }

    if (error.status === 500) {
      return <ServerErrorPage />;
    }
  }

  return <GenericErrorPage error={error} />;
}
```

## Error Boundary Scope

Error boundaries can be defined at different levels:

```typescript
// Module-level - catches errors in all resources
defineModule({
  path: "products",
  errorBoundary: <ModuleErrorBoundary />,
  resources: [...]
})

// Resource-level - catches errors in specific resource
defineResource({
  path: ":id",
  errorBoundary: <ResourceErrorBoundary />,
  component: ProductDetail
})

// Global - catches all unhandled errors
<AppShell
  modules={modules}
  errorBoundary={<GlobalErrorBoundary />}
/>
```

## Important Notes

### Always Import from AppShell

```typescript
// ✅ Correct
import { useRouteError } from "@tailor-platform/app-shell";

// ❌ Wrong - won't work with AppShell's router
import { useRouteError } from "react-router";
```

### Error Boundaries Don't Catch

Error boundaries do **not** catch:

* Errors in event handlers (use try/catch)
* Async errors (use try/catch with async/await)
* Server-side rendering errors
* Errors thrown in the error boundary itself

## Related

* [defineModule](define-module) - Module-level error boundaries
* [defineResource](define-resource) - Resource-level error boundaries
* [AppShell Component](../components/app-shell) - Global error boundary

---

---
url: https://docs.tailor.tech/app-shell/api/use-theme.md
description: Hook for accessing and controlling theme (light/dark mode)
---

# useTheme

React hook to access and control the current theme (light/dark mode).

## Signature

```typescript
import { type ColorTheme, type ResolvedColorTheme } from "@tailor-platform/app-shell";

const useTheme: () => {
  theme: ColorTheme;
  resolvedTheme: ResolvedColorTheme;
  setTheme: (theme: ColorTheme) => void;
};
```

## Return Value

### `theme`

* **Type:** `ColorTheme` (`"light" | "dark" | "system"`)
* **Description:** Current user preference. `"system"` means the OS setting is followed.

### `resolvedTheme`

* **Type:** `ResolvedColorTheme` (`"light" | "dark"`)
* **Description:** Concrete color mode after resolving `"system"`. Always `"light"` or `"dark"`.

### `setTheme()`

* **Type:** `(theme: ColorTheme) => void`
* **Description:** Set the color theme. Persisted to `localStorage` under the key `appshell-ui-theme`.

## Usage

### Display Current Theme

```typescript
import { useTheme } from "@tailor-platform/app-shell";

function ThemeDisplay() {
  const { theme } = useTheme();

  return <div>Current theme: {theme}</div>;
}
```

### Theme Toggle

```typescript
function ThemeToggle() {
  const { theme, setTheme } = useTheme();

  const toggleTheme = () => {
    setTheme(theme === "dark" ? "light" : "dark");
  };

  return <button onClick={toggleTheme}>Toggle Theme</button>;
}
```

### Theme Selector

```typescript
function ThemeSelector() {
  const { theme, setTheme } = useTheme();

  return (
    <select value={theme} onChange={(e) => setTheme(e.target.value)}>
      <option value="light">Light</option>
      <option value="dark">Dark</option>
      <option value="system">System</option>
    </select>
  );
}
```

### Conditional Rendering

Use `resolvedTheme` when you need a concrete `"light"` or `"dark"` value — it already accounts for `"system"`:

```typescript
function Logo() {
  const { resolvedTheme } = useTheme();

  return (
    <img
      src={resolvedTheme === "dark" ? "/logo-dark.png" : "/logo-light.png"}
      alt="Logo"
    />
  );
}
```

## Theme Persistence

Theme preference is automatically saved to localStorage and restored on page load.

## Related

* [Styling & Theming](../concepts/styling-theming) - Theme customization

---

---
url: https://docs.tailor.tech/app-shell/api/use-time-zone.md
description: Hook to access the configured IANA timezone from AppShell context
---

# useTimeZone

React hook that returns a `TimeZone` object for the timezone configured on `AppShell`. Falls back to the user's local timezone when no timezone is configured.

Date/time components (`DateField`, `DatePicker`, `Calendar`) consume this hook automatically — use it when you need the same timezone in custom components.

## Signature

```typescript
const useTimeZone: () => TimeZone;
```

## Return Value

A `TimeZone` object with the following properties:

### `value`

* **Type:** `string`
* **Description:** Raw IANA timezone identifier (e.g. `"America/Los_Angeles"`). Returns the value of AppShell's `timeZone` prop when configured, or the result of `getLocalTimeZone()` (the user's local timezone) when not.

### `today()`

* **Type:** `() => CalendarDate`
* **Description:** Returns today's date in this timezone.

### `now()`

* **Type:** `() => ZonedDateTime`
* **Description:** Returns the current instant in this timezone.

## Usage

```typescript
import { useTimeZone } from "@tailor-platform/app-shell";

function TodayDisplay() {
  const timeZone = useTimeZone();
  const todayDate = timeZone.today();

  return <span>Today: {todayDate.toString()}</span>;
}
```

### Current timestamp

```typescript
import { useTimeZone } from "@tailor-platform/app-shell";

function CurrentTimestamp() {
  const timeZone = useTimeZone();

  return <span>{timeZone.now().toString()}</span>;
}
```

### Accessing the raw IANA string

```typescript
import { useTimeZone } from "@tailor-platform/app-shell";

function TimeZoneLabel() {
  const { value } = useTimeZone();

  return <span>Timezone: {value}</span>;
}
```

## Related

* [AppShell](../components/app-shell) — configure timezone via the `timeZone` prop
* [useResolvedLocale](use-resolved-locale) — access the locale for formatting
* [DatePicker](../components/date-picker) — date input components that consume this timezone automatically

---

---
url: https://docs.tailor.tech/app-shell/api/use-toast.md
description: Hook for displaying toast notifications
---

# useToast

React hook to display toast notifications for user feedback.

## Signature

```typescript
const useToast: () => {
  toast: (props: ToastProps) => void;
};
```

## Parameters

### ToastProps

```typescript
{
  title?: string;
  description?: string;
  variant?: "default" | "success" | "error" | "warning";
  duration?: number; // milliseconds
}
```

## Usage

### Basic Toast

```typescript
import { useToast } from "@tailor-platform/app-shell";

function SaveButton() {
  const { toast } = useToast();

  const handleSave = () => {
    // Save logic...
    toast({
      title: "Saved!",
      description: "Your changes have been saved.",
    });
  };

  return <button onClick={handleSave}>Save</button>;
}
```

### Success Toast

```typescript
function CreateButton() {
  const { toast } = useToast();

  const handleCreate = async () => {
    await createItem();
    toast({
      title: "Created",
      description: "Item created successfully.",
      variant: "success",
    });
  };

  return <button onClick={handleCreate}>Create</button>;
}
```

### Error Toast

```typescript
function DeleteButton() {
  const { toast } = useToast();

  const handleDelete = async () => {
    try {
      await deleteItem();
    } catch (error) {
      toast({
        title: "Error",
        description: error.message,
        variant: "error",
      });
    }
  };

  return <button onClick={handleDelete}>Delete</button>;
}
```

### Custom Duration

```typescript
toast({
  title: "Processing...",
  duration: 5000, // 5 seconds
});
```

## Related

* [SidebarLayout](../components/sidebar-layout) - Toast provider included

---

---
url: https://docs.tailor.tech/app-shell/api/guards/overview.md
description: Access control system for routes and components using guard functions
---

# Guards Overview

Guards are functions that control access to routes and UI elements in AppShell. They provide a flexible, composable way to implement permission-based and role-based access control.

## How Guards Work

Guards are executed sequentially and can return one of three results:

* **`pass()`** - Allow access, continue to next guard
* **`hidden()`** - Deny access, return 404
* **`redirectTo(path)`** - Redirect to another page

If any guard returns `hidden()` or `redirectTo()`, execution stops immediately.

## Guard Function Signature

```typescript
type Guard = (ctx: GuardContext) => GuardResult | Promise<GuardResult>;

type GuardContext = {
  context: ContextData; // Your custom context from AppShell
};

type GuardResult = { type: "pass" } | { type: "hidden" } | { type: "redirect"; to: string };
```

## Guard Functions

### pass()

Allows access and continues to the next guard.

```typescript
import { pass } from "@tailor-platform/app-shell";

const allowAll: Guard = () => pass();
```

[Full Reference →](pass)

### hidden()

Denies access and shows 404 Not Found.

```typescript
import { hidden } from "@tailor-platform/app-shell";

const denyAll: Guard = () => hidden();
```

[Full Reference →](hidden)

### redirectTo(path)

Redirects to another page.

```typescript
import { redirectTo } from "@tailor-platform/app-shell";

const redirectToLogin: Guard = () => redirectTo("/login");
```

[Full Reference →](redirect-to)

## Usage Locations

### Route-Level Guards

Applied to modules and resources:

```typescript
import { defineModule, pass, hidden } from "@tailor-platform/app-shell";

const adminModule = defineModule({
  path: "admin",
  component: AdminPage,
  guards: [
    ({ context }) => {
      return context.currentUser?.role === "admin" ? pass() : hidden();
    },
  ],
});
```

### Component-Level Guards

Applied to UI elements with `WithGuard`:

```typescript
import { WithGuard, pass, hidden } from "@tailor-platform/app-shell";

const isAdmin = ({ context }) =>
  context.currentUser?.role === "admin" ? pass() : hidden();

<WithGuard guards={[isAdmin]}>
  <Button>Delete All</Button>
</WithGuard>
```

## Context Data

Guards receive context data from AppShell:

```typescript
// Define your context type
declare module "@tailor-platform/app-shell" {
  interface AppShellRegister {
    contextData: {
      currentUser: User | null;
      permissions: string[];
      featureFlags: FeatureFlags;
    };
  }
}

// Pass context to AppShell
<AppShell
  modules={modules}
  contextData={{
    currentUser,
    permissions,
    featureFlags,
  }}
>
  {/* ... */}
</AppShell>

// Access in guards
const guard: Guard = ({ context }) => {
  // context is fully typed!
  if (context.currentUser) {
    return pass();
  }
  return hidden();
};
```

## Common Patterns

### Authentication Check

```typescript
const requireAuth: Guard = ({ context }) => {
  if (!context.currentUser) {
    return redirectTo("/login");
  }
  return pass();
};
```

### Role-Based Access

```typescript
const requireAdmin: Guard = ({ context }) => {
  if (context.currentUser?.role !== "admin") {
    return hidden();
  }
  return pass();
};
```

### Permission-Based Access

```typescript
const requirePermission =
  (permission: string): Guard =>
  ({ context }) => {
    if (!context.permissions.includes(permission)) {
      return hidden();
    }
    return pass();
  };

// Usage
guards: [requirePermission("users:delete")];
```

### Feature Flags

```typescript
const requireFeature =
  (flag: string): Guard =>
  ({ context }) => {
    if (!context.featureFlags[flag]) {
      return hidden();
    }
    return pass();
  };
```

### Async Permission Check

```typescript
const checkApiPermission: Guard = async ({ context }) => {
  const response = await fetch("/api/permissions/admin");
  const { allowed } = await response.json();
  return allowed ? pass() : hidden();
};
```

### Multiple Guards (AND logic)

```typescript
const guards = [requireAuth, requireAdmin, requireFeature("beta")];

// All must pass() for access to be granted
defineModule({
  path: "admin",
  guards: guards,
});
```

### Reusable Guard Library

```typescript
// guards.ts
export const requireAuth: Guard = ({ context }) => {
  return context.currentUser ? pass() : redirectTo("/login");
};

export const requireRole =
  (role: string): Guard =>
  ({ context }) => {
    return context.currentUser?.role === role ? pass() : hidden();
  };

export const requirePermission =
  (perm: string): Guard =>
  ({ context }) => {
    return context.permissions.includes(perm) ? pass() : hidden();
  };

// Usage across application
import { requireAuth, requireRole } from "./guards";

defineModule({
  path: "admin",
  guards: [requireAuth, requireRole("admin")],
});
```

## Guard Execution Order

Guards are executed sequentially in the order they're defined:

```typescript
guards: [guardA, guardB, guardC];

// Execution:
// 1. guardA runs → if not pass(), stop
// 2. guardB runs → if not pass(), stop
// 3. guardC runs → if not pass(), stop
// 4. All passed → grant access
```

## Navigation Behavior

When guards return `hidden()`:

* Route returns 404 Not Found
* Item hidden from sidebar navigation
* Item hidden from CommandPalette
* Breadcrumbs don't show the page

When guards return `redirectTo()`:

* User is redirected immediately
* Original URL is not accessible
* Useful for login flows

## Best Practices

### Do:

* ✅ Keep guards simple and focused
* ✅ Reuse guards across routes and components
* ✅ Use descriptive names (requireAuth, not guard1)
* ✅ Return quickly for better performance
* ✅ Cache expensive checks when possible

### Don't:

* ❌ Make guards too complex (extract logic)
* ❌ Have side effects in guards (logging OK)
* ❌ Duplicate guard logic (DRY principle)
* ❌ Forget to handle async errors
* ❌ Use redirectTo() in WithGuard (not supported)

## TypeScript

Full type safety:

```typescript
import { type Guard, type GuardContext, type GuardResult } from "@tailor-platform/app-shell";

const myGuard: Guard = (ctx: GuardContext): GuardResult => {
  // Fully typed context
  return pass();
};

// Async guard
const asyncGuard: Guard = async (ctx): Promise<GuardResult> => {
  await someAsyncCheck();
  return pass();
};
```

## Performance

### Sync Guards (Fast)

```typescript
const isAdmin: Guard = ({ context }) => {
  return context.currentUser?.role === "admin" ? pass() : hidden();
};
// ~0ms - Instant
```

### Async Guards (Slower)

```typescript
const checkPermission: Guard = async ({ context }) => {
  const allowed = await fetch("/api/check");
  return allowed ? pass() : hidden();
};
// ~50-200ms - Network request
```

**Tip:** Prefer sync guards when possible. Cache API results in context data.

## Comparison: Route vs Component Guards

| Aspect                    | Route Guards                | Component Guards (WithGuard) |
| ------------------------- | --------------------------- | ---------------------------- |
| **Location**              | defineModule/defineResource | WithGuard component          |
| **Supports pass()**       | ✅ Yes                      | ✅ Yes                       |
| **Supports hidden()**     | ✅ Yes                      | ✅ Yes                       |
| **Supports redirectTo()** | ✅ Yes                      | ❌ No                        |
| **Execution**             | Before route loads          | During render                |
| **Use Case**              | Page access control         | UI element visibility        |

## Related

* [pass()](pass) - Allow access guard function
* [hidden()](hidden) - Hide/deny access guard function
* [redirectTo()](redirect-to) - Redirect guard function
* [WithGuard Component](../../components/with-guard) - Component-level guards

---

---
url: https://docs.tailor.tech/app-shell/api/guards/hidden.md
description: Guard function that denies access and returns 404 Not Found
---

# hidden()

Returns a guard result that denies access and makes the route return 404 Not Found. The route is also hidden from navigation and search.

## Signature

```typescript
function hidden(): GuardResult;
```

## Return Type

```typescript
{
  type: "hidden";
}
```

## Usage

```typescript
import { hidden, type Guard } from "@tailor-platform/app-shell";

const denyAccess: Guard = () => {
  return hidden();
};
```

## When to Use

Use `hidden()` when:

* ✅ Access should be denied
* ✅ User doesn't have required permissions
* ✅ You want to hide the page completely (404)
* ✅ Feature is not available for current user

## Effects

When `hidden()` is returned:

* 🚫 Route returns **404 Not Found**
* 🚫 Hidden from **sidebar navigation**
* 🚫 Hidden from **CommandPalette** search
* 🚫 Not shown in **breadcrumbs**
* 🚫 Direct URL access returns 404

## Examples

### Deny All Access

```typescript
const denyAll: Guard = () => hidden();
```

### Role-Based Hiding

```typescript
const adminOnly: Guard = ({ context }) => {
  if (context.currentUser?.role !== "admin") {
    return hidden(); // Non-admins see 404
  }
  return pass();
};
```

### Permission-Based Hiding

```typescript
const requirePermission =
  (perm: string): Guard =>
  ({ context }) => {
    if (!context.permissions.includes(perm)) {
      return hidden(); // No permission → 404
    }
    return pass();
  };
```

### Feature Flag

```typescript
const requireBetaFeature: Guard = ({ context }) => {
  if (!context.featureFlags?.beta) {
    return hidden(); // Feature disabled → 404
  }
  return pass();
};
```

### Subscription Tier

```typescript
const premiumOnly: Guard = ({ context }) => {
  if (context.currentUser?.plan !== "premium") {
    return hidden(); // Free users see 404
  }
  return pass();
};
```

### Conditional Hiding

```typescript
const conditionalHide: Guard = ({ context }) => {
  // Multiple conditions
  if (!context.currentUser || context.currentUser.suspended || !context.currentUser.emailVerified) {
    return hidden();
  }
  return pass();
};
```

### Async Permission Check

```typescript
const asyncHide: Guard = async ({ context }) => {
  const allowed = await fetch("/api/check-access");
  if (!allowed) {
    return hidden();
  }
  return pass();
};
```

## vs redirectTo()

| Aspect         | hidden()             | redirectTo()             |
| -------------- | -------------------- | ------------------------ |
| **Result**     | 404 Not Found        | Redirect to page         |
| **URL**        | Stays same           | Changes to new URL       |
| **Navigation** | Hidden               | Not affected             |
| **Use Case**   | Deny access silently | Send to login/error page |

### Example: When to Use Each

```typescript
// Use hidden() - Silently deny access
const adminFeature: Guard = ({ context }) => {
  if (!isAdmin(context)) {
    return hidden(); // Non-admins don't even see this exists
  }
  return pass();
};

// Use redirectTo() - Explicitly redirect
const requireAuth: Guard = ({ context }) => {
  if (!context.currentUser) {
    return redirectTo("/login"); // Unauthenticated users go to login
  }
  return pass();
};
```

## Navigation Impact

```typescript
// Before guard (user is not admin):
Sidebar:
› Dashboard
› Products
› Admin Panel  ← Visible

// After guard returns hidden():
Sidebar:
› Dashboard
› Products
               ← Admin Panel disappeared

// Direct URL access: /admin
// Result: 404 Not Found
```

## WithGuard Component

`hidden()` works with `WithGuard` to hide UI elements:

```typescript
import { WithGuard, hidden, pass } from "@tailor-platform/app-shell";

const isAdmin = ({ context }) =>
  context.currentUser?.role === "admin" ? pass() : hidden();

<WithGuard guards={[isAdmin]}>
  <Button>Delete All Users</Button>
</WithGuard>
// Non-admins: button doesn't render
```

## Related

* [pass()](pass) - Allow access and continue
* [redirectTo()](redirect-to) - Redirect to another page
* [Guards Overview](overview) - Complete guard system guide
* [WithGuard Component](../../components/with-guard) - Component-level guards

---

---
url: https://docs.tailor.tech/app-shell/api/guards/pass.md
description: Guard function that allows access and continues to the next guard
---

# pass()

Returns a guard result that allows access and continues to the next guard in the chain.

## Signature

```typescript
function pass(): GuardResult;
```

## Return Type

```typescript
{
  type: "pass";
}
```

## Usage

```typescript
import { pass, type Guard } from "@tailor-platform/app-shell";

const allowAccess: Guard = () => {
  return pass();
};
```

## When to Use

Use `pass()` when:

* ✅ Access should be granted
* ✅ User meets the required conditions
* ✅ You want to continue to the next guard

## Examples

### Always Allow

```typescript
const allowAll: Guard = () => pass();
```

### Conditional Access

```typescript
const requireAuth: Guard = ({ context }) => {
  if (context.currentUser) {
    return pass(); // User is authenticated
  }
  return redirectTo("/login");
};
```

### Role Check

```typescript
const requireAdmin: Guard = ({ context }) => {
  if (context.currentUser?.role === "admin") {
    return pass(); // User is admin
  }
  return hidden();
};
```

### Permission Check

```typescript
const requirePermission =
  (perm: string): Guard =>
  ({ context }) => {
    if (context.permissions.includes(perm)) {
      return pass(); // User has permission
    }
    return hidden();
  };
```

### Multiple Conditions

```typescript
const complexGuard: Guard = ({ context }) => {
  // Check multiple conditions
  if (context.currentUser && context.currentUser.active && !context.currentUser.suspended) {
    return pass(); // All conditions met
  }
  return hidden();
};
```

### Async Guard

```typescript
const asyncGuard: Guard = async ({ context }) => {
  const isValid = await validateToken(context.token);
  if (isValid) {
    return pass();
  }
  return redirectTo("/login");
};
```

## Guard Chaining

When `pass()` is returned, the next guard in the array executes:

```typescript
guards: [
  guardA, // Returns pass() → Continue to guardB
  guardB, // Returns pass() → Continue to guardC
  guardC, // Returns pass() → Grant access
];
```

If all guards return `pass()`, access is granted.

## Related

* [hidden()](hidden) - Deny access and return 404
* [redirectTo()](redirect-to) - Redirect to another page
* [Guards Overview](overview) - Complete guard system guide

---

---
url: https://docs.tailor.tech/app-shell/api/guards/redirect-to.md
description: Guard function that redirects to another page
---

# redirectTo()

Returns a guard result that redirects the user to a different URL. Used primarily for authentication flows and access control redirection.

## Signature

```typescript
function redirectTo(to: string): GuardResult;
```

## Parameters

### `to`

* **Type:** `string`
* **Required:** Yes
* **Description:** Target URL path to redirect to

## Return Type

```typescript
{
  type: "redirect";
  to: string;
}
```

## Usage

```typescript
import { redirectTo, type Guard } from "@tailor-platform/app-shell";

const redirectToLogin: Guard = () => {
  return redirectTo("/login");
};
```

## When to Use

Use `redirectTo()` when:

* ✅ User needs authentication (redirect to login)
* ✅ User needs to complete setup (redirect to onboarding)
* ✅ Access denied but you want to show why (redirect to error page)
* ✅ You want explicit navigation vs silent denial

## Examples

### Require Authentication

```typescript
const requireAuth: Guard = ({ context }) => {
  if (!context.currentUser) {
    return redirectTo("/login");
  }
  return pass();
};
```

### Subscription Required

```typescript
const requirePremium: Guard = ({ context }) => {
  if (context.currentUser?.plan !== "premium") {
    return redirectTo("/upgrade");
  }
  return pass();
};
```

### Complete Profile

```typescript
const requireProfile: Guard = ({ context }) => {
  if (!context.currentUser?.profileComplete) {
    return redirectTo("/complete-profile");
  }
  return pass();
};
```

### Email Verification

```typescript
const requireVerifiedEmail: Guard = ({ context }) => {
  if (!context.currentUser?.emailVerified) {
    return redirectTo("/verify-email");
  }
  return pass();
};
```

### Terms Acceptance

```typescript
const requireTerms: Guard = ({ context }) => {
  if (!context.currentUser?.termsAccepted) {
    return redirectTo("/accept-terms");
  }
  return pass();
};
```

### Role-Based Redirect

```typescript
const redirectNonAdmins: Guard = ({ context }) => {
  if (context.currentUser?.role !== "admin") {
    return redirectTo("/access-denied");
  }
  return pass();
};
```

### Conditional Redirect

```typescript
const conditionalRedirect: Guard = ({ context }) => {
  const user = context.currentUser;

  if (!user) {
    return redirectTo("/login");
  }

  if (user.suspended) {
    return redirectTo("/account-suspended");
  }

  if (!user.onboardingComplete) {
    return redirectTo("/onboarding");
  }

  return pass();
};
```

### Async Redirect

```typescript
const asyncRedirect: Guard = async ({ context }) => {
  const status = await fetch("/api/user-status");
  const { active } = await status.json();

  if (!active) {
    return redirectTo("/reactivate");
  }

  return pass();
};
```

## vs hidden()

| Aspect                | redirectTo()             | hidden()                |
| --------------------- | ------------------------ | ----------------------- |
| **Result**            | Redirect to URL          | 404 Not Found           |
| **User Experience**   | Clear (shows why denied) | Silent (no explanation) |
| **URL Changes**       | Yes                      | No                      |
| **Navigation Impact** | No effect                | Hides from navigation   |
| **Use Case**          | Login flows, errors      | Permission hiding       |

### Example: When to Use Each

```typescript
// Use redirectTo() - User needs to take action
const requireAuth: Guard = ({ context }) => {
  if (!context.currentUser) {
    return redirectTo("/login"); // Clear: "You need to log in"
  }
  return pass();
};

// Use hidden() - Feature doesn't exist for user
const adminFeature: Guard = ({ context }) => {
  if (!isAdmin(context)) {
    return hidden(); // Silent: User doesn't even know this exists
  }
  return pass();
};
```

## Redirect Chains

Guards can create redirect chains:

```typescript
const guards = [
  // 1. Check authentication
  ({ context }) => {
    if (!context.currentUser) {
      return redirectTo("/login");
    }
    return pass();
  },
  // 2. Check onboarding (only runs if authenticated)
  ({ context }) => {
    if (!context.currentUser?.onboardingComplete) {
      return redirectTo("/onboarding");
    }
    return pass();
  },
  // 3. Check permissions (only runs if onboarded)
  ({ context }) => {
    if (!context.currentUser?.hasAccess) {
      return redirectTo("/upgrade");
    }
    return pass();
  },
];
```

## Module vs Resource Redirects

### Module-Level

```typescript
const dashboardModule = defineModule({
  path: "dashboard",
  component: DashboardPage,
  guards: [
    ({ context }) => {
      if (!context.currentUser) {
        return redirectTo("/login");
      }
      return pass();
    },
  ],
});

// Accessing /dashboard without auth → Redirects to /login
```

### Resource-Level

```typescript
const settingsResource = defineResource({
  path: "settings",
  component: SettingsPage,
  guards: [
    ({ context }) => {
      if (!context.currentUser?.emailVerified) {
        return redirectTo("/verify-email");
      }
      return pass();
    },
  ],
});

// Accessing /settings without verified email → Redirects to /verify-email
```

## Limitations

### Not Supported in WithGuard

`redirectTo()` does **NOT** work with the `WithGuard` component:

```typescript
// ❌ NOT SUPPORTED
<WithGuard
  guards={[
    () => redirectTo("/login") // This won't work!
  ]}
>
  <Content />
</WithGuard>

// ✅ Use hidden() with fallback instead
<WithGuard
  guards={[() => hidden()]}
  fallback={<Navigate to="/login" />}
>
  <Content />
</WithGuard>
```

## Preserving Original URL

To preserve the original URL after redirect:

```typescript
const requireAuth: Guard = ({ context }) => {
  if (!context.currentUser) {
    const currentPath = window.location.pathname;
    return redirectTo(`/login?redirect=${encodeURIComponent(currentPath)}`);
  }
  return pass();
};

// After login, redirect back:
// const redirect = searchParams.get('redirect');
// if (redirect) navigate(redirect);
```

## Related

* [pass()](pass) - Allow access and continue
* [hidden()](hidden) - Deny access and return 404
* [Guards Overview](overview) - Complete guard system guide
* [WithGuard Component](../../components/with-guard) - Component-level guards (doesn't support redirectTo)

---

---
url: https://docs.tailor.tech/app-shell/api/router/use-location.md
description: Hook to access current location object with pathname, search, and state
---

# useLocation

React Router hook to access the current location object. Re-exported from `react-router` for convenience.

## Signature

```typescript
const useLocation: () => Location;
```

## Return Type

```typescript
interface Location {
  pathname: string; // Current path: "/products/123"
  search: string; // Query string: "?sort=name&page=2"
  hash: string; // Hash: "#details"
  state: any; // State passed via navigate()
  key: string; // Unique key for this location
}
```

## Usage

### Access Current Path

```typescript
import { useLocation } from "@tailor-platform/app-shell";

function Breadcrumb() {
  const location = useLocation();

  return <div>Current path: {location.pathname}</div>;
}
```

### Check Active Route

```typescript
function NavItem({ path, label }: { path: string; label: string }) {
  const location = useLocation();
  const isActive = location.pathname === path;

  return (
    <a
      href={path}
      className={isActive ? "active" : ""}
    >
      {label}
    </a>
  );
}
```

### Access Query Parameters

```typescript
function ProductsList() {
  const location = useLocation();
  const searchParams = new URLSearchParams(location.search);

  const sort = searchParams.get("sort"); // "name"
  const page = searchParams.get("page"); // "2"

  return <div>Sort: {sort}, Page: {page}</div>;
}

// URL: /products?sort=name&page=2
```

### Access Navigation State

```typescript
// Navigate with state
function ProductsList() {
  const navigate = useNavigate();

  const selectProduct = (id: string) => {
    navigate(`/products/${id}`, {
      state: { from: "list", scrollPosition: window.scrollY },
    });
  };
}

// Access state in target component
function ProductDetail() {
  const location = useLocation();
  const from = location.state?.from;           // "list"
  const scrollPos = location.state?.scrollPosition; // 450

  return <div>Came from: {from}</div>;
}
```

### Track Route Changes

```typescript
function AnalyticsTracker() {
  const location = useLocation();

  useEffect(() => {
    // Track page view
    analytics.pageView(location.pathname);
  }, [location.pathname]);

  return null;
}
```

### Preserve Query Params on Navigation

```typescript
function FilterButton({ filter }: { filter: string }) {
  const location = useLocation();
  const navigate = useNavigate();

  const applyFilter = () => {
    const params = new URLSearchParams(location.search);
    params.set("filter", filter);
    navigate(`${location.pathname}?${params}`);
  };

  return <button onClick={applyFilter}>Apply Filter</button>;
}
```

## Common Patterns

### Check Prefix Match

```typescript
function isActiveRoute(pathname: string, prefix: string) {
  return pathname.startsWith(prefix);
}

function NavItem({ path }: { path: string }) {
  const location = useLocation();
  const isActive = isActiveRoute(location.pathname, path);

  return <a className={isActive ? "active" : ""}>{path}</a>;
}
```

### Scroll to Hash

```typescript
function ScrollToHash() {
  const location = useLocation();

  useEffect(() => {
    if (location.hash) {
      const element = document.querySelector(location.hash);
      element?.scrollIntoView({ behavior: "smooth" });
    }
  }, [location.hash]);

  return null;
}
```

### Preserve Scroll Position

```typescript
function Layout() {
  const location = useLocation();
  const scrollPositions = useRef<Record<string, number>>({});

  useEffect(() => {
    // Save scroll position
    scrollPositions.current[location.key] = window.scrollY;

    // Restore scroll position
    const savedPosition = scrollPositions.current[location.key];
    if (savedPosition !== undefined) {
      window.scrollTo(0, savedPosition);
    }
  }, [location]);

  return <Outlet />;
}
```

## useSearchParams Alternative

For easier query parameter handling, use `useSearchParams`:

```typescript
import { useSearchParams } from "@tailor-platform/app-shell";

function ProductsList() {
  const [searchParams, setSearchParams] = useSearchParams();

  const sort = searchParams.get("sort");
  const page = searchParams.get("page");

  const updateSort = (newSort: string) => {
    setSearchParams({ sort: newSort, page });
  };

  return <div>...</div>;
}
```

## Important Notes

### Always Import from AppShell

```typescript
// ✅ Correct
import { useLocation } from "@tailor-platform/app-shell";

// ❌ Wrong - won't work with AppShell's router
import { useLocation } from "react-router";
```

### Location is Immutable

The location object is immutable. Don't try to modify it:

```typescript
// ❌ Wrong
location.pathname = "/new-path";

// ✅ Correct - use navigate
navigate("/new-path");
```

## Related

* [useNavigate](use-navigate) - Programmatic navigation
* [useParams](use-params) - Access route parameters
* [useSearchParams](use-navigate) - Query parameter management
* [Routing & Navigation](../../concepts/routing-navigation) - Navigation guide

---

---
url: https://docs.tailor.tech/app-shell/api/router/use-navigate.md
description: Hook for programmatic navigation between routes
---

# useNavigate

React Router hook for programmatic navigation. Re-exported from `react-router` for convenience.

## Signature

```typescript
const useNavigate: () => (to: string | number, options?: NavigateOptions) => void;
```

## Usage

### Navigate to Path

```typescript
import { useNavigate } from "@tailor-platform/app-shell";

function MyComponent() {
  const navigate = useNavigate();

  const goToProducts = () => {
    navigate("/products");
  };

  return <button onClick={goToProducts}>View Products</button>;
}
```

### Navigate with Dynamic Parameters

```typescript
function ProductCard({ id }: { id: string }) {
  const navigate = useNavigate();

  const viewDetails = () => {
    navigate(`/products/${id}`);
  };

  return <button onClick={viewDetails}>Details</button>;
}
```

### Navigate Back

```typescript
function BackButton() {
  const navigate = useNavigate();

  return <button onClick={() => navigate(-1)}>Back</button>;
}
```

### Navigate Forward

```typescript
function ForwardButton() {
  const navigate = useNavigate();

  return <button onClick={() => navigate(1)}>Forward</button>;
}
```

### Replace Current Entry

```typescript
function LoginSuccess() {
  const navigate = useNavigate();

  useEffect(() => {
    // Replace current history entry (user can't go back to login)
    navigate("/dashboard", { replace: true });
  }, []);

  return <div>Redirecting...</div>;
}
```

### Navigate with State

```typescript
function ProductsList() {
  const navigate = useNavigate();

  const selectProduct = (product: Product) => {
    navigate(`/products/${product.id}`, {
      state: { from: "list" },
    });
  };

  return <ProductList onSelect={selectProduct} />;
}

// Access state in target component
function ProductDetail() {
  const location = useLocation();
  const from = location.state?.from; // "list"
}
```

## NavigateOptions

```typescript
interface NavigateOptions {
  replace?: boolean; // Replace current entry instead of pushing
  state?: any; // Pass state to target route
  preventScrollReset?: boolean;
  relative?: "route" | "path";
}
```

## Important Notes

### Import from AppShell

Always import from `@tailor-platform/app-shell`, not `react-router`:

```typescript
// ✅ Correct
import { useNavigate } from "@tailor-platform/app-shell";

// ❌ Wrong - won't work with AppShell's router
import { useNavigate } from "react-router";
```

This ensures you're using AppShell's router instance.

## Related

* [useParams](use-params) - Access route parameters
* [useLocation](use-location) - Access current location
* [Routing & Navigation](../../concepts/routing-navigation) - Navigation guide, including the `Navigate` component for declarative redirects

---

---
url: https://docs.tailor.tech/app-shell/api/router/use-params.md
description: Hook to access dynamic route parameters
---

# useParams

React Router hook to access dynamic route parameters from the URL. Re-exported from `react-router` for convenience.

## Signature

```typescript
const useParams: <T extends Record<string, string>>() => T;
```

## Usage

### Access Single Parameter

```typescript
import { useParams } from "@tailor-platform/app-shell";

// Route: /products/:id
function ProductDetail() {
  const { id } = useParams();

  return <div>Product ID: {id}</div>;
}
```

### Multiple Parameters

```typescript
// Route: /categories/:category/products/:id
function ProductInCategory() {
  const { category, id } = useParams();

  return (
    <div>
      Category: {category}
      <br />
      Product ID: {id}
    </div>
  );
}
```

### With Data Fetching

```typescript
function OrderDetail() {
  const { id } = useParams();
  const [order, setOrder] = useState(null);

  useEffect(() => {
    fetch(`/api/orders/${id}`)
      .then(r => r.json())
      .then(setOrder);
  }, [id]);

  return <div>Order #{id}</div>;
}
```

### TypeScript with Type Safety

```typescript
import { useParams } from "@tailor-platform/app-shell";

interface ProductParams {
  id: string;
}

function ProductDetail() {
  const { id } = useParams<ProductParams>();
  //    ^ type: string

  return <div>Product {id}</div>;
}
```

## Route Definition

Parameters are defined in `defineResource` using `:param` syntax:

```typescript
import { defineModule, defineResource } from "@tailor-platform/app-shell";

const productsModule = defineModule({
  path: "products",
  component: ProductsList,
  resources: [
    defineResource({
      path: ":id", // ← Dynamic parameter
      component: () => {
        const { id } = useParams(); // Access here
        return <div>Product {id}</div>;
      },
    }),
  ],
});
```

### Nested Parameters

```typescript
const ordersModule = defineModule({
  path: "orders",
  component: OrdersList,
  resources: [
    defineResource({
      path: ":orderId",
      component: OrderDetail,
      subResources: [
        defineResource({
          path: "items/:itemId",
          component: () => {
            const { orderId, itemId } = useParams();
            return <div>Order {orderId}, Item {itemId}</div>;
          },
        }),
      ],
    }),
  ],
});

// URL: /orders/123/items/456
// useParams() returns: { orderId: "123", itemId: "456" }
```

## Important Notes

### Always Import from AppShell

```typescript
// ✅ Correct
import { useParams } from "@tailor-platform/app-shell";

// ❌ Wrong - won't work with AppShell's router
import { useParams } from "react-router";
```

### Parameters are Always Strings

```typescript
const { id } = useParams();
// id is always a string, even for numeric IDs

// Convert if needed:
const numericId = parseInt(id, 10);
```

### Optional Parameters

For optional parameters, check for undefined:

```typescript
const { filter } = useParams();

if (filter) {
  // Filter is provided
} else {
  // Filter is optional and not provided
}
```

## Examples

### Edit Page

```typescript
// Route: /products/:id/edit
function ProductEdit() {
  const { id } = useParams();
  const [product, setProduct] = useState(null);

  useEffect(() => {
    loadProduct(id).then(setProduct);
  }, [id]);

  return (
    <form>
      <h1>Edit Product {id}</h1>
      {/* form fields */}
    </form>
  );
}
```

### Delete Confirmation

```typescript
function DeleteConfirmation() {
  const { id } = useParams();
  const navigate = useNavigate();

  const handleDelete = async () => {
    await deleteProduct(id);
    navigate("/products");
  };

  return (
    <div>
      <p>Delete product {id}?</p>
      <button onClick={handleDelete}>Confirm</button>
    </div>
  );
}
```

## Related

* [useNavigate](use-navigate) - Programmatic navigation
* [useLocation](use-location) - Access current location
* [defineResource](../define-resource) - Define routes with parameters
* [Routing & Navigation](../../concepts/routing-navigation) - Navigation guide

---

---
url: https://docs.tailor.tech/getting-started.md
---
# Getting Started

Getting started with the Tailor Platform is fast and straightforward. Tailor Platform offers powerful tools, such as the CLI and [console](https://console.tailor.tech), that simplify the process of creating and managing your applications.

## Console

The Console is Tailor Platform’s web interface, providing you with access to enhanced development capabilities.

Start by creating a workspace and deploying an application using the [templates](https://github.com/tailor-platform/templates).
You can explore and analyze data models, visualize pipelines, and use the interactive playground to run queries with ease.

Here is a quick look at the console.

![Tailor Console](./assets/console-application-overview.png)

## Tailor Platform SDK

The `tailor` is the command-line interface for building, deploying, and managing applications on the Tailor Platform. It provides a comprehensive set of tools for working with TailorDB, Functions, Workflows and Auth.

### Installation

The Tailor Platform SDK requires Node.js 22 or later. You can use it in three ways:

**1. With npx (recommended for quick start):**

```bash
npx @tailor-platform/sdk --version
```

**2. As a project dependency:**

```bash
npm install --save-dev @tailor-platform/sdk
# or
pnpm add -D @tailor-platform/sdk
```

**3. Global installation:**

```bash
npm install -g @tailor-platform/sdk
```

### Key Commands

The SDK provides commands for all aspects of application development:

* **[Application Commands](/sdk/cli/application)** - Initialize projects, deploy apps, and manage configurations
* **[TailorDB Commands](/sdk/cli/tailordb)** - Manage database schema, migrations, and data
* **[Workflow Commands](/sdk/cli/workflow)** - Create and monitor workflow executions
* **[Function Commands](/sdk/cli/function)** - Test and view function execution logs
* **[Auth Commands](/sdk/cli/auth)** - Manage machine users and OAuth2 clients
* **[Secret Commands](/sdk/cli/secret)** - Manage vaults and secrets
* **[Workspace Commands](/sdk/cli/workspace)** - Create and manage workspaces

For detailed setup instructions and tutorials, see the [SDK Quickstart Guide](/sdk/quickstart).

---

---
url: https://docs.tailor.tech/getting-started/quickstart.md
---
# Quickstart

## Getting Started

In this quickstart tutorial, you'll create an app using the Tailor Platform SDK.
Follow the steps below to get started.

## Prerequisite

You'll need a Tailor account to start using the Tailor Platform.
Contact us [here](https://www.tailor.tech/demo) to get started.

### Install Node.js

The SDK requires Node.js 22 or later. Install Node.js via your package manager by following the official Node.js instructions.

### Create an Example App

The following command creates a new project with the required configuration files and example code.

```bash
npm create @tailor-platform/sdk example-app --template hello-world
```

Before deploying your app, you need to create a workspace:

```bash
npx tailor login
npx tailor workspace create --name <workspace-name> --region <workspace-region>
npx tailor workspace list

# OR
# Create a new workspace using Tailor Platform Console
# https://console.tailor.tech/
```

### Deploy Your App

Run the apply command to deploy your project:

```bash
cd example-app
npm run deploy -- --workspace-id <your-workspace-id>
```

You can now open the GraphQL Playground and execute the `hello` query:

```graphql
query {
  hello(name: "sdk") {
    message
  }
}
```

### Hello World Example

Here's a simple query resolver from the hello-world template:

```typescript
import { createResolver, t } from "@tailor-platform/sdk";

export default createResolver({
  name: "hello",
  operation: "query",
  input: {
    name: t.string().description("Name to greet"),
  },
  body: (context) => {
    return {
      message: `Hello, ${context.input.name}!`,
    };
  },
  output: t
    .object({
      message: t.string().description("Greeting message"),
    })
    .description("Greeting response"),
});
```

You can edit `src/resolvers/hello.ts` to customize the message:

```typescript
export default createResolver({
  body: (context) => {
    return {
      message: `Goodbye, ${context.input.name}!`,
    };
  },
});
```

Deploy again to see the response.

---

---
url: https://docs.tailor.tech/getting-started/graphql.md
---
# Interacting with Tailor Platform GraphQL

If you're already familiar with the GraphQL, you can skip this page and
proceed to the [Tutorials](/tutorials/manage-data-schema/overview)

This page demonstrates how to use the Tailor Platform GraphQL API. Along the way, you'll learn key concepts and techniques that are fundamental to using the Tailor Platform GraphQL.

## GraphQL

GraphQL is a powerful query language for APIs that allows clients to request exactly the data they need. This guide will introduce you to the basics of GraphQL, starting with queries and including sample code.

## Queries

In GraphQL, queries are used to request data from the server.
They are similar to making a GET request in REST APIs. With GraphQL, you can specify exactly which fields you want to receive in the response, giving you more control over the returned data and reducing the amount of unnecessary data transfer.

### Query Example

Let's assume we have an API for an e-commerce platform that has a `Product` table with fields like `id`, `name`, and `price`.
Assume that the `name` field is of the `String` data type and the `price` field is of the `Integer` data type.
Here's an example of a GraphQL query to request a list of products and their details:

```graphql {{ title: 'graphql' }}
query {
  products {
    edges {
      node {
        id
        name
        price
      }
    }
  }
}
```

In this query, we are asking for a list of products and their `id`, `name`, and `price` fields. The server will respond with a JSON object containing the requested data:

```json {{ title: 'example result'}}
{
  "data": {
    "products": {
      "edges": [
        {
          "node": {
            "id": "5223c635-557e-42b5-817a-138192923495",
            "name": "Product A",
            "price": 20
          }
        },
        {
          "node": {
            "id": "1935b56d-4fb6-4b7f-8e8a-8817c783b613",
            "name": "Product B",
            "price": 30
          }
        }
      ]
    }
  }
}
```

You might notice that the name of the query: `products` is plural of the table name.
In Tailor Platform, `<table name>s` (in plural) will give you a list of the records in the `<table name>`.

`edges` contains an array of results.

Unlike REST API, you are not constrained by the pre-determined API specification.

***

## Nested Objects

In GraphQL, you can request data from related objects or entities in a single query. This is called a "nested object" query. Nested objects allow you to fetch data from multiple related entities efficiently, without making multiple requests like you would with REST APIs.

### Nested Object Example

Continuing with our e-commerce platform example, let's assume that the `Product` table has a related `Manufacturer` table with fields like `id`, `name`, `country`, and `directShipping`. You can request data from both the `Product` and the related `Manufacturer` in a single query.

Here's an example of a GraphQL query requesting a list of products, their details, and the associated manufacturer information:

```graphql {{ title: 'graphql'}}
query {
  products {
    edges {
      node {
        id
        name
        price
        manufacturer {
          id
          name
          country
          directShipping
        }
      }
    }
  }
}
```

In this query, we are asking for a list of products along with their `id`, `name`, `price`, and related `manufacturer` data. The server will respond with a JSON object containing the requested data:

```json {{ title: 'example result'}}
{
  "data": {
    "products": {
      "edges": [
        {
          "node": {
          	"id": "5223c635-557e-42b5-817a-138192923495",
            "name": "Product A",
            "price": 20,
            "manufacturer" {
              "id": "6a5e6f81-15fd-493a-b5d5-86a80a8f81db",
              "name": "ABC Corp.",
              "country": "United States",
              "directShipping": false
            }
          }
        },
        {
          "node": {
          	"id": "1935b56d-4fb6-4b7f-8e8a-8817c783b613",
            "name": "Product B",
            "price": 30,
            "manufacturer" {
              "id": "38bfe29c-329c-4f6c-9e3e-5c1e6e8f0c0f",
              "name": "Wasabi Co.",
              "country": "Japan",
              "directShipping": false
              }
          }
        }
      ]
    }
  }
}
```

***

## Mutations

In GraphQL, mutations are used to create, update, or delete data on the server.
They are similar to POST, PUT, and DELETE requests in REST APIs.
Mutations allow you to perform actions on your data, such as creating new objects, updating existing ones, or removing objects altogether.

### Mutation Example

Continuing with our e-commerce platform example, let's assume we want to create, update, and delete `Product` objects.
Here are examples of GraphQL mutations for each of these operations:

#### Create a new Product

```graphql {{ title: 'graphql'}}
# Create "Product C" and set the manufacturer "ABC Corp." with the id in the Manufacturer table
mutation {
  createProduct(
    input: { name: "Product C", price: 40, manufacturerId: "6a5e6f81-15fd-493a-b5d5-86a80a8f81db" }
  ) {
    id
    name
    price
    manufacturer {
      id
      name
    }
  }
}
```

#### Update an existing Product

```graphql {{ title: 'graphql'}}
mutation {
  updateProduct(
    id: "5223c635-557e-42b5-817a-138192923495"
    input: { name: "Product A Updated", price: 25 }
  ) {
    id
    name
    price
  }
}
```

#### Delete a Product

```graphql {{ title: 'graphql'}}
# Delete "Product B"
mutation {
  deleteProduct(id: "5223c635-557e-42b5-817a-138192923495") {
    id
  }
}
```

In these mutation examples, we perform various actions on `Product` objects.
The `createProduct` mutation creates a new product, while the `updateProduct` mutation updates an existing product's information.
The `deleteProduct` mutation removes a product based on the provided `id`.
After executing each mutation, the server will respond with the affected data, such as the `id`, `name`, and `price` of the created or updated product, or the `id` of the deleted product.

## Filtering and Sorting

In GraphQL, you can apply filters and sorting options to your queries to retrieve specific data subsets or to organize the returned data based on certain criteria.
This allows you to efficiently request data that matches specific conditions or to display data in a particular order.

### Filter and Sort Example

Continuing with our e-commerce platform example, let's say we want to filter products based on their price and sort the results by price in ascending order.
Here are examples of GraphQL queries that demonstrate filtering and sorting:

#### Filter products by price

```graphql {{ title: 'graphql'}}
# Get the number of products that are priced greater than or equal to 30 and list them.
query {
  products(query: { price: { gte: 30 } }) {
    edges {
      node {
        id
        name
        price
      }
    }
  }
}
```

In this query, we request a count of products with a `price` greater than or equal to 30, along with a list of those products in the `edges` field. The`query` parameter specifies the filtering condition.

#### Sort products by price in ascending order

```graphql {{ title: 'graphql'}}
query {
  products(order: [{ field: price, direction: Asc }]) {
    edges {
      node {
        id
        name
        price
      }
    }
  }
}
```

In this query, we are requesting a list of products sorted by `price` in ascending order.
The `order` parameter takes an array of the sorting field and direction and is used to specify the ordering condition.

By applying filters and sorting options to your GraphQL queries, you can easily customize the data you receive from the server, making it more relevant to your specific use case and simplifying the data processing on the client-side.

#### Combining Filters and Sorting

You can also combine filtering and sorting in a single query to further refine your results.
For example, you can retrieve products with a price greater than or equal to 30, sorted by price in ascending order:

```graphql {{ title: 'graphql'}}
query {
  products(query: { price: { gte: 30 } }, order: [{ field: price, direction: Asc }]) {
    edges {
      node {
        id
        name
        price
      }
    }
  }
}
```

In this query, we apply both a filter and a sorting option to the products query. The resulting data will be a list of products that meet the filtering condition and are sorted according to the specified criteria.

By combining filters and sorting options in your GraphQL queries, you can retrieve data that is both relevant to your application and organized in a way that meets your specific needs. This flexibility allows you to tailor your queries to your requirements and optimize data retrieval and processing.

You can also use AND, OR, NOT and nested queries. Find more about operators and nested filtering condition in [TailorDB](/guides/tailordb/overview).

## Pagination

Pagination is an important feature in GraphQL that allows you to request a specific portion of a dataset. This is particularly useful when dealing with large datasets, as it enables you to efficiently retrieve and display smaller chunks of data, reducing the amount of data transferred and processed at once.

### Pagination Example

Continuing with our e-commerce platform example, let's assume we want to retrieve a list of products but limit the results to only 5 items per request. We can achieve this using the `first` and `after` parameters in our GraphQL query. Here's an example of how to implement pagination:

#### Fetch the first 5 products

```graphql {{ title: 'graphql'}}
query {
  products(first: 5) {
    edges {
      node {
        id
        name
        price
      }
    }
  }
}
```

In this query, we use the `first` parameter to limit the number of products returned to the first 5 items. This is useful for displaying a smaller set of data on the client-side, such as on the first page of a paginated list.

By using `first`, `last`, `after` and `before` parameters in your GraphQL queries, you can implement pagination in your application, allowing you to efficiently manage large datasets and improve the user experience by reducing the amount of data loaded and displayed at once.

Learn more about [pagination specification](/guides/tailordb/auto-generated-api#pagination).

## Aggregation Queries

Aggregation queries in GraphQL allow you to perform calculations on your data, such as counting, summing, averaging, finding the minimum or maximum values, and more. These queries are useful when you need to generate summary statistics or derive insights from your data.

### Aggregation Example

Continuing with our e-commerce platform example, let's say we want to calculate the average of the price of all products. We can achieve this using an aggregation query. Here's an example of how to implement an aggregation query for averaging the product prices:

#### Calculate the average price

```graphql {{ title: 'graphql'}}
query {
  aggregateProduct {
    average {
      price
    }
  }
}
```

In this query, we use the `aggregateProduct` query to perform an aggregation on the `price` field of the `Product` table. The `average` field is used to specify the aggregation operation, which in this case is calculating the average of all product prices.

Aggregation queries can also be combined with filtering to further customize the data you retrieve and perform calculations on specific subsets of your data.

### Calculate the total revenue per product

```graphql {{ title: 'graphql'}}
query {
  aggregateOrder {
    sum {
      total
    }
    groupBy {
      productId
    }
  }
}
```

In this query, we use the `aggregateOrder` query to perform an aggregation on the `Order` table. The `groupBy` syntax is used to group the orders by the `productId` field. For each group (each unique product), we calculate the sum of the `total` field, which represents the revenue for that specific product. We alias the result as `totalRevenue`.

The response will include a list of grouped results, where each group is identified by a unique `key` (the `productId` in this case), and the corresponding aggregated values, such as the total revenue for that specific product.

Using `groupBy` with aggregation queries in GraphQL allows you to perform calculations on your data while grouping it by a specific field, which can be helpful for generating summary statistics, comparisons, or insights based on different categories or attributes.

To use the aggregation query, you'll need to enable advanced APIs. For example, to enable aggregation on the `Order` table

```typescript
db.table("Order", {
  name: db.string(),
  // ... other fields
}).features({
  aggregation: true,
});
```

See [Advanced APIs](/guides/tailordb/advanced-settings/aggregation) page for more information.

## Further information

* Explore [Tutorials](/tutorials/manage-data-schema/overview) as you start building your application.

---

---
url: https://docs.tailor.tech/getting-started/console/overview.md
---
# Console

The [Console](https://console.tailor.tech) is a web-based interface that gives you a unified view of everything running inside the Tailor Platform.
It’s designed to simplify observability and operational workflows by letting you quickly inspect resources, interact with data, and manage workspaces.

With the console, you can monitor platform resources in real time, explore and work with data, manage workspaces and their assets, and perform key operational actions such as importing data or managing secrets.

## Core Capabilities

The Console provides the following key features:

* **Application Overview**: View and manage your deployed applications with a comprehensive dashboard
* **GraphQL Playground**: Test and execute GraphQL queries and mutations with an embedded playground
* **Schema Management**: Browse data models and database schemas
* **Pipeline Management**: Monitor and debug pipeline executions with detailed logs
* **User Role Management**: Configure platform user roles and permissions for workspace access
* **Organization Management**: Manage organization settings and configurations
* **Organization User Role Management**: Configure and manage user roles and permissions at the organization level
* **Data Operations**: Import and view table data with pagination
* **Manage Secrets**: Create and update secrets in the workspace settings
* **Workspace Management**: Configure and manage workspace-level settings and integrations

## Explore Your New App

After deploying your application, the console gives you several ways to explore, manage, and work with your app’s data and resources.

### Test with GraphQL Playground

In the application, select the `GraphQL Playground` from the left navigation panel.

![Embedded GraphQL Playground Highlight](../assets/console-application-embedded-graphql-playground-highlight.png)

This opens an embedded `GraphQL Playground` with a pre-populated access token, allowing you to execute queries and mutations for the following data operations.

![GraphQL Playground](../assets/console-graphql-playground.png)

#### 1. Fetch and filter data

Retrieve and refine data using queries to filter and sort the data based on defined criteria.
You can refer to examples for filter and sort operations [here](/getting-started/graphql#filterandsortexample).

#### 2. Create, update, and delete records

Manage your data dynamically by executing mutations to create new entries, modify existing records, or remove them as needed.
You can refer to examples for mutations [here](/getting-started/graphql#mutations).

The application comes pre-loaded with sample data to help you get started. When you're ready to work with your own data, you can import CSV files by following the [Import CSV Files](/tutorials/manage-data-schema/import-csv-file) tutorial.

#### 3. Validate input data

You can confirm that the input data aligns with the validation rules defined in the schema. To learn more about data validations, refer to the guide [here](/guides/tailordb/validations).

### Customize your application

#### 1. Set Up Your Workspace

Configure your workspace to match your deployed application. You can view and manage workspaces using the `tailor` CLI.

```bash
tailor workspace
```

#### 2. Update the configuration file

For example, to modify the `User` table with a new field, update your TailorDB table definition:

```typescript
import { db } from "@tailor-platform/sdk";

export const user = db.table("User", "User of the system", {
  name: db.string(),
  email: db.string().unique(),
  // Add new field
  lastname: db.string().description("Last name of the user"),
});
```

#### 3. Apply your changes

After updating the configuration, deploy your changes:

```bash
npm run deploy
```

#### 4. Verify your changes

In the console, you can see the new field added to the `user` schema on the overview page.

![Schema overview page](../assets/console-show-new-field.png)

#### Troubleshooting

If you encounter issues:

1. Verify your workspace selection
2. Check your configuration file

---

---
url: https://docs.tailor.tech/getting-started/console/key-features.md
---
# Console Features

## Application Status

The Application Card displays clear status indicators to help you quickly assess the state of each application.

![Console – Application Health Indicator](../assets/console-application-health-indicator.png)

### Status Types

🟢 Healthy and Up-to-Date: Indicates that the application is running normally and using the latest schema.

🔴 Unhealthy Schema: The application is in an unhealthy state, and its serving schema is outdated.

🟠 Unknown Status: The current status of the application cannot be determined.

🚫 Disabled: The application is currently disabled.

Each status includes a tooltip providing a brief explanation for additional clarity.

## Pipeline Execution Logs

Pipeline resolver execution logs include timestamps, messages, and status information to help you debug and monitor your pipelines.

To view the logs, select the `Pipeline` option for your application in the console and choose the pipeline resolver to inspect.

![Console – Pipeline resolver execution logs](../assets/console-pipeline-resolver-execution-logs.png)

Click on `View Details` to learn more about the pipeline resolver execution.

![Console – Pipeline resolver execution logs details](../assets/console-pipeline-resolver-execution-logs-detail.png)

For more detailed information, refer to [Resolver](/guides/resolver).

## Platform user roles

As a workspace admin, you can change platform users role for the workspace. Once you update and save these changes, you cannot revert the user role unless you remove the user and add them back with the desired role.

Follow the steps below to change the PF users role in the [Console](https://console.tailor.tech).

1. Select the workspace `Settings` tab and navigate to `PF users` in the sidebar.

![Console – workspace permission](../assets/tailor-console-workspace-settings-pf-users.png)

2. Choose the desired role for the user and click `Submit` to update the user role.

![Console – edit role save dialog](../assets/tailor-console-edit-role-save-dialog.png)

Refer [Permissions of the Platform user](/administration/workspace#permissionsoftheplatformuser) for more information about the roles and permissions.

---

---
url: >-
  https://docs.tailor.tech/getting-started/core-concepts/platform-architecture.md
---
# Platform Architecture

Tailor Platform resources are organized in a hierarchical structure.
The following diagram illustrates the relationship between resources:

![Core Concepts](../assets/core-concepts.svg)

## Resource Hierarchy

### Workspace

A [Workspace](/administration/workspace) is the top-level namespace in the Tailor Platform for your organization.

* An application must belong to a Workspace
* Multiple applications can be hosted within a Workspace
* A workspace can have multiple admin users who manage the workspace and its applications

With the SDK, you can create a workspace using the CLI:

```bash
npx tailor workspace create --name my-workspace --region us-west
```

### Application

An **Application** represents your ERP application APIs, such as CRM, SCM, or any customized applications.

Each application can:

* Register services (TailorDB, Resolver, Auth) for use
* Configure CORS settings
* Provide a single GraphQL endpoint for all configured services

With the SDK, applications are defined in `tailor.config.ts`:

```typescript
import { defineConfig } from "@tailor-platform/sdk";

export default defineConfig({
  name: "my-app",
  db: {
    "my-db": { files: ["db/**/*.ts"] },
  },
  resolver: {
    "my-resolver": { files: ["resolver/**/*.ts"] },
  },
  auth: { name: "my-auth" },
  // ... other configuration
});
```

### Services

A **Service** is a pluggable microservice that you use to build applications.
The application handles stitching services together to provide a single GraphQL endpoint.

Learn more about available services in [Platform Services](/getting-started/core-concepts/services).

## Next Steps

* [Workspace & Application](/getting-started/core-concepts/workspace-application) - Learn more about workspaces and applications
* [Services](/getting-started/core-concepts/services) - Explore available platform services
* [Quickstart](/getting-started/quickstart) - Build your first application

---

---
url: https://docs.tailor.tech/getting-started/core-concepts/services.md
---
# Services

Tailor Platform offers several core services to help you build applications. Each service is designed to handle specific functionality and can be composed together to create powerful applications.

## Core Services

### TailorDB

A flexible database service that provides:

* **Type-safe schema definition** using the SDK
* **Auto-generated GraphQL API** for CRUD operations
* **Relationships** between data tables
* **Hooks** for custom logic
* **Permission-based access control**

[Learn more about TailorDB →](/guides/tailordb/overview)

### Auth

Authentication and authorization service that provides:

* **User management** and authentication
* **Identity Provider (IdP) integration** (Okta, Entra ID, Google Workspace, Auth0)
* **Built-in IdP** for quick setup
* **Machine users** for service-to-service communication

[Learn more about Auth →](/guides/auth/overview)

### Resolver

Custom GraphQL resolver service for business logic:

* **Query resolvers** for custom read operations
* **Mutation resolvers** for custom write operations
* **Type-safe input/output** definitions
* **Access to TailorDB** via query builder

[Learn more about Resolver →](/guides/resolver)

### Executor

Event-driven automation service:

* **Event-based triggers** on database changes
* **Schedule-based triggers** for cron jobs
* **Webhook triggers** for external events
* **Multiple operation types** (GraphQL, Webhook, Function)

[Learn more about Executor →](/guides/executor/overview)

### Function

Serverless JavaScript runtime for custom logic:

* **Custom business logic** in JavaScript
* **HTTP requests** to external services
* **TailorDB access** for data operations

[Learn more about Function →](/guides/function/overview)

### Workflow

Job orchestration service (Preview):

* **Multi-step workflows**
* **Conditional branching**
* **Retry and error handling**

[Learn more about Workflow →](/guides/workflow/)

### Secret Manager

Secure secret storage:

* **API keys and tokens**
* **Connection strings**
* **Environment-specific secrets**

[Learn more about Secret Manager →](/guides/secretmanager)

## Next Steps

* [Quickstart](/getting-started/quickstart) - Build your first application
* [TailorDB](/guides/tailordb/overview) - Start with database setup

---

---
url: >-
  https://docs.tailor.tech/getting-started/core-concepts/workspace-application.md
---
# Workspace & Application

This guide explains how Workspaces and Applications work in Tailor Platform.

## Workspace

A Workspace is the top-level container for your Tailor Platform resources.

### Creating a Workspace

Using the SDK CLI:

```bash
# Create a new workspace
npx tailor workspace create --name my-workspace --region us-west

# List your workspaces
npx tailor workspace list
```

Or create one through the [Console](https://console.tailor.tech).

### Workspace Regions

Workspaces are deployed to specific regions:

| Region           | Location             |
| ---------------- | -------------------- |
| `us-west`        | United States (West) |
| `asia-northeast` | Asia Pacific (Tokyo) |

## Application

An Application represents a complete API deployment within a workspace.

### Application Configuration

Configure your application in `tailor.config.ts`:

```typescript
import { defineConfig } from "@tailor-platform/sdk";

export default defineConfig({
  name: "my-app",
  db: {
    "my-db": { files: ["db/**/*.ts"] },
  },
  resolver: {
    "my-resolver": { files: ["resolver/**/*.ts"] },
  },
  auth: { name: "my-auth" },
});
```

### Subgraphs

Each service you configure becomes a subgraph of your application's single GraphQL endpoint:

* `db` - TailorDB database service
* `resolver` - Custom resolvers and business logic
* `auth` - Authentication and authorization

See [Configuration](/sdk/configuration) for the full list of services.

### Deploying Applications

Deploy your application using the SDK CLI:

```bash
npm run deploy -- --workspace-id <your-workspace-id>
```

## Next Steps

* [Services](/getting-started/core-concepts/services) - Learn about available platform services
* [TailorDB](/guides/tailordb/overview) - Set up your database
* [Auth](/guides/auth/overview) - Configure authentication

---

---
url: https://docs.tailor.tech/guides.md
---

# Guides

Comprehensive guides for building applications on Tailor Platform.

## Core Platform Guides

* [Application](application.md) - Create application manifests and API endpoints for your services
* [Resolver](resolver.md) - Build custom GraphQL resolvers with business logic and data transformations
* [Events](events.md) - Event types and payloads for building dynamic workflows and automations
* [Secret Manager](secretmanager.md) - Securely manage API keys, tokens, and credentials with versioning
* [Observability / OpenTelemetry](opentelemetry.md) - Forward platform-generated traces and logs to external backends like New Relic, Honeycomb, or Datadog
* [Static Website Hosting](static-website-hosting.md) - Deploy single-page applications with CDN caching, access control, and custom domains

## Service-Specific Guides

* [TailorDB](tailordb/overview) - Database schema, fields, relationships, permissions, hooks, and auto-generated APIs
* [Auth](auth/overview) - Authentication setup, app login, auth connections, and identity provider integrations
* [Executor](executor/overview) - Event-based, webhook, and scheduled triggers with various operations
* [Function](function/overview) - Custom function development, TailorDB access, debugging, and examples
* [Workflow](workflow/) - Creating workflows, monitoring executions, and triggering mechanisms
* [Integration](integration/overview) - Third-party integrations including Shopify, QuickBooks, ShipStation, and more

---

---
url: https://docs.tailor.tech/guides/application.md
---

# Application

By creating an application manifest, you can create your API endpoint for the services you use.
This API endpoint will provide all the Queries and Mutations of each service, including those you defined.

In the spec property, the following child properties can be defined:

**Properties**

* `Name`: The gateway name. Name of the gateway that will be used as the application's subdomain, e.g. setting `Name` to `my-app` will create API endpoints at `my-app-{WORKSPACE_HASH}.erp.dev/query`. Cannot duplicate a NAME that is being used by other users. **(required)**
* `Cors`: The origins. Defines the origin to which requests are allowed.
* `AllowedIPAddresses`: A list of IP addresses authorized to access the application, preventing unauthorized access. Each entry is a string in the format CIDR. Example: `["1.1.1.1/32", "2.2.2.0/24"]`. To restrict access more broadly across an organization or folder, see [IP Restriction](/administration/ip-restriction).
* `Auth`: The authentication service. Defines the authentication service to be used.
* `Subgraphs`: The services you use.

To deploy an application, you'll need to enable at least one service.

**Example**

```typescript
import { defineConfig } from "@tailor-platform/sdk";

export default defineConfig({
  name: "my-app",
  db: {
    "my-db": { files: ["db/**/*.ts"] },
  },
  resolver: {
    "my-resolver": { files: ["resolver/**/*.ts"] },
  },
  auth: { name: "my-auth" },
});
```

---

---
url: https://docs.tailor.tech/guides/events.md
---

# Events and Payloads

The Tailor Platform offers a wide range of events that allow you to trigger specific actions within your applications. These events play a crucial role in building dynamic workflows and enable you to automate processes based on real-time data changes. Refer to the [Event based trigger](/guides/executor/event-based-trigger) section for details on using and configuring events.

Below is a list of supported events and their payloads.

## TailorDB

### Record Created

`tailordb.type_record.created`

| Field Name      | Description                                          |
| --------------- | ---------------------------------------------------- |
| `workspaceId`   | `String`: The workspace ID where the event occurred. |
| `namespaceName` | `String`: Name of the application.                   |
| `typeName`      | `String`: Name of the type.                          |
| `newRecord`     | `Object`: The new record added to Tailor DB.         |

### Record Updated

`tailordb.type_record.updated`

| Field Name      | Description                                          |
| --------------- | ---------------------------------------------------- |
| `workspaceId`   | `String`: The workspace ID where the event occurred. |
| `namespaceName` | `String`: Name of the application.                   |
| `typeName`      | `String`: Name of the type.                          |
| `oldRecord`     | `Object`: The old record in Tailor DB.               |
| `newRecord`     | `Object`: The updated record in Tailor DB.           |

### Record Deleted

`tailordb.type_record.deleted`

| Field Name      | Description                                          |
| --------------- | ---------------------------------------------------- |
| `workspaceId`   | `String`: The workspace ID where the event occurred. |
| `namespaceName` | `String`: Name of the application.                   |
| `typeName`      | `String`: Name of the type.                          |
| `oldRecord`     | `Object`: The deleted record.                        |

### File Uploaded

`tailordb.type_record_file.uploaded`

| Field Name                  | Description                                                |
| --------------------------- | ---------------------------------------------------------- |
| `workspaceId`               | `String`: The workspace ID where the event occurred.       |
| `namespaceName`             | `String`: Name of the application.                         |
| `typeName`                  | `String`: Name of the type.                                |
| `metadata.content_type`     | `String`: MIME type of the uploaded file.                  |
| `metadata.field_name`       | `String`: Name of the file field that received the upload. |
| `metadata.last_uploaded_at` | `DateTime`: Timestamp when the file was uploaded.          |
| `metadata.parent_id`        | `String`: ID of the record that owns the file.             |
| `metadata.sha256sum`        | `String`: SHA256 checksum of the uploaded file.            |
| `metadata.size`             | `Integer`: Size of the uploaded file in bytes.             |

## Resolver

### Resolver Executed

`pipeline.resolver.executed`

| Field Name         | Description                                                                |
| ------------------ | -------------------------------------------------------------------------- |
| `workspaceId`      | `String`: The workspace ID where the event occurred.                       |
| `namespaceName`    | `String`: Name of the application.                                         |
| `resolverName`     | `String`: Name of the resolver.                                            |
| `succeeded.result` | `Object`: The result object contains `pipelines` and `resolver` data.      |
| `failed.error`     | `String`: The error message provides details about the cause of the error. |

## Auth

### Access Token Issued

`auth.access_token.issued`

| Field Name      | Description                                          |
| --------------- | ---------------------------------------------------- |
| `workspaceId`   | `String`: The workspace ID where the event occurred. |
| `namespaceName` | `String`: Name of the application.                   |

## Built-in IdP

### User Created

`idp.user.created`

| Field Name      | Description                                          |
| --------------- | ---------------------------------------------------- |
| `workspaceId`   | `String`: The workspace ID where the event occurred. |
| `namespaceName` | `String`: Name of the application.                   |
| `userId`        | `String`: The ID of the created IdP user.            |

### User Updated

`idp.user.updated`

| Field Name      | Description                                          |
| --------------- | ---------------------------------------------------- |
| `workspaceId`   | `String`: The workspace ID where the event occurred. |
| `namespaceName` | `String`: Name of the application.                   |
| `userId`        | `String`: The ID of the updated IdP user.            |

### User Deleted

`idp.user.deleted`

| Field Name      | Description                                          |
| --------------- | ---------------------------------------------------- |
| `workspaceId`   | `String`: The workspace ID where the event occurred. |
| `namespaceName` | `String`: Name of the application.                   |
| `userId`        | `String`: The ID of the deleted IdP user.            |

## Workflow

Workflow publishes events on every meaningful state transition of a workflow execution, at two granularity levels. Workflow-level events describe the execution as a whole, and job-level events describe a single job execution within it.

Workflows are not scoped to an application namespace, so these events carry no `namespaceName` field.

Publishing is controlled per resource by `publishEvents`. When an executor subscribes to a workflow's events, the SDK enables publishing automatically on the resources that produce them. See [Execution Events](/guides/workflow/monitoring-executions#execution-events) for details.

All workflow-level events share the following fields.

| Field Name            | Description                                          |
| --------------------- | ---------------------------------------------------- |
| `workspaceId`         | `String`: The workspace ID where the event occurred. |
| `workflowId`          | `String`: ID of the workflow resource.               |
| `workflowName`        | `String`: Name of the workflow.                      |
| `workflowExecutionId` | `String`: ID of the workflow execution.              |

Job-level events share the fields above plus the following.

| Field Name               | Description                                                  |
| ------------------------ | ------------------------------------------------------------ |
| `workflowJobExecutionId` | `String`: ID of the job execution.                           |
| `jobFunctionName`        | `String`: Name of the job, as passed to `createWorkflowJob`. |

### Workflow Execution Started

`workflow.workflow_execution.started`

Published when the execution starts running, including when it starts running again after a retry or a resume.

### Workflow Execution Completed

`workflow.workflow_execution.completed`

Published when the execution reaches a terminal state.

| Field Name | Description                                                     |
| ---------- | --------------------------------------------------------------- |
| `success`  | `Boolean`: Whether the execution succeeded.                     |
| `error`    | `String`: The error message. Present when `success` is `false`. |

### Workflow Execution Retried

`workflow.workflow_execution.retried`

Published when the execution is retried automatically by its retry policy.

| Field Name   | Description                                                        |
| ------------ | ------------------------------------------------------------------ |
| `retryCount` | `Integer`: Number of retries already attempted for this execution. |
| `retryAfter` | `DateTime`: Timestamp the retry is scheduled for.                  |

### Workflow Execution Resumed

`workflow.workflow_execution.resumed`

Published when a failed or retry-pending execution is resumed manually.

### Workflow Execution Wait Started

`workflow.workflow_execution.wait_started`

Published when a job suspends the execution on a wait point. Refer to [Wait / Resolve](/guides/workflow/wait-resolve) for details on wait points.

### Workflow Execution Wait Resolved

`workflow.workflow_execution.wait_resolved`

Published when a waiting execution is released by resolving its wait point.

### Job Execution Started

`workflow.workflow_execution.job_execution.started`

Published when the job is submitted and its execution starts running.

### Job Execution Completed

`workflow.workflow_execution.job_execution.completed`

Published when the job execution reaches a terminal state. A job execution released from a wait point publishes Job Execution Wait Resolved instead.

| Field Name | Description                                                     |
| ---------- | --------------------------------------------------------------- |
| `success`  | `Boolean`: Whether the job execution succeeded.                 |
| `error`    | `String`: The error message. Present when `success` is `false`. |

### Job Execution Wait Started

`workflow.workflow_execution.job_execution.wait_started`

Published when the job calls `tailor.workflow.wait()` and its execution is created in the waiting state.

| Field Name    | Description                                                                                               |
| ------------- | --------------------------------------------------------------------------------------------------------- |
| `waitKey`     | `String`: The wait point key the job execution is suspended on.                                           |
| `waitPayload` | `String`: JSON-serialized payload recorded with the wait point. Absent when the wait point recorded none. |

### Job Execution Wait Resolved

`workflow.workflow_execution.job_execution.wait_resolved`

Published when a waiting job execution is released by resolving its wait point.

| Field Name | Description                                     |
| ---------- | ----------------------------------------------- |
| `waitKey`  | `String`: The wait point key that was resolved. |

---

---
url: https://docs.tailor.tech/guides/resolver.md
---

# Resolver

The Tailor Platform provides GraphQL APIs to access and manipulate your data.
While the auto-generated GraphQL APIs cover many use cases, more complex ones require custom business logic.
The Resolver service lets you define custom resolvers that chain queries and perform data transformations.

## Quick Start with SDK

The SDK provides a simplified way to create custom GraphQL resolvers using TypeScript:

```typescript
import { createResolver, t } from "@tailor-platform/sdk";
import { getDB } from "../generated/tailordb";

export default createResolver({
  name: "incrementUserAge",
  operation: "mutation",
  input: {
    email: t.string(),
  },
  body: async (context) => {
    const db = getDB("tailordb");
    const user = await db
      .selectFrom("User")
      .selectAll()
      .where("email", "=", context.input.email)
      .executeTakeFirstOrThrow();

    await db
      .updateTable("User")
      .set({ age: user.age + 1 })
      .where("id", "=", user.id)
      .execute();

    return { oldAge: user.age, newAge: user.age + 1 };
  },
  output: t.object({
    oldAge: t.int(),
    newAge: t.int(),
  }),
});
```

### Key Features

* **Type-safe input/output schemas** using `t` object
* **Direct database access** via Kysely query builder
* **User context** for authentication/authorization
* **Input validation** with custom rules

### Input Validation

```typescript
createResolver({
  input: {
    email: t
      .string()
      .validate(
        ({ value }) => value.includes("@"),
        [({ value }) => value.length <= 255, "Email must be 255 characters or less"],
      ),
  },
  // ...
});
```

## Overview

A resolver exposes a custom GraphQL query or mutation. When a request resolves to it, the SDK validates the input, runs the `body` function, and validates the output.
Inside `body` you chain operations with plain TypeScript — read from TailorDB, call external services, and pass intermediate results along with ordinary variables and `await`.

## Definition

The SDK resolver definition specifies the resolver's behavior, input/output types, and implementation.

**Properties**

| Property    | Type     | Required | Description                                  |
| ----------- | -------- | -------- | -------------------------------------------- |
| `name`      | string   | Yes      | The name of the resolver                     |
| `operation` | string   | Yes      | Either `"query"` or `"mutation"`             |
| `input`     | object   | No       | Input schema using `t` type builders         |
| `body`      | function | Yes      | Async function containing the resolver logic |
| `output`    | object   | Yes      | Output schema using `t` type builders        |

**Example**

```typescript
import { createResolver, t } from "@tailor-platform/sdk";

export default createResolver({
  name: "myResolver",
  operation: "mutation",
  input: {
    userId: t.uuid(),
    name: t.string(),
  },
  body: async (context) => {
    return { success: true };
  },
  output: t.object({
    success: t.boolean(),
  }),
});
```

### Caveats

* `Subscription` operations are not supported, only `Mutation` and `Query` may be used.
* The name of the resolver **MUST NOT** collide with the existing tables' (e.g. `User`, etc.) as well as auto-generated operations (e.g. `createUser`, etc.).

## Resolver

The SDK `createResolver` function defines a complete resolver with its input, output, and implementation logic.

**Properties**

| Property    | Type     | Required | Description                                            |
| ----------- | -------- | -------- | ------------------------------------------------------ |
| `name`      | string   | Yes      | The resolver name (used in GraphQL schema)             |
| `operation` | string   | Yes      | `"query"` or `"mutation"`                              |
| `input`     | object   | No       | Input schema defined with `t` type builders            |
| `body`      | function | Yes      | Async function with resolver logic, receives `context` |
| `output`    | object   | Yes      | Output schema defined with `t` type builders           |

**Context Properties**

The `body` function receives a `context` object with:

| Property         | Description                                                                     |
| ---------------- | ------------------------------------------------------------------------------- |
| `context.input`  | The validated input arguments                                                   |
| `context.caller` | The user or machine user who called the resolver, or `null` for anonymous calls |

**Example**

```typescript
import { createResolver, t } from "@tailor-platform/sdk";
import { getDB } from "../generated/tailordb";

export default createResolver({
  name: "bindUserToContract",
  operation: "mutation",
  input: {
    userID: t.uuid(),
    contractID: t.uuid(),
    bindDate: t.date(),
    employeeType: t.enum(["MANAGER", "STAFF"]),
  },
  body: async (context) => {
    const db = getDB("tailordb");

    // Perform database operations
    await db
      .updateTable("Contract")
      .set({ userId: context.input.userID })
      .where("id", "=", context.input.contractID)
      .execute();

    return { userID: context.input.userID };
  },
  output: t.object({
    userID: t.uuid(),
  }),
});
```

### Schema types

Scalar Types

* String
* Int
* Float
* Boolean
* ID

Custom Scalar Types

* Date
* DateTime
* Time

**Timeout and Limits**

Resolvers have a timeout set to 60 seconds. Additionally, the platform enforces a recursive call depth limit of 10 levels to prevent infinite loops when resolvers call other platform services. See [Platform Limits](/reference/platform/platform-limits#recursive-call-detection) for more details.

### Execution Order (Resolver level)

In the SDK, the execution order is straightforward: the `body` function executes your resolver logic directly. The flow is:

1. Input validation (via `t` type definitions and optional `.validate()` rules)
2. `body` function execution
3. Output validation (via output schema)

```typescript
import { createResolver, t } from "@tailor-platform/sdk";

export default createResolver({
  name: "myResolver",
  operation: "mutation",
  input: {
    email: t.string().validate(({ value }) => value.includes("@")),
  },
  body: async (context) => {
    // Your resolver logic executes here
    return { success: true };
  },
  output: t.object({
    success: t.boolean(),
  }),
});
```

## Multi-step logic

In the SDK, the concept of declarative "pipeline steps" is replaced by direct TypeScript code in the `body` function. You can perform multiple database operations, call external services, and chain logic naturally using async/await.

**Example**

```typescript
import { createResolver, t } from "@tailor-platform/sdk";
import { getDB } from "../generated/tailordb";

export default createResolver({
  name: "createUserWithContract",
  operation: "mutation",
  input: {
    name: t.string(),
    email: t.string(),
    contractCode: t.int(),
  },
  body: async (context) => {
    const db = getDB("tailordb");

    // Step 1: Create user
    const user = await db
      .insertInto("User")
      .values({
        name: context.input.name,
        email: context.input.email,
      })
      .returning(["id", "name"])
      .executeTakeFirstOrThrow();

    // Step 2: Create contract linked to user
    const contract = await db
      .insertInto("Contract")
      .values({
        userId: user.id,
        code: context.input.contractCode,
      })
      .returning(["id"])
      .executeTakeFirstOrThrow();

    return {
      userId: user.id,
      contractId: contract.id,
    };
  },
  output: t.object({
    userId: t.uuid(),
    contractId: t.uuid(),
  }),
});
```

### Execution Order (within a step)

In the SDK, there are no separate "steps" with pre/post scripts. Instead, you write TypeScript code directly in the `body` function, which gives you full control over execution order using standard programming constructs:

```typescript
import { createResolver, t } from "@tailor-platform/sdk";
import { getDB } from "../generated/tailordb";

export default createResolver({
  name: "processOrder",
  operation: "mutation",
  input: {
    orderId: t.uuid(),
  },
  body: async (context) => {
    const db = getDB("tailordb");

    // Validation (equivalent to PreValidation)
    const order = await db
      .selectFrom("Order")
      .selectAll()
      .where("id", "=", context.input.orderId)
      .executeTakeFirst();

    if (!order) {
      throw new Error("Order not found");
    }

    // Main operation
    await db.updateTable("Order").set({ status: "processed" }).where("id", "=", order.id).execute();

    // Post-processing (equivalent to PostScript)
    return { orderId: order.id, status: "processed" };
  },
  output: t.object({
    orderId: t.uuid(),
    status: t.string(),
  }),
});
```

## Data manipulation

### Input arguments

In the SDK, input arguments are accessed via `context.input` in the `body` function. This is a type-safe object based on your input schema definition.

For instance, given a resolver with `userID` and `contractID` inputs:

```typescript
import { createResolver, t } from "@tailor-platform/sdk";

export default createResolver({
  name: "bindUserToContract",
  operation: "mutation",
  input: {
    userID: t.uuid(),
    contractID: t.uuid(),
  },
  body: async (context) => {
    // Access input arguments via context.input
    const userId = context.input.userID;
    const contractId = context.input.contractID;

    // Use the values in your logic
    return { userId, contractId };
  },
  output: t.object({
    userId: t.uuid(),
    contractId: t.uuid(),
  }),
});
```

Data from previous operations is available as regular TypeScript variables, making data flow explicit and type-safe:

```typescript
body: async (context) => {
  const db = getDB("tailordb");

  // First operation
  const user = await db
    .insertInto("User")
    .values({ name: context.input.name })
    .returning(["id"])
    .executeTakeFirstOrThrow();

  // Use result from first operation directly
  const contract = await db
    .insertInto("Contract")
    .values({ userId: user.id })
    .returning(["id"])
    .executeTakeFirstOrThrow();

  return { userId: user.id, contractId: contract.id };
},
```

### Context

In the SDK, the `context` object is passed to the `body` function and provides access to:

* `context.input` - The validated input arguments
* `context.caller` - The user or machine user who called the resolver (id, attributes, workspaceId, etc.), or `null` for anonymous calls

Data from previous operations is simply stored in TypeScript variables:

```typescript
import { createResolver, t } from "@tailor-platform/sdk";
import { getDB } from "../generated/tailordb";

export default createResolver({
  name: "processUserData",
  operation: "mutation",
  input: {
    name: t.string(),
  },
  body: async (context) => {
    const db = getDB("tailordb");

    // Step 1: Create user
    const user = await db
      .insertInto("User")
      .values({ name: context.input.name })
      .returning(["id"])
      .executeTakeFirstOrThrow();

    // Step 2: Do something else
    const profile = await db
      .insertInto("Profile")
      .values({ userId: user.id })
      .returning(["id"])
      .executeTakeFirstOrThrow();

    // Step 3: Reference results from earlier operations
    return {
      userId: user.id,
      profileId: profile.id,
    };
  },
  output: t.object({
    userId: t.uuid(),
    profileId: t.uuid(),
  }),
});
```

Access caller context for authorization:

```typescript
body: async (context) => {
  // Access current caller information (null for anonymous calls)
  const currentUserId = context.caller?.id;
  const userAttributes = context.caller?.attributes;

  // Use in your logic
  return { userId: currentUserId };
},
```

### Configuration data

In the SDK, you can access shared configuration data using standard TypeScript imports. Simply import your configuration objects and use them directly in your resolver:

```typescript
import { createResolver, t } from "@tailor-platform/sdk";
import { settings } from "../config/settings";

export default createResolver({
  name: "myResolver",
  operation: "query",
  input: {
    key: t.string(),
  },
  body: async (context) => {
    // Access shared configuration directly via imports
    const sharedValue = settings.shared.value;

    return { result: sharedValue };
  },
  output: t.object({
    result: t.string(),
  }),
});
```

You can also use environment variables:

```typescript
body: async (context) => {
  const apiKey = process.env.API_KEY;
  // Use the configuration in your logic
  return { configured: !!apiKey };
},
```

### Iteration and loops

In the SDK, you use standard JavaScript iteration constructs like `for...of` loops or array methods like `map`, `forEach`, and `Promise.all`:

```typescript
import { createResolver, t } from "@tailor-platform/sdk";
import { getDB } from "../generated/tailordb";

export default createResolver({
  name: "processProducts",
  operation: "mutation",
  input: {
    productIds: t.array(t.uuid()),
  },
  body: async (context) => {
    const db = getDB("tailordb");
    const results = [];

    // Iterate over products using for...of
    for (const productId of context.input.productIds) {
      const product = await db
        .selectFrom("Product")
        .selectAll()
        .where("id", "=", productId)
        .executeTakeFirstOrThrow();

      results.push({
        id: product.id,
        name: product.name,
      });
    }

    return { products: results };
  },
  output: t.object({
    products: t.array(
      t.object({
        id: t.uuid(),
        name: t.string(),
      }),
    ),
  }),
});
```

For parallel processing, use `Promise.all`:

```typescript
body: async (context) => {
  const db = getDB("tailordb");

  const products = await Promise.all(
    context.input.productIds.map(async (productId) => {
      return db
        .selectFrom("Product")
        .selectAll()
        .where("id", "=", productId)
        .executeTakeFirstOrThrow();
    })
  );

  return { products };
},
```

---

---
url: https://docs.tailor.tech/guides/secretmanager.md
---

# Secret Manager

Secret Manager provides a secure, centralized solution for managing confidential resources such as API keys, tokens, database credentials, and other sensitive information.
It integrates seamlessly with Tailor Platform services, allowing them to access secrets without exposing them in configuration files.
The service also supports versioning and fine-grained access control.

Common use cases include:

* Storing OAuth client secrets for Auth service integration
* Managing API keys for third-party service integrations
* Securing database connection strings and credentials
* Storing encryption keys and SSL/TLS certificates

## How to set up secrets

There are two ways to register secrets in Secret Manager:

You can define secrets using the SDK with `defineSecret()`:

```typescript {{ title: 'secrets.ts' }}
import { defineSecret } from "@tailor-platform/sdk";

export const secrets = defineSecret("my-secrets", {
  "api-key": { description: "External API key" },
});
```

* **name**: The first argument is the vault name for organizing secrets
* **secrets**: An object where each key is a secret name and the value contains metadata like description

You can manage secrets using the Terraform provider with dedicated vault and secret resources:

```sh {{ title: 'vaults.tf' }}
resource "tailor_secretmanager_vault" "default" {
  workspace_id = tailor_workspace.starwars.id
  name         = "default"
}

resource "tailor_secretmanager_secret" "my-secret" {
  workspace_id = tailor_workspace.starwars.id
  vault_name   = tailor_secretmanager_vault.default.name

  name             = "my-secret"
  value_wo         = "my-secret-value"
  value_wo_version = 1
}
```

* **workspace\_id**:(String) The ID of the workspace where the vault will be created
* **name**:(String) A unique name for the vault within the workspace
* **vault\_name**:(String) Reference to the vault where the secret will be stored
* **value\_wo**:(String) The actual secret value (write-only for security)
* **value\_wo\_version**:(Number) Version number for the secret value

You can also manage secrets using the tailor command-line interface:

```bash
# Create a vault
tailor secret vault create default

# Create a secret in the vault
tailor secret create --vault-name default --name my-secret --value my-secret-value
```

* `tailor secret vault create`: Creates a new vault in the current workspace (vault name as positional argument)
* `tailor secret create`: Adds a new secret to an existing vault
* Use `--vault-name` to specify the target vault name
* Use `--name` to set the secret identifier
* Use `--value` to provide the secret value

## Use cases

### Auth Service Integration

Secret Manager is commonly used with the Auth service to store sensitive authentication credentials:

```sh {{ title: 'auth.tf' }}
resource "tailor_auth_idp_config" "oidc_local" {
  workspace_id = tailor_workspace.ims.id
  namespace    = tailor_auth.ims_auth.namespace

  name = "oidc-local"

  oidc_config = {
    client_id = "<client-id>"
    client_secret = {
      vault_name  = tailor_secretmanager_vault.default.name
      secret_name = tailor_secretmanager_secret.oidc-client-secret.name
    }
    provider_url = "<your_auth_provider_url>"
  }
}
```

### Function Runtime Integration

You can access Secret Manager values from Function Runtime using the built-in `tailor.secretmanager` API:

```js {{ title: 'function_example.js' }}
export default async () => {
  console.log("start");

  // Get multiple secrets from a vault
  let secrets = await tailor.secretmanager.getSecrets("default", [
    "test-secret-1",
    "test-secret-2",
  ]);
  let jsonSecrets = JSON.stringify(secrets);
  console.log(`getSecrets: ${jsonSecrets}`);
  // output:
  // getSecrets: {"test-secret-1":"secret-value-1","test-secret-2":"secret-value-2"}

  // Get a single secret
  let secret = await tailor.secretmanager.getSecret("default", "test-secret-1");
  console.log(`getSecret with test-secret-1: ${secret}`);
  // output:
  // getSecret with test-secret-1: secret-value-1

  return {
    secrets: jsonSecrets,
  };
};
```

**API Methods:**

* `tailor.secretmanager.getSecrets(vaultName, secretNames)`: Retrieves multiple secrets from a vault
* `tailor.secretmanager.getSecret(vaultName, secretName)`: Retrieves a single secret from a vault

### Resolver and Executor Integration

Secrets can be referenced in resolvers and Executor configurations to securely access external services without hardcoding credentials.

## Security considerations

Secret values are write-only when using Terraform. Once stored, they cannot be retrieved through Terraform state files, ensuring your sensitive data remains secure.

* Secrets are encrypted at rest and in transit
* Access to secrets is controlled through workspace permissions
* Secret values are never exposed in logs or configuration files
* Use descriptive names for secrets to make them easily identifiable
* Regularly rotate sensitive credentials and update secret values accordingly

## Best practices

1. **Organize secrets by environment**: Use separate vaults for development, staging, and production environments
2. **Use descriptive naming**: Choose clear, consistent naming conventions for your secrets
3. **Limit access**: Only grant access to secrets that are necessary for each service
4. **Regular rotation**: Implement a process for regularly updating sensitive credentials
5. **Version management**: Use the versioning feature to track changes to secret values

---

---
url: https://docs.tailor.tech/guides/static-website-hosting.md
---

# Static Website Hosting

A static website hosting enables deployment of single page applications (SPAs) directly on Tailor Platform with optional IP-based access control and CDN caching.

## Configuration

Define static websites in your workspace configuration. Without IP restrictions, websites are automatically cached via CDN for optimal performance.

```typescript {{ title: "Static Website Configuration" }}
import { defineStaticWebSite } from "@tailor-platform/sdk";

// Basic static website
export const mySpa = defineStaticWebSite("my-spa", {
  description: "Single page application",
});

// With IP restrictions (disables caching)
export const internalApp = defineStaticWebSite("internal-app", {
  description: "Internal application with restricted access",
  allowedIpAddresses: ["198.51.100.0/24", "203.0.113.0/24"],
});
```

## Deployment

Deploy pre-built static files using TailorCLI. The service is designed for single page applications and will serve `index.html` for unmatched routes.

```bash {{ title: "Deploy Pre-built Files" }}
# Deploy your build output directory
tailor staticwebsite deploy \
  --name my-spa \
  --dir ./dist \
  --workspace_id <workspace-id>
```

## Caching Behavior

* **Public websites** (no IP restrictions): Automatically cached via CDN for optimal performance
* **Restricted websites** (with IP restrictions): Caching is disabled to ensure access control

## Using Generated URLs

Each static website receives a unique URL that can be used in your application configuration. After deploying your static website, you can reference its URL in your application's CORS settings or auth redirect URLs:

```typescript {{ title: "Using Static Website URL in Application Config" }}
import { defineTailorConfig } from "@tailor-platform/sdk";

export default defineTailorConfig({
  workspace: "my-workspace",
  app: {
    name: "my-app",
    // Add static website URL to CORS
    cors: ["https://my-spa-{WORKSPACE_HASH}.web.erp.dev"],
    subgraphs: [/* ... */],
  },
});
```

The static website URL format is: `https://{static-website-name}-{WORKSPACE_HASH}.web.erp.dev`

## Custom Domains

You can use your own subdomain (e.g. `app.example.com`) instead of the auto-generated URL. Apex domains (e.g. `example.com`) are not yet supported. A domain can only belong to one static website. Adding a domain that is already in use will fail.

Each static website supports up to 10 custom domains. After adding a domain, you need to configure DNS CNAME records to complete the setup.

### Adding Custom Domains

There are two ways to add custom domains to a static website.

#### SDK Configuration

Add the `customDomains` field to your `defineStaticWebSite()` definition. Domains are provisioned automatically when you run `tailor deploy`.

```typescript {{ title: "Static Website with Custom Domains" }}
import { defineStaticWebSite } from "@tailor-platform/sdk";

export const mySpa = defineStaticWebSite("my-spa", {
  description: "Single page application",
  customDomains: ["app.example.com"],
});
```

#### CLI

Use the API command to add a custom domain directly.

```bash {{ title: "Add a Custom Domain" }}
tailor api AddCustomDomain --body '{
  "workspace_id": "<workspace-id>",
  "static_website_name": "my-spa",
  "domain": "app.example.com"
}'
```

You can list and inspect custom domains with dedicated subcommands:

```bash {{ title: "List and Get Custom Domains" }}
# List all custom domains for a static website
tailor staticwebsite domain list my-spa

# Get details of a specific custom domain
tailor staticwebsite domain get app.example.com
```

### DNS Configuration

After adding a custom domain, configure CNAME records with your DNS provider. The required targets are returned in the response and can also be retrieved with `tailor staticwebsite domain get`.

| Record Type | Host                              | Target                            | Purpose                                  |
| ----------- | --------------------------------- | --------------------------------- | ---------------------------------------- |
| CNAME       | `app.example.com`                 | Value of `trafficCnameTarget`     | Routes traffic to the CDN                |
| CNAME       | `_acme-challenge.app.example.com` | Value of `certificateCnameTarget` | TLS certificate issuance (DNS challenge) |

For new domains, setting the traffic CNAME is sufficient. The TLS certificate is issued automatically via HTTP challenge. If you are migrating from another service and cannot switch traffic yet, set the `_acme-challenge` record first to issue the certificate via DNS challenge, then update the traffic CNAME when ready.

### Domain Status

Custom domains progress through the following statuses:

| Status        | Description                                          |
| ------------- | ---------------------------------------------------- |
| `pending`     | Domain registered, challenge not yet started         |
| `verifying`   | Challenge in progress, verifying certificate         |
| `cert_issued` | TLS certificate issued, waiting for traffic CNAME    |
| `active`      | TLS certificate active and domain is serving traffic |
| `failed`      | Provisioning failed (see `errorMessage` for details) |

If the challenge does not complete within 7 days, the domain is automatically removed. To retry, add the domain again.

---

---
url: https://docs.tailor.tech/guides/opentelemetry.md
---

# Observability / OpenTelemetry

Tailor Platform automatically generates [OpenTelemetry](https://github.com/open-telemetry/opentelemetry-specification) signals — **traces** and **logs** — for the services in your workspace. By configuring an **OTLP exporter**, you can forward those signals to the observability backend of your choice, such as New Relic, Honeycomb, Grafana, or Datadog, without changing any application code.

Common use cases include:

* Sending request traces from your platform services to an existing distributed tracing backend
* Centralizing platform logs alongside your application logs
* Enriching all outgoing signals with a consistent service name and deployment environment

## How OTLP exporters work

The platform collects the OpenTelemetry signals your services emit and forwards them, over OTLP (the OpenTelemetry Protocol), to each **OTLP exporter** you have configured. These signals include both the traces and logs the platform generates automatically and any structured logs your [Functions](/guides/function/overview) emit via the [`tailor.logger`](/guides/function/builtin-interfaces#logger) API. An OTLP exporter is the resource *you* define — it points at one backend and decides which signals that backend receives. The internal platform component that performs this routing is **TelemetryRouter**; you don't configure it directly, but it is the source of the `tailor_telemetryrouter_` prefix on the resources below.

```mermaid
flowchart TD
  A[Your workspace services<br/>emit OpenTelemetry signals] -->|traces / logs| B[TelemetryRouter<br/>routes your workspace's signals]
  B -->|OTLP| C[OTLP exporter<br/>New Relic]
  B -->|OTLP| D[OTLP exporter<br/>Honeycomb]
  B -->|OTLP| E[OTLP exporter<br/>...]
```

You configure OTLP exporters through the Tailor Terraform provider. There are two resources:

* `tailor_telemetryrouter_otlp_exporter` — defines an export destination. A workspace may have many; each is given a `name` that is unique within that workspace.
* `tailor_telemetryrouter_resource_attributes_config` — defines workspace-level resource attributes attached to every outgoing signal. A workspace has at most one.

A few things to keep in mind:

* **Traces and logs can be enabled independently** per exporter, so each destination receives only the signals you choose.
* **Authentication credentials are never stored inline** — they are referenced from [Secret Manager](secretmanager.md) and resolved at send time.

::: warning Metrics
Tailor does not export metric signals through OTLP exporters today. While the `enable_metrics` field exists, the platform does not currently emit metric signals, so enabling it has no practical effect. Configure your destinations for traces and logs.
:::

## Configuring an OTLP exporter

An OTLP exporter defines a single destination. Most OTLP-compatible backends can be targeted **directly**, with no additional infrastructure on your side.

The following example forwards traces and logs to [New Relic](https://github.com/newrelic), authenticating with a license key stored in Secret Manager:

```hcl {{ title: 'otlp_exporter.tf' }}
resource "tailor_telemetryrouter_otlp_exporter" "newrelic" {
  workspace_id = tailor_workspace.example.id

  name     = "newrelic"
  endpoint = "https://otlp.nr-data.net"
  protocol = "http"

  auth = {
    api_key = {
      header_name = "api-key"
      secret_value = {
        vault_name  = tailor_secretmanager_vault.example.name
        secret_name = "newrelic-license-key"
      }
    }
  }

  enable_traces = true
  enable_logs   = true
}
```

For more backends — including ones that cannot ingest OTLP directly, such as Datadog — see [Backend examples](#backend-examples).

For the full list of arguments and their constraints, refer to the [Tailor Platform Provider documentation](https://registry.terraform.io/providers/tailor-platform/tailor/latest/docs/resources/telemetryrouter_otlp_exporter).

### Authentication

The optional `auth` block configures how Tailor authenticates to the destination. Set **exactly one** of the following.

**API key** — the secret value is sent in the header you name:

```hcl {{ title: 'auth_api_key.tf' }}
auth = {
  api_key = {
    header_name = "x-api-key"
    secret_value = {
      vault_name  = tailor_secretmanager_vault.example.name
      secret_name = "backend-api-key"
    }
  }
}
```

**Bearer token** — the secret value is sent as an `Authorization: Bearer <token>` header:

```hcl {{ title: 'auth_bearer.tf' }}
auth = {
  bearer_token = {
    secret_value = {
      vault_name  = tailor_secretmanager_vault.example.name
      secret_name = "backend-token"
    }
  }
}
```

In both cases `secret_value` references a secret in [Secret Manager](secretmanager.md):

* `vault_name` — the name of the vault that stores the secret
* `secret_name` — the key of the secret within the vault

## Endpoint format

Use a TLS-enabled endpoint (HTTPS) so credentials and signals are encrypted in transit; plaintext endpoints are not recommended, and a plaintext gRPC target fails to connect. The required `endpoint` format depends on the `protocol`:

* **`http`** — an HTTPS base URL, for example `https://otlp.example.com`. Do **not** include the OTLP signal path (`/v1/traces`, `/v1/logs`); it is appended automatically for each enabled signal. Avoid query strings and fragments.
* **`grpc`** — either a bare `host:port` (include the port, for example `otlp.example.com:4317`) or an `https://host[:port]` URL (the port defaults to `443` when omitted). Do not include a path, query string, or fragment.

Endpoints that resolve to a private or internal host (for example RFC 1918 ranges or loopback addresses) are rejected by default.

| Protocol | Recommended                                         | Avoid                                                                                   |
| -------- | --------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `http`   | `https://otlp.example.com`                          | `https://otlp.example.com/v1/traces` (signal path), `http://otlp.example.com` (not TLS) |
| `grpc`   | `otlp.example.com:4317`, `https://otlp.example.com` | `otlp.example.com` (no port), `https://otlp.example.com/path` (has path)                |

## Backend examples

### New Relic

New Relic ingests OTLP directly. Point the exporter at its OTLP endpoint and authenticate with a license key sent in the `api-key` header — see the [example above](#configuring-an-otlp-exporter). Use the OTLP endpoint that matches your New Relic account's region (for example `https://otlp.nr-data.net` for a US account); see New Relic's documentation for the endpoint of your region.

### Honeycomb

[Honeycomb](https://github.com/honeycombio) also ingests OTLP directly. Authenticate with an API key sent in the `x-honeycomb-team` header:

```hcl {{ title: 'honeycomb_exporter.tf' }}
resource "tailor_telemetryrouter_otlp_exporter" "honeycomb" {
  workspace_id = tailor_workspace.example.id

  name     = "honeycomb"
  endpoint = "https://api.honeycomb.io"
  protocol = "http"

  auth = {
    api_key = {
      header_name = "x-honeycomb-team"
      secret_value = {
        vault_name  = tailor_secretmanager_vault.example.name
        secret_name = "honeycomb-api-key"
      }
    }
  }

  enable_traces = true
  enable_logs   = true
}
```

Use the endpoint that matches your Honeycomb account's region (for example `https://api.honeycomb.io` for a US account); see Honeycomb's documentation for the endpoint of your region.

### Routing through an OpenTelemetry Collector (Datadog)

Datadog provides a [direct OTLP intake endpoint](https://docs.datadoghq.com/opentelemetry/setup/otlp_ingest/), but it comes with constraints — trace intake is in preview and requires requesting access, and some behavior differs from the Agent/Collector path. For a full-featured setup, a common approach is to run your own [OpenTelemetry Collector](https://github.com/open-telemetry/opentelemetry-collector) with the Datadog exporter: point your Tailor OTLP exporter at the collector and let it forward signals to Datadog.

This collector pattern applies to any backend you'd rather reach through a collector — for processing, fan-out, or vendor-specific exporters — not just Datadog.

```mermaid
flowchart LR
  A[Tailor Platform<br/>OTLP exporter] -->|OTLP| B[Your OpenTelemetry<br/>Collector]
  B -->|datadog exporter| C[Datadog]
```

#### 1. Configure your OpenTelemetry Collector

Run an OpenTelemetry Collector that receives OTLP from Tailor and exports to Datadog. A minimal configuration:

```yaml {{ title: 'otel-collector.yaml' }}
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317

processors:
  batch: {}

exporters:
  datadog:
    api:
      key: ${env:DD_API_KEY}
      site: datadoghq.com

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [datadog]
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [datadog]
```

This collector must be reachable from Tailor over TLS at a publicly resolvable address. Terminate TLS in front of the collector (for example with a load balancer) and expose its OTLP gRPC endpoint.

#### 2. Point the OTLP exporter at your collector

Configure the exporter `endpoint` to your collector's OTLP endpoint rather than Datadog directly:

```hcl {{ title: 'datadog_exporter.tf' }}
resource "tailor_telemetryrouter_otlp_exporter" "datadog" {
  workspace_id = tailor_workspace.example.id

  name     = "datadog-collector"
  endpoint = "otel-collector.example.com:4317"
  protocol = "grpc"

  enable_traces = true
  enable_logs   = true
}
```

If your collector requires authentication, add an `auth` block as described in [Authentication](#authentication) so the credentials stay in Secret Manager. (The `headers` map can carry static, non-secret headers, but its values are persisted in Terraform state, so don't put credentials there.) Because the endpoint points at your own collector, make sure it is not a private or internal host — see [Endpoint format](#endpoint-format).

## Configuring resource attributes

The `tailor_telemetryrouter_resource_attributes_config` resource defines workspace-level resource attributes that are attached to every outgoing signal. It is a singleton: a workspace has at most one resource attributes configuration.

```hcl {{ title: 'resource_attributes.tf' }}
resource "tailor_telemetryrouter_resource_attributes_config" "this" {
  workspace_id = tailor_workspace.example.id

  service_name_prefix         = "acme"
  deployment_environment_name = "production"
}
```

`service_name_prefix` is prepended to each microservice's own `service.name` to form the final `service.name` attribute on outgoing signals (`<service_name_prefix>-<service.name>`), making platform signals easy to identify in your backend. `deployment_environment_name` follows the OpenTelemetry semantic convention `deployment.environment.name`.

For the full list of arguments and their constraints, refer to the [Tailor Platform Provider documentation](https://registry.terraform.io/providers/tailor-platform/tailor/latest/docs/resources/telemetryrouter_resource_attributes_config).

## Security considerations

* Prefer the `auth` block for credentials: it references secrets in [Secret Manager](secretmanager.md), so the secret values themselves are never stored in the exporter configuration or in Terraform state.
* The `headers` map is marked sensitive (redacted from Terraform plan and diff output), but its values are still persisted in Terraform state. Use it only for non-secret, static headers — put credentials in the `auth` block instead.
* Use TLS-enabled (HTTPS) endpoints so credentials and signals are encrypted in transit. Endpoints that resolve to a private or internal host are rejected.

## Best practices

1. **Separate environments**: Use distinct exporters (and Secret Manager vaults) per environment, and set `deployment_environment_name` accordingly.
2. **Enable only the signals you need**: Leave `enable_traces` / `enable_logs` off for destinations that should not receive a given signal.
3. **Use a consistent service name prefix**: Set `service_name_prefix` so platform signals are easy to identify in your backend.
4. **Rotate credentials**: Update the referenced secret values when rotating API keys or tokens.

---

---
url: https://docs.tailor.tech/guides/ai-gateway.md
---

# AI Gateway&#x20;

AI Gateway provides a unified, OpenAI-compatible endpoint for accessing a range of large language models through a single API. The platform manages all model credentials, so you don't need to bring your own API keys. Every request is authenticated against your workspace's auth, and each gateway is isolated to its own workspace-scoped endpoint.

## How it works

* **One endpoint, many models.** Send standard OpenAI-style requests (`/v1/chat/completions`, `/v1/responses`, `/v1/embeddings`, …) and choose a model by setting the `model` field. The gateway routes the request to the selected model and handles protocol translation for you.
* **Platform-managed credentials.** All model credentials are managed by the platform — you never handle API keys.
* **Mandatory authentication.** Every request is authenticated against the auth namespace you configure. External clients present an application user token; server-side [functions](#calling-from-a-function) are authenticated by the platform and need no token of their own.
* **Per-workspace isolation.** Each gateway is provisioned with its own URL and its own usage tracking and rate limits.

## Configuration

Define an AI Gateway in your `tailor.config.ts` with [`defineAIGateway()`](/sdk/services/aigateway). At minimum you provide a name and the auth namespace used to authenticate requests:

```typescript {{ title: "tailor.config.ts" }}
import { defineAIGateway, defineConfig } from "@tailor-platform/sdk";

const aiGateway = defineAIGateway("my-aigateway", {
  authNamespace: "default",
});

export default defineConfig({
  name: "my-app",
  aiGateways: [aiGateway],
});
```

After deploying, the gateway is reachable at a workspace-scoped URL of the form:

```
https://{gateway-name}-{workspace-hash}.ai.erp.dev
```

See the [SDK reference](/sdk/services/aigateway) for all options, including CORS configuration and type-safe URL references.

## Supported models

Specify the model with the `model` field in the request body. The following models are available:

| Model                    | Type      | Location |
| ------------------------ | --------- | -------- |
| `gemini-3.1-flash-lite`  | Chat      | Global   |
| `gemini-3.5-flash`       | Chat      | Global   |
| `gemini-3.5-flash-lite`  | Chat      | Global   |
| `gemini-3.6-flash`       | Chat      | Global   |
| `gemini-3.7-flash`       | Chat      | Global   |
| `gpt-5`                  | Chat      | Regional |
| `gpt-5-mini`             | Chat      | Regional |
| `gpt-5-nano`             | Chat      | Regional |
| `gpt-5.6-luna`           | Chat      | Regional |
| `gpt-5.6-sol`            | Chat      | Regional |
| `gpt-5.6-terra`          | Chat      | Regional |
| `gemini-embedding-001`   | Embedding | Global   |
| `text-embedding-3-large` | Embedding | Regional |
| `text-embedding-3-small` | Embedding | Regional |

A model's **Type** determines which endpoints it can be used with: **Chat** models are available through `/v1/chat/completions` and `/v1/responses`, and **Embedding** models through `/v1/embeddings`. If the `model` value does not match a supported model exactly, the gateway returns `404 No matching route found`.

### Deprecated models

The following models remain fully available until their retirement date, after which they will stop being served. Please migrate to the suggested replacement before then:

| Model                   | Type | Location | Retires    | Replacement             |
| ----------------------- | ---- | -------- | ---------- | ----------------------- |
| `gemini-2.5-flash`      | Chat | Regional | 2027-01-14 | `gemini-3.5-flash`      |
| `gemini-2.5-flash-lite` | Chat | Global   | 2027-01-14 | `gemini-3.1-flash-lite` |
| `gemini-2.5-pro`        | Chat | Regional | 2027-01-14 | `gemini-3.6-flash`      |
| `gpt-4.1`               | Chat | Regional | 2027-03-31 | `gpt-5.6-terra`         |
| `gpt-4o-mini`           | Chat | Regional | 2027-03-31 | `gpt-5.6-luna`          |

Two things to check before migrating:

* **Region**: all suggested replacements are **Global**, while `gemini-2.5-pro` and `gemini-2.5-flash` are **Regional**. If your workload requires in-region inference for data-residency reasons, note that after retirement no Regional Gemini chat models remain — evaluate whether Global routing is acceptable, or use a Regional model from the table above.
* **Thought signatures**: Gemini 3.x models use [thought signatures](https://ai.google.dev/gemini-api/docs/thought-signatures) — to preserve reasoning quality in multi-turn conversations, return each response's thought signatures in your follow-up requests unchanged.

Validate your workflows against the replacement model before switching.

### Model location and region restriction

Each workspace belongs to a home region (currently **Japan** or **US West**). The **Location** column above indicates where a model runs:

* **Regional** — served from within your workspace's home region. The request and its data stay in that region.
* **Global** — routed dynamically to the nearest available region, which may be outside your workspace's home region.

If you need to keep all inference within a specific region — for data-residency or compliance reasons — use only models marked **Regional**.

## Authentication

Every request must include a valid application user token from your workspace's auth as a Bearer token:

```
Authorization: Bearer <application-user-token>
```

The token is resolved against the `authNamespace` configured on the gateway. Requests without a valid token are rejected. DPoP-bound tokens (`Authorization: DPoP <token>`) are also supported.

Calls made from inside your workspace are the exception: server-side [functions](#calling-from-a-function) are authenticated by the platform and send no `Authorization` header at all.

## Calling the gateway

The endpoint is OpenAI-compatible, so you can use any OpenAI-style client or a plain HTTP request.

### With curl

```bash {{ title: "Chat completion" }}
curl https://my-aigateway-{WORKSPACE_HASH}.ai.erp.dev/v1/chat/completions \
  -H "Authorization: Bearer $APP_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5",
    "messages": [
      { "role": "user", "content": "Hello!" }
    ]
  }'
```

### With the OpenAI SDK

Point the OpenAI client at your gateway URL and pass the application user token as the API key:

```typescript {{ title: "Using the OpenAI SDK" }}
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://my-aigateway-{WORKSPACE_HASH}.ai.erp.dev/v1",
  apiKey: appUserToken, // application user token
});

const completion = await client.chat.completions.create({
  model: "gemini-2.5-pro",
  messages: [{ role: "user", content: "Hello!" }],
});
```

### Available paths

| Method | Path                   | Purpose               |
| ------ | ---------------------- | --------------------- |
| `POST` | `/v1/chat/completions` | Chat completions      |
| `POST` | `/v1/responses`        | Responses API         |
| `POST` | `/v1/embeddings`       | Embeddings            |
| `GET`  | `/v1/models`           | List available models |

The Responses API (`/v1/responses`) returns its result as an `output` array rather than the `choices[]` array used by chat completions — parse the response accordingly.

## Web search & grounding

Both OpenAI and Gemini models can answer with live, web-grounded information and return source citations. The tool, endpoint, and response shape differ by provider.

### OpenAI

Use the Responses API (`/v1/responses`) with the `web_search` tool:

```bash {{ title: "OpenAI web search" }}
curl https://my-aigateway-{WORKSPACE_HASH}.ai.erp.dev/v1/responses \
  -H "Authorization: Bearer $APP_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5",
    "input": "Who won the most recent FIFA World Cup? Include sources.",
    "tools": [{ "type": "web_search" }]
  }'
```

The `output` array holds one or more `web_search_call` items (the searches performed), followed by a `message` whose `output_text` carries the answer and whose `annotations` cite the sources:

```json
{
  "output": [
    { "type": "web_search_call", "status": "completed" },
    {
      "type": "message",
      "content": [
        {
          "type": "output_text",
          "text": "…the answer…",
          "annotations": [
            { "type": "url_citation", "url": "https://example.com/post", "title": "Example" }
          ]
        }
      ]
    }
  ]
}
```

:::tip
Under the default `tool_choice: "auto"`, the model only searches when it judges a query needs it — for a fact it already knows it may answer directly, leaving `annotations` empty. To force a search (and citations), set `tool_choice: "required"`. The older `web_search_preview` tool behaves the same way; prefer the GA `web_search` tool.
:::

### Gemini

Gemini grounding uses the `google_search` tool on `/v1/chat/completions` (not the Responses API). Call it **without streaming** — the grounding data is only present on the final response body, not on streamed SSE chunks:

```bash {{ title: "Gemini google_search" }}
curl https://my-aigateway-{WORKSPACE_HASH}.ai.erp.dev/v1/chat/completions \
  -H "Authorization: Bearer $APP_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.5-flash",
    "messages": [{ "role": "user", "content": "Who won the most recent FIFA World Cup? Include sources." }],
    "tools": [{ "type": "google_search" }]
  }'
```

Grounding appears on `choices[].message.grounding_metadata` — the search queries the model issued and the sources it used:

```json
{
  "choices": [
    {
      "message": {
        "content": "…the answer…",
        "grounding_metadata": {
          "webSearchQueries": ["most recent FIFA World Cup winner"],
          "groundingChunks": [
            {
              "web": {
                "uri": "https://example.com/post",
                "title": "Example",
                "domain": "example.com"
              }
            }
          ]
        }
      }
    }
  ]
}
```

:::warning Web search sends data outside your region and compliance boundary
When you enable web search (`web_search` or `google_search`), your query and relevant request context are sent to an external web search provider — Bing for OpenAI, Google Search for Gemini — to fetch results. That data leaves your workspace's home region and falls outside its data-residency and compliance boundary (see [Model location and region restriction](#model-location-and-region-restriction)). Only enable web search for workspaces where that is acceptable.
:::

## Calling from a Function

Server-side [functions](/guides/function/overview) — resolvers, executor functions, job functions, workflow jobs, and auth hook handlers — can call the gateway with plain `fetch`, and **you do not set an `Authorization` header**. The function runtime recognizes requests addressed to your own workspace's AI Gateway and attaches the execution's identity for you, so no token ever has to be minted, stored, or passed through your code.

:::tip Prefer an asynchronous execution site
LLM inference is slow — a single completion routinely takes tens of seconds, and longer for reasoning-heavy models, long outputs, or [web search](#web-search-grounding). Synchronous execution sites cannot absorb that: resolvers and Function service executions are [capped at 60 seconds](/reference/platform/timeouts), as is the API gateway in front of them, so a slow completion fails the whole operation.

**Call the gateway from a [job function](/guides/executor/job-function-operation) or a [workflow](/sdk/services/workflow) job**, which run asynchronously with a much higher execution ceiling, and have the caller pick the result up afterwards — read it from the record the job writes, or subscribe to the executor or workflow completion event.

Calling from a resolver or an [auth hook](/guides/auth/hook) works but is discouraged. Both make a user wait on inference: a resolver holds the GraphQL request open, and a `beforeLogin` hook adds the latency to **every** login and fails the login outright if the call errors. Reserve them for cases where you know the response is small and fast, and always set a timeout you control.
:::

Resolve the gateway URL with [`aigateway.get()`](/sdk/services/aigateway#runtime-usage) rather than hardcoding it — the name is type-checked against the gateways declared in `aiGateways`:

```typescript {{ title: "executors/summarize-order.ts" }}
import { createExecutor, recordCreatedTrigger } from "@tailor-platform/sdk";
import { aigateway } from "@tailor-platform/sdk/runtime";
import { getDB } from "../generated/tailordb";
import { order } from "../tailordb/order";

export default createExecutor({
  name: "summarize-order",
  trigger: recordCreatedTrigger({ type: order }),
  operation: {
    // Asynchronous, so a slow completion can't time out a caller.
    kind: "jobFunction",
    // Runs the function as this machine user; its auth namespace must be the
    // one the gateway is configured with.
    invoker: "ai-machine-user",
    body: async ({ newRecord }) => {
      const { url } = await aigateway.get("my-aigateway");

      const res = await fetch(`${url}/v1/chat/completions`, {
        method: "POST",
        // No Authorization header — the runtime authenticates the call.
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          model: "gpt-5",
          messages: [{ role: "user", content: `Summarize this order: ${newRecord.notes}` }],
        }),
      });

      const body = await res.json();

      // Persist the result rather than returning it — nothing is waiting.
      await getDB("tailordb")
        .updateTable("Order")
        .set({ summary: body.choices[0].message.content })
        .where("id", "=", newRecord.id)
        .execute();
    },
  },
});
```

Only `https` requests to your own workspace's gateway hostname are treated this way. Every other `fetch` — a third-party API you authenticate with your own key, for example — is left completely untouched.

:::info Not available in inline expressions
Short inline expressions — [TailorDB hooks](/guides/tailordb/hooks), [validations](/guides/tailordb/validations), and default values, plus executor `variables` — are evaluated in a sandbox with no outbound network access at all, so they cannot reach the gateway (or any other host). Move the call into an executor function, job function, resolver, workflow job, or auth hook handler.
:::

### Which identity the request runs as

The gateway sees the identity the function execution itself runs as, which is what the `invoker` option controls:

| Where the function runs                 | Identity attached to the gateway request                                                                                                                |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Resolver](/sdk/services/resolver)      | The resolver's `invoker` machine user if it declares one; otherwise the GraphQL caller.                                                                 |
| Executor `function` / `jobFunction`     | The operation's `invoker` machine user if it declares one; otherwise the user whose action raised the trigger event; otherwise anonymous.               |
| [Workflow](/sdk/services/workflow) jobs | The `invoker` passed when the workflow was started — via `workflow.start(args, { invoker })` or the executor `workflow` operation; otherwise anonymous. |
| [Auth hook](/guides/auth/hook) handler  | The hook's `invoker` machine user, which is always required.                                                                                            |

:::warning The invoker's auth namespace must match the gateway's
The gateway accepts the request only when the identity's auth namespace is the same one the gateway was configured with in `authNamespace`. A machine user from a different auth namespace is rejected with `401 Unauthorized`.

Anonymous executions carry no auth namespace at all, so they are always rejected. In practice this means a schedule-triggered executor, or a workflow started without an invoker, **must** declare an `invoker` to reach the gateway — there is no ambient identity to fall back on.
:::

### Authenticating explicitly instead

If you set an `Authorization` header yourself, the runtime skips its own authentication entirely and sends the request as you wrote it — the [external path](#authentication) with an application user token. Use this when you deliberately want the request to run as a specific end user whose token you already hold.

The internal header the runtime uses is platform-managed: any value your code sets for it is stripped before the request leaves the runtime, so a function cannot pick its own identity by forging one.

## Streaming

Streaming responses (`"stream": true`) are supported across all layers of the gateway. Long-running streams — such as high-effort reasoning — are kept alive by generous upstream timeouts that allow responses to stream for several minutes. The exact limit is managed by the platform and may change; don't rely on a specific value.

Note that this budget is the gateway's own. A stream consumed inside a function is still bounded by that execution's [timeout](/reference/platform/timeouts) — a stream the gateway would happily hold open for minutes will still be cut off at 60 seconds in a resolver. This is another reason to prefer an [asynchronous execution site](#calling-from-a-function).

## CORS

To call the gateway directly from a browser, configure allowed origins with the `cors` option on `defineAIGateway()`. Without it, browsers block cross-origin requests. See the [SDK reference](/sdk/services/aigateway#cors) for the accepted origin formats.

## Usage tracking and rate limiting

Token usage is tracked per workspace, including prompt-caching metrics where the model supports it. Each gateway is rate-limited per workspace. Both are managed by the platform.

---

---
url: https://docs.tailor.tech/guides/tailordb/overview.md
---

# TailorDB

TailorDB is the primary database service within Tailor Platform, where you store and retrieve your data.
TailorDB provides a flexible and scalable database that you build using schema definitions.
A GraphQL endpoint is automatically generated, enabling seamless fetching, creation, updating, and deletion of records.
Additionally, it allows for easy sorting and filtering by any field.

## Defining a Schema

A data model of your application is defined by the schema. The Tailor Platform SDK provides a type-safe TypeScript API for defining your data models.

### Project Structure

Below is a typical folder structure for a Tailor Platform project using the SDK:

```
my-app/
├── tailor.config.ts      # Configuration file
├── tailordb/
│   ├── index.ts          # Exports all tables
│   ├── product.ts        # Product table definition
│   └── category.ts       # Category table definition
├── auth/
│   └── index.ts          # Auth configuration
└── resolver/
    └── index.ts          # Resolvers
```

### Defining a Table

Here's how to define a `Product` table using the SDK:

```typescript
import { db } from "@tailor-platform/sdk";

export const product = db.table("Product", "Product data schema", {
  title: db.string().description("Title of the product").index(),
  description: db.string().description("Description of the product"),
  price: db.float(),
  ...db.fields.timestamps(),
});
export type product = typeof product;
```

The SDK provides:

* **Type-safe field definitions** with TypeScript autocomplete
* **Fluent API** for field modifiers (`.index()`, `.unique()`, `.description()`)
* **Built-in field helpers** like `db.fields.timestamps()` for common patterns

```typescript
import { db } from "@tailor-platform/sdk";

export const product = db
  .table("Product", "Product data schema", {
    title: db.string().description("Title of the product").index(),
    description: db.string().description("Description of the product"),
  })
  .permission({ read: [[{ user: "_loggedIn" }, "=", true]] });
```

## Field Types

The SDK supports the following field types:

| Method          | TailorDB Type | TypeScript Type |
| --------------- | ------------- | --------------- |
| `db.string()`   | String        | string          |
| `db.int()`      | Integer       | number          |
| `db.float()`    | Float         | number          |
| `db.bool()`     | Boolean       | boolean         |
| `db.date()`     | Date          | string          |
| `db.datetime()` | DateTime      | string          |
| `db.time()`     | Time          | string          |
| `db.uuid()`     | UUID          | string          |
| `db.enum()`     | Enum          | string          |
| `db.object()`   | Nested        | object          |

### Optional and Array Fields

```typescript
db.string({ optional: true });
db.string({ array: true });
db.string({ optional: true, array: true });
```

### Enum Fields

```typescript
db.enum(["red", "green", "blue"]);
db.enum([
  { value: "active", description: "Active status" },
  { value: "inactive", description: "Inactive status" },
]);
```

### Object Fields (Nested)

```typescript
db.object({
  street: db.string(),
  city: db.string(),
  country: db.string(),
});
```

## Auto-generated GraphQL API

In TailorDB, the GraphQL APIs are [automatically generated](/guides/tailordb/auto-generated-api) based on your schema definitions.

## Schema Composition

### Basic Structure

A TailorDB table definition consists of:

* **Table name** (Required): The name of the data model
* **Description** (Optional): Description shown in GraphQL SDL and playground
* **Fields** (Required): Field definitions with types and modifiers

```typescript
export const task = db.table("Task", "Task management entity", {
  title: db.string().description("Task title"),
  completed: db.bool(),
  dueDate: db.datetime({ optional: true }),
  ...db.fields.timestamps(),
});
export type task = typeof task;
```

See [Fields](fields) for detailed field configuration options.

### Permissions

TailorDB follows a **secure-by-default** principle. All operations are denied unless explicitly granted.

```typescript
db.table("Task", {
  title: db.string(),
  ownerId: db.uuid(),
  ...db.fields.timestamps(),
}).permission({
  create: [[{ user: "role" }, "=", "admin"]],
  read: [
    [{ user: "role" }, "=", "admin"],
    [{ record: "ownerId" }, "=", { user: "id" }],
  ],
  update: [[{ record: "ownerId" }, "=", { user: "id" }]],
  delete: [[{ user: "role" }, "=", "admin"]],
});
```

See [Permission](permission) for more information.

## Advanced Features

### Table Features

Enable additional GraphQL operations with the `.features()` modifier:

```typescript
db.table("Product", {
  name: db.string(),
  price: db.float(),
  ...db.fields.timestamps(),
}).features({
  aggregation: true, // Enable aggregate queries
  bulkUpsert: true, // Enable bulk upsert mutations
});
```

See [Advanced Settings](advanced-settings/overview) for more information.

### Composite Indexes

Create multi-field indexes for query optimization:

```typescript
db.table("Order", {
  customerId: db.uuid(),
  orderDate: db.datetime(),
  ...db.fields.timestamps(),
}).indexes({
  fields: ["customerId", "orderDate"],
  name: "customer_order_idx",
});
```

See [Indexes](indexes) for more information.

## Next Steps

* [Fields](fields) - Detailed field type configuration
* [Relationships](relationships) - Define relations between tables
* [Hooks](hooks) - Add custom logic on create/update
* [Validations](validations) - Field-level data validation
* [Permission](permission) - Access control configuration

---

---
url: https://docs.tailor.tech/guides/tailordb/auto-generated-api.md
---

# Auto-generated APIs

Based on the name of the schema, GraphQL APIs are automatically generated.
Each query has fields defined in the schema. See [fields](/guides/tailordb/fields) section for details.
The following generated queries and mutations are available for use:

## Queries

* `<type_name>`: return a single resource based on the provided resource ID.
* `<type_name>By`: return a single resource based on the unique field value.\
  To enable this query, you need to set `unique` and `index` as `true` in the field settings. See [Supporting fields](/guides/tailordb/fields#uniqueindex) for more details.
* `<type_name>s`: return multiple resources based on a search query (*query*), pagination parameters, and a sorting parameter (*order*).
* `<type_name>Permission`: return permissions set in the resource based on the provided resource ID.

### Pagination

We support cursor pagination by default in TailorDB. This approach enables for more efficient data retrieval, especially for large datasets.\
Cursor pagination uses cursors like `after` and `first` to fetch data relative to a specific point.

```graphql
type Query {
  users(
    query: UserQueryInput
    order: UserOrderInput
    first: Int
    after: String
    last: Int
    before: String
  ): UserConnection!
}
type UserConnection {
  edges: [UserEdge!]!
  pageInfo: PageInfo!
  total: Int
}
type UserEdge {
  node: User!
  cursor: String!
}
type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}
```

**The string input for `after` or `before` needs to be a base64-encoded representation of the cursor.**

The number of records retrieved is determined by the `first` or `last` parameter:

* If neither `first` nor `last` is specified, `first` defaults to `DefaultQueryLimitSize` (default: 100).
* If both `first` and `last` are specified, an error is returned.
* If `first` or `last` is less than 0 or greater than 1000, an error is returned.

The retrieval order of records is determined by the `order` parameter:

* If no `order` is specified, the records will be retrieved in the order they were created, using `_created` (an internal field) and `id` to generate the cursor.
* If an `order` is specified, the cursor is created using the specified field and `id`.

#### Example Query

```graphql {{ title: "query"}}
query users {
  users(
    first: 3
    # Without specifying after, retrieve the first 3 records
    order: [{ field: name, direction: Asc }]
  ) {
    pageInfo {
      hasNextPage
      endCursor
    }
    edges {
      node {
        name
      }
    }
  }
}
```

```json {{ title: "response"}}
{
  "data": {
    "users": {
      "pageInfo": {
        "hasNextPage": true,
        "endCursor": "W3siZm...In1d"
      },
      "edges": [
        {
          "node": {
            "name": "user1"
          }
        },
        {
          "node": {
            "name": "user2"
          }
        },
        {
          "node": {
            "name": "user3"
          }
        }
      ]
    }
  }
}
```

```graphql {{ title: "query"}}
query users {
  users(
    first: 3
    # Specifying the endCursor from the previous response to retrieve the next 3 records.
    after: "W3siZm...In1d"
    order: [{ field: name, direction: Asc }]
  ) {
    pageInfo {
      hasNextPage
      endCursor
    }
    edges {
      node {
        name
      }
    }
  }
}
```

```json {{ title: "response"}}
{
  "data": {
    "users": {
      "pageInfo": {
        // Since hasNextPage is false, there is no point in retrieving more records.
        "hasNextPage": false,
        "endCursor": "W3siZm...In1d"
      },
      "edges": [
        {
          "node": {
            "name": "user4"
          }
        },
        {
          "node": {
            "name": "user5"
          }
        }
      ]
    }
  }
}
```

### Sorting

You can use the `order: [QueryNameOrderInput]` argument to sort the results of the query.
The argument accepts an array of QueryNameOrderInput values, each of which will be evaluated in the order specified in the array.

| Argument  | Description                         |
| --------- | ----------------------------------- |
| direction | Desc or Asc                         |
| field     | Field name as the enumeration value |

### Filtering

Refer to [Filters](/guides/tailordb/filters) guide.

## Mutations

### Create, Update and Delete

* `create<type_name>`: create the resource based on the values provided for each field.
* `update<type_name>`: update the resource based on the provided resource ID and the values provided for each field.
* `delete<type_name>`: delete the resource based on the provided resource ID.

### Conditional Update

The Conditional Update feature is available in all automatically generated update mutations, allowing atomic updates that occur only when specified conditions are met. This ensures data consistency by preventing updates when conditions are not satisfied.

When performing an update, you can specify a condition query alongside the update data. The update executes only if the condition matches the current record state; otherwise, an error is returned. The condition query follows the same format as filter queries in list operations.

To use conditional updates, include a condition parameter in your update mutation, using the same filter format as query parameters in list operations. For example, to update an Episode title to "Return of the Jedi" only if its current title is "A New Hope":

```graphql
mutation {
  updateEpisode(
    id: "b666346f-0b2d-42f7-bcba-b18f46ee573d"
    input: { title: "Return of the Jedi" }
    condition: { title: { eq: "A New Hope" } }
  ) {
    id
    title
  }
}
```

You can use all filter operators including logical operators like `and`, `or`, and `not`. For more details on filters, see [Filters](/guides/tailordb/filters).

### Change Permission

* `change<type_name>`: change the permission of the resource based on the provided resource ID and `PermissionItemInput` values for read, update, and delete actions.
  `PermissionItemInput` has a `PermitEnum` field that can be either `allow` or `deny`. **Note:** This mutation is part of the deprecated Legacy Permission system. Consider using the [new Permission system](/guides/tailordb/permission) for new applications.

# Example

As the example, if you specify this `Report` schema, the following queries and mutations API will be automatically generated based on the schema.

Besides basic CRUD operations, [Aggregation](/guides/tailordb/advanced-settings/aggregation), [Bulk upsert](/guides/tailordb/advanced-settings/bulk-upsert) and more available as [Advanced APIs](/guides/tailordb/advanced-settings/overview).

---

---
url: https://docs.tailor.tech/guides/tailordb/fields.md
---

# Fields in schema

As explained in the [Basic Structure of a Schema](/guides/tailordb/overview#basicstructureofaschema), each field of the data model (corresponding to columns in a relational database) is defined in the `fields` property of the schema file.

Here, we will discuss how to configure the schema within the `Fields` property.

## Properties of `Fields`

As shown in the example schema below, `Fields` contains the following structure

* Field name: the name for the field (required).
* `Description`: the description of the field in String. This will appear in GraphQL SDL and Playground (required).
* `Type`: the data type of the field (required). Have to be one of [Data types](/guides/tailordb/fields#datatype)

With just this, the GraphQL API is automatically generated.

```typescript {{title: "tailordb/product.ts"}}
import { db } from "@tailor-platform/sdk";

export const product = db.table("Product", "Product data schema", {
  title: db.string().description("Title of the product").index(),
  description: db.string().description("Description of the product"),
  ...db.fields.timestamps(),
});
export type product = typeof product;
```

```sh {{title: "product.tf"}}
  resource "tailor_tailordb_type" "product" {
    workspace_id = tailor_workspace.ims.id
    namespace    = tailor_tailordb.ims.namespace
    name         = "Product"
    description  = "Product data schema"

    settings = {
      draft = true
    }

    fields = {
      title = {
    	  type        = "string"
    	  description = "Title of the product"
    	  index       = true
    	  required    = true
      }
      description = {
    	  type        = "string"
    	  description = "Description of the product"
      }
    }
    type_permission = local.permission_everyone
  }
```

## Naming rules

Field names should use lower camel case (e.g., priceTotal) and must not contain spaces or special characters. Therefore, snake case naming (e.g., price\_total) is not allowed.
Use only alphabetic characters (A-Z, a-z) and numeric characters (0-9), and do not start with a numeric character.
Even if the field name violates this rule, the API is still auto-generated, but it does not work correctly.

## Data type

```typescript
// Example: set data type as string
name: db.string();
```

The SDK provides the following field type methods:

| SDK Method      | Type     | Description               |
| --------------- | -------- | ------------------------- |
| `db.string()`   | String   | String value              |
| `db.uuid()`     | UUID     | UUID formatted string     |
| `db.int()`      | Integer  | 32-bit integer            |
| `db.float()`    | Float    | 128-bit decimal           |
| `db.enum()`     | Enum     | Enumerated values         |
| `db.bool()`     | Boolean  | Boolean value             |
| `db.time()`     | Time     | Time in HH:MM format      |
| `db.date()`     | Date     | Date in YYYY-MM-DD format |
| `db.datetime()` | DateTime | ISO 8601 datetime         |
| `db.object()`   | Nested   | Nested object fields      |

```sh
  // Example: set data type as string
  name = {
  	type = "string"
  }
```

Visit [tailordb types](https://registry.terraform.io/providers/tailor-platform/tailor/latest/docs/resources/tailordb_type) to learn more about the types.

Here are the available list of data types in TailorDB.
For details about the filter, refer to [TailorDB Filter](/guides/tailordb/filters) specification.

| Predefined Data Type | Type Description                                                                                                                            | Available Filters                          |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| string               | String                                                                                                                                      | eq, ne, in, nin, contains, regex           |
| uuid                 | String of of 32 hexadecimal digits as defined in [RFC4122](https://www.ietf.org/rfc/rfc4122.txt) ex. `f81d4fae-7dec-11d0-a765-00a0c91e6bf6` | eq, ne, in, nin                            |
| integer              | 32-bit integer                                                                                                                              | eq, ne, lt, lte, gt, gte, between, in, nin |
| float                | 128-bit decimal-based floating-point number                                                                                                 | eq, ne, lt, lte, gt, gte, between, in, nin |
| enum                 | Enum. Values are defined in `values` field                                                                                                  | eq, ne, in, nin                            |
| bool                 | Boolean                                                                                                                                     | eq, ne                                     |
| time                 | String in the format `HH:MM` ex. "12:45"                                                                                                    | eq, ne, lt, lte, gt, gte, between, in, nin |
| date                 | String in the format `YYYY-MM-DD` ex. "2022-10-10"                                                                                          | eq, ne, lt, lte, gt, gte, between, in, nin |
| datetime             | String in the ISO 8601 format `yyyy-MM-ddTHH:mm:ss` ex. "2024-06-25T19:34:42Z"                                                              | eq, ne, lt, lte, gt, gte, between, in, nin |
| nested               | A type with nested fields. Nested fields are defined in `fields` field                                                                      | ----                                       |

Additionally, you can configure a field to automatically generate sequential numbers using the `serial` property. See [Serial](#serial) for more details.

As for the `Type` field, set one of the following data types as `tailordb.#<field_type>`.

For example, to set the `TypeString` data type to the `name` field, use the following setting:

Here are the available list of data types in TailorDB.
For details about the filter, refer to [TailorDB Filter](/guides/tailordb/filters) specification.

| Predefined Data Type | Type Description                                                                                                                            | Available Filters                          |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| TypeString           | String                                                                                                                                      | eq, ne, in, nin, contains, regex           |
| TypeUUID             | String of of 32 hexadecimal digits as defined in [RFC4122](https://www.ietf.org/rfc/rfc4122.txt) ex. `f81d4fae-7dec-11d0-a765-00a0c91e6bf6` | eq, ne, in, nin                            |
| TypeInt              | 32-bit integer                                                                                                                              | eq, ne, lt, lte, gt, gte, between, in, nin |
| TypeFloat            | 128-bit decimal-based floating-point number                                                                                                 | eq, ne, lt, lte, gt, gte, between, in, nin |
| TypeEnum             | Enum. Values are defined in `values` field                                                                                                  | eq, ne, in, nin                            |
| TypeBool             | Boolean                                                                                                                                     | eq, ne                                     |
| TypeTime             | String in the format `HH:MM` ex. "12:45"                                                                                                    | eq, ne, lt, lte, gt, gte, between, in, nin |
| TypeDate             | String in the format `YYYY-MM-DD` ex. "2022-10-10"                                                                                          | eq, ne, lt, lte, gt, gte, between, in, nin |
| TypeDateTime         | String in the ISO 8601 format `yyyy-MM-ddTHH:mm:ss` ex. "2024-06-25T19:34:42Z"                                                              | eq, ne, lt, lte, gt, gte, between, in, nin |
| TypeNested           | A type with nested fields. Nested fields are defined in `fields` field                                                                      | ----                                       |

Additionally, you can configure a field to automatically generate sequential numbers using the `Serial` property. See [Serial](#serial) for more details.

## Auto-generated GraphQL data fields

Besides the fields specified within the fields parameter, TailorDB automatically generates the following system fields for each Type in the GraphQL Schema:

Please be aware that these names are reserved for system use and cannot be employed as user-defined field names.

| GraphQL field name | Data Type | Description                                                                                 |
| ------------------ | --------- | ------------------------------------------------------------------------------------------- |
| `id`               | UUID      | UUID formatted unique identifier of the resource. Acts as the primary key of the resources. |
| `createdBy`        | createdBy | ID of the user and the user's organization who created the resource.                        |
| `updatedBy`        | updatedBy | ID of the user and the user's organization who updated the resource.                        |

## Supporting fields

Describing more complex data models is also simple. By adding the following optional parameters to the field, you can set default values, array types, relations to other models, unique keys or foreign keys, and input value validation, among other things.

### Required

If this field is set, the value must be provided.
The data type of the field is `Boolean`.

### Array

If this field is set, the field value will be an array.
The data type of the field is `Boolean`.

### Unique / Index

If these fields are set to true, the field value will be subject to uniqueness constraints.
However, you can set only the index option to true when the field is not unique.
To enforce uniqueness, both options must be enabled.
The data type of the fields are both `Boolean`.

### AllowedValues (used only in Enum)

If the field data type is `TypeEnum`, this can be used to define the enumerated values.
The data type of the field is `String`. You can describe each defined value using the `Description` property.

```typescript
inventoryType: db.enum([
  { value: "INVENTORY", description: "INVENTORY type" },
  { value: "NON_INVENTORY", description: "NON_INVENTORY type" },
  { value: "SERVICE", description: "SERVICE type" },
]).description("Different categories of product");
```

```sh
  inventoryType = {
  	type        = "enum"
  	description = "Different categories of product"
  	allowed_values = [
  		{
  			value       = "INVENTORY"
  			description = "INVENTORY type"
  		},
  		{
  			value       = "NON_INVENTORY"
  			description = "NON_INVENTORY type"
  		},
  		{
  			value       = "SERVICE"
  			description = "SERVICE type"
  		}
  	]
  }
```

### Fields (used only in Nested)

If the field data type is `TypeNested`, use this to define the nested fields within the structure.
The data type of the field is the same as that of the parent field.

### SourceId (used for linking other Table)

If you want to link the data from a different table, you can use the SourceId field to create the link.
The data type of `SourceId` field is `UUID`.

#### Example

```typescript
  // Define a relation to another type
  supplierId: db.uuid().description("UUID of type Supplier").index(),
  supplier: db.relation("Supplier", "supplierId").description("Link to the model Supplier"),
```

```sh
  species = {
  	type        = "Species"
  	description = "Species of the character"
  	source      = "speciesID"
  }
  speciesID = {
  	type        = "uuid"
  	description = "Species ID of the character"
  	index       = true
  	foreign_key = {
  		type  = "Species"
  		field = "id"
  	}
  }
```

### Foreign key

Foreign key constraints are automatically applied when using `db.relation()`. For explicit foreign key configuration:

```typescript
// Foreign key with relation
supplierId: db.uuid().description("UUID of type Supplier").index(),
supplier: db.relation("Supplier", "supplierId"),
```

Foreign key `type` and `field` can be configured when the source field is set.
If these fields are specified, the field value will be subject to foreign key constraints.
The `field` is optional and defaults to id. To improve query performance, enable indexing on foreign key fields by setting index to true.

The data type of the foreign key `type` and `field` is `string`.

#### Example

```sh
// add foreign key constraints
speciesID = {
	type        = "uuid"
	description = "Species ID of the character"
	foreign_key = {
		type  = "Species"
		field = "id" // optional. if you don't set "field", "id" is used by default.
	}
}
```

`ForeignKey`,`ForeignKeyType` and `ForeignKeyField` can be configured in case `SourceId` field is set.
If these fields are set, the field value will be subject to foreign key constraints.
For this to take effect, both `ForeignKey` and `ForeignKeyType` must be enabled.
`ForeignKeyField` is an *optional* field where you can specify `ForeignKeyType`'s field. By default, it is `id`.
To improve query performance, enable indexing on foreign key fields by setting index to true.

The data type of `ForeignKey` is `Boolean`, that of `ForeignKeyType` and `ForeignKeyField` is `String`.

#### Example

### Validate

If this field is set, validation rules will be applied to the field value.
Validations are evaluated after all properties are evaluated. For example, hooks will always run first then validation.
The data type of the field is an array of maps, with `Expr` and `Action` defined. Learn more in [Data Validations](/guides/tailordb/validations).

### Hooks

If this field is set, the field value is computed using the given expression.
Hooks are evaluated before validation.
Learn more in [Hooks](/guides/tailordb/hooks).

### Serial

If this field is set, the field value will be automatically assigned a sequential number when a new record is created.
The data type of the field can be either `Integer` or `String`.
When a Serial Field is specified, this field cannot be set as required.

The sequence part is represented as a number (or its representation in different bases).
During record creation, the Serial Field gets a value from a sequence generator.
However, if a value is already specified for the field, the Serial Field won't overwrite it.

For string fields with Format specified, the formatted string is applied.

The Serial configuration includes the following options:

* `Start`: The starting number for the sequence (required).
* `MaxValue`: The maximum value for the sequence (optional).
* `Format`: A printf notation string to format the sequence number (optional, only for String type fields).
  * The format must follow the C printf style, containing exactly one conversion specifier (`%d`, `%o`, `%x`, or `%X`), optionally preceded by a width specifier, with any other characters allowed. For example, `"No:%03d"` with a value of 5 would display as `No:005`.
  * Format must be within 32 characters.

If Start or MaxValue is changed, the sequence generator is altered.
Format changes don't alter the sequence generator.
Serial Fields cannot be used in nested fields.

```typescript
serial: db.string()
  .description("Serial Number of the episode")
  .index()
  .unique()
  .serial({ start: 1000, maxValue: 9999, format: "EP#%04d" });
```

```sh
  serial = {
  	type        = "string"
  	description = "Serial Number of the episode"
  	index       = true
  	unique      = true
  	serial      = {
  		start    = 1000
  		max_value = 9999
  		format   = "EP#%04d"
  	}
  }
```

#### Example

```typescript {{title: "tailordb/episode.ts"}}
import { db } from "@tailor-platform/sdk";

export const episode = db.table("Episode", "Episode data schema", {
  title: db.string().description("Title of the episode"),
  serial: db
    .string()
    .description("Serial Number of the episode")
    .index()
    .unique()
    .serial({ start: 1000, maxValue: 9999, format: "EP#%04d" }),
  ...db.fields.timestamps(),
});
export type episode = typeof episode;
```

```graphql
# GraphQL mutation
mutation createEpisode($title: String!) {
  createEpisode(input: { title: $title }) {
    id
    title
    serial
  }
}
```

```json
# Result
{
  "data": {
    "createEpisode": {
      "id": "b25f81f9-3409-4c47-8ad8-0e8720f1e341",
      "title": "hello3",
      "serial": "EP#1000"
    }
  }
}
```

```sh
  // TailorDB config
  resource "tailor_tailordb_type" "episode" {
  	workspace_id = tailor_workspace.example.id
  	namespace    = tailor_tailordb.example.namespace
  	name         = "Episode"
  	description  = "Episode data schema"

  	fields = {
  		title = {
  			type        = "string"
  			description = "Title of the episode"
  			required    = true
  		}
  		serial = {
  			type        = "string"
  			description = "Serial Number of the episode"
  			index       = true
  			unique      = true
  			serial      = {
  				start    = 1000
  				max_value = 9999
  				format   = "EP#%04d"
  			}
  		}
  	}
  }
```

```graphql
# GraphQL mutation
mutation createEpisode($title: String!) {
  createEpisode(input: { title: $title }) {
    id
    title
    serial
  }
}
```

```json
# Result
{
	"data": {
		"createEpisode": {
			"id": "b25f81f9-3409-4c47-8ad8-0e8720f1e341",
			"title": "hello3",
			"serial": "EP#1000"
		}
	}
}
```

```graphql
# GraphQL mutation
mutation createEpisode($title: String!) {
  createEpisode(input: { title: $title }) {
    id
    title
    serial
  }
}
```

```json
# Result
{
	"data": {
		"createEpisode": {
			"id": "b25f81f9-3409-4c47-8ad8-0e8720f1e341",
			"title": "hello3",
			"serial": "EP#1000"
		}
	}
}
```

---

---
url: https://docs.tailor.tech/guides/tailordb/file-type.md
---

# File Type

TailorDB File Type enables developers to attach files to records in their data model, providing seamless file management capabilities integrated with GraphQL queries and HTTP operations. This feature eliminates the need for separate file storage solutions by providing:

* Integrated file storage with TailorDB records
* Attachment file management (size, checksum, content type, timestamps)
* Permission-based access control aligned with record-level permissions
* GraphQL query integration for file metadata filtering

## Basic Workflow

1. Define file attachments in your schema
2. Create records with file attachment fields
3. Upload files via HTTP PUT to auto-generated URLs
4. Query file info through GraphQL
5. Download files via HTTP GET
6. Delete files via HTTP DELETE

## Schema Definition

Files are defined in the **Files** section (not Fields) of your table definition. Each file type field in a record has a reserved URL endpoint that serves as both the upload and download location for that specific field. This URL is automatically generated when the record is created and remains constant throughout the record's lifecycle.

```typescript {{ title: "Schema Definition" }}
db.table("Starship", {
  name: db.string().description("Name of the starship"),
  blueprint: db.file().description("Technical blueprint file"),
  thumbnail: db.file().description("Thumbnail image"),
});
```

## GraphQL Operations

### Querying File Metadata

When you query a record with file attachments, each file field returns metadata about the attached file:

```graphql {{ title: "Get Record with File Metadata" }}
query show {
  starship(id: "72f157d3-9f3f-40f8-9517-7627909d3580") {
    name
    blueprint {
      url
      urlPath
      size
      contentType
      lastUploadedAt
      sha256sum
    }
    thumbnail {
      url
      urlPath
      size
      contentType
      lastUploadedAt
      sha256sum
    }
  }
}
```

```json {{ title: "Response" }}
{
  "data": {
    "starship": {
      "name": "Millennium Falcon",
      "blueprint": {
        "url": "https://{YOUR_APP_SUBDOMAIN}.erp.dev/files/tailordb/galaxy/Starship/blueprint/72f157d3-9f3f-40f8-9517-7627909d3580",
        "urlPath": "/files/tailordb/galaxy/Starship/blueprint/72f157d3-9f3f-40f8-9517-7627909d3580",
        "size": 6542,
        "contentType": "image/png",
        "lastUploadedAt": "2025-08-26T10:09:13.452171+09:00",
        "sha256sum": "a6034bb72c22843b3b06e59a8a9bf85b58fec62d71e69fe9c2ab61924fc25a98"
      },
      "thumbnail": {
        "url": "https://{YOUR_APP_SUBDOMAIN}.erp.dev/files/tailordb/galaxy/Starship/thumbnail/72f157d3-9f3f-40f8-9517-7627909d3580",
        "urlPath": "/files/tailordb/galaxy/Starship/thumbnail/72f157d3-9f3f-40f8-9517-7627909d3580",
        "size": null,
        "contentType": null,
        "lastUploadedAt": null,
        "sha256sum": null
      }
    }
  }
}
```

### File Metadata Properties

| Property       | Type     | Description                             |
| -------------- | -------- | --------------------------------------- |
| url            | String!  | Upload/download endpoint URL            |
| urlPath        | String!  | Path portion of the URL                 |
| size           | Int      | File size in bytes (null before upload) |
| sha256sum      | String   | SHA256 checksum of file content         |
| lastUploadedAt | DateTime | Timestamp of last upload                |
| contentType    | String   | MIME type of the file                   |

### Filtering by File Existence

You can filter records based on whether files exist:

```graphql {{ title: "Query with File Filters" }}
query getStarshipsWithFiles {
  starships(query: { blueprint: { exists: true } }) {
    edges {
      node {
        id
        name
        blueprint {
          url
          size
          contentType
          sha256sum
          lastUploadedAt
        }
      }
    }
  }
}
```

## HTTP File Operations

### Upload File

Use HTTP PUT to upload a file to the auto-generated URL endpoint:

```bash {{ title: "Upload File" }}
curl -X PUT \
  "https://{YOUR_APP_SUBDOMAIN}.erp.dev/files/tailordb/galaxy/Starship/cd7b898e-3779-4e3f-b484-607e92df1ebc/blueprint" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/pdf" \
  --data-binary @blueprint.pdf
```

### Download File

Use HTTP GET to download a file from the endpoint:

```bash {{ title: "Download File" }}
curl -X GET \
  "https://{YOUR_APP_SUBDOMAIN}.erp.dev/files/tailordb/galaxy/Starship/cd7b898e-3779-4e3f-b484-607e92df1ebc/blueprint" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o downloaded_blueprint.pdf
```

### Delete File

Use HTTP DELETE to remove a file:

```bash {{ title: "Delete File" }}
curl -X DELETE \
  "https://{YOUR_APP_SUBDOMAIN}.erp.dev/files/tailordb/galaxy/Starship/cd7b898e-3779-4e3f-b484-607e92df1ebc/blueprint" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

## Limitations and Notes

* You can specify up to **10 file types** in the Files section of your schema
* The maximum file size allowed for upload is **100 MB**
* If you upload a file to the same endpoint, the existing file will be overwritten
* File access permissions are aligned with record-level permissions
* Each file attachment has a unique, persistent URL that remains constant throughout the record's lifecycle
* **When a record is deleted, all attached files are automatically deleted as well**

## Related Documentation

* [Fields](/guides/tailordb/fields) - Learn about other field types in TailorDB
* [Auto-generated API](/guides/tailordb/auto-generated-api) - Understand the GraphQL API structure
* [Permission](/guides/tailordb/permission) - Configure access control for your data

---

---
url: https://docs.tailor.tech/guides/tailordb/filters.md
---

# Query filters

To filter data, you can use query filters.

The available operator sets for query filters depend on the data type. These same filters can also be used for [conditional updates](/guides/tailordb/auto-generated-api#conditionalupdate).

To apply a query filter to a `<data_type>` type, use the `input <data_type>Filter` input.

For example, for a `String` data type, use `input StringFilter`.

## Filters for each data type

### StringFilter

| Operator     | Description                                  |
| ------------ | -------------------------------------------- |
| eq           | = Equals                                     |
| ne           | <> or != Not Equals                         |
| in           | Allows you to specify multiple string values |
| nin          | Allows you to specify multiple string values |
| contains     | Contains target string                       |
| notContains  | Does not contain target string               |
| hasPrefix    | Starts with target string                    |
| hasSuffix    | Ends with target string                      |
| notHasPrefix | Does not start with target string            |
| notHasSuffix | Does not end with target string              |
| regex        | Regular expression search                    |

#### Examples

```graphql {{ title: "Pick data where carName equals XXX" }}
{
  cars(query: { carName: { eq: "XXX" } }) {
    edges {
      node {
        id
      }
    }
  }
}
```

```graphql {{ title: "Pick data where carName matches regex [0-9]+" }}
{
  cars(query: { carName: { regex: "[0-9]+" } }) {
    edges {
      node {
        id
      }
    }
  }
}
```

```graphql {{ title: "Pick data where carName contains YY string" }}
{
  cars(query: { carName: { contains: "YY" } }) {
    edges {
      node {
        id
      }
    }
  }
}
```

```graphql {{ title: "Pick data where carName does not contain YY string" }}
{
  cars(query: { carName: { notContains: "YY" } }) {
    edges {
      node {
        id
      }
    }
  }
}
```

```graphql {{ title: "Pick data where carName starts with XX string" }}
{
  cars(query: { carName: { hasPrefix: "XX" } }) {
    edges {
      node {
        id
      }
    }
  }
}
```

```graphql {{ title: "Pick data where carName ends with YY string" }}
{
  cars(query: { carName: { hasSuffix: "YY" } }) {
    edges {
      node {
        id
      }
    }
  }
}
```

```graphql {{ title: "Pick data where carName does not start with XX string" }}
{
  cars(query: { carName: { notHasPrefix: "XX" } }) {
    edges {
      node {
        id
      }
    }
  }
}
```

```graphql {{ title: "Pick data where carName does not end with YY string" }}
{
  cars(query: { carName: { notHasSuffix: "YY" } }) {
    edges {
      node {
        id
      }
    }
  }
}
```

### Integer, Float, DateTime, Date, and Time Filters

| Operator | Description                                                                |
| -------- | -------------------------------------------------------------------------- |
| eq       | =Equals                                                                    |
| ne       | <>or != Not Equals                                                        |
| lt       | < Less Than                                                               |
| lte      | <= Less Than Equals                                                       |
| gt       | > Greater Than                                                             |
| gte      | >= Greater Than Equals                                                     |
| between  | {min:x, max: y}                                                           |
|          | x <= n && n <= y Between x and y.                                        |
| in       | in: \[x, y …. ] Allows you to specify multiple values (n == x or n == y)   |
| nin      | nin: \[x, y …. ] Allows you to specify multiple values (n != x and n != y) |

#### Examples

```graphql {{ title: "Pick data where carNumber is greater than 10" }}
{
  cars(query: { carNumber: { gt: 10 } }) {
    edges {
      node {
        id
      }
    }
  }
}
```

```graphql {{ title: "Pick data where carNumber is between 5 and 10" }}
{
  cars(query: { carNumber: { between: { min: 5, max: 10 } } }) {
    edges {
      node {
        id
      }
    }
  }
}
```

```graphql {{ title: "Pick data where carNumber is 1 or 2 or 3" }}
{
  cars(query: { carNumber: { in: [1, 2, 3] } }) {
    edges {
      node {
        id
      }
    }
  }
}
```

### EnumFilter

| Operator | Description                                                                     |
| -------- | ------------------------------------------------------------------------------- |
| eq       | =Equals enum value                                                              |
| ne       | <>or != Not Equals enum value                                                  |
| in       | in: \[x, y …. ] Allows you to specify multiple enum values (n == x or n == y)   |
| nin      | nin: \[x, y …. ] Allows you to specify multiple enum values (n != x and n != y) |

### UUIDFilter

| Operator | Description                                                                   |
| -------- | ----------------------------------------------------------------------------- |
| eq       | =Equals enum value                                                            |
| ne       | <>or != Not Equals enum value                                                |
| in       | in: \[x, y …. ] Allows you to specify multiple id values (n == x or n == y)   |
| nin      | nin: \[x, y …. ] Allows you to specify multiple id values (n != x and n != y) |

### BooleanFilter

| Operator | Description                    |
| -------- | ------------------------------ |
| eq       | =Equals enum value             |
| ne       | <>or != Not Equals enum value |

### ArrayFilter

Array fields support specialized filters for both length and content operations.

| Operator | Description                                                                                         |
| -------- | --------------------------------------------------------------------------------------------------- |
| len      | Filter based on array length with sub-operators: eq, ne, lt, lte, gt, gte                           |
| has      | Filter based on array elements with sub-operators matching the element type                         |
| all      | Filter based on all array elements meeting a condition with sub-operators matching the element type |
| exists   | Check for the presence of elements in an array                                                      |

#### Examples

```graphql {{ title: "Pick data where manufacturers array has less than 3 elements" }}
{
  starships(query: { manufacturers: { len: { lt: 3 } } }) {
    edges {
      node {
        name
      }
    }
  }
}
```

```graphql {{ title: "Pick data where manufacturers array contains an element with 'Corellian'" }}
{
  starships(query: { manufacturers: { has: { contains: "Corellian" } } }) {
    edges {
      node {
        name
      }
    }
  }
}
```

```graphql {{ title: "Pick data where all elements in manufacturers array contain 'Corp'" }}
{
  starships(query: { manufacturers: { all: { contains: "Corp" } } }) {
    edges {
      node {
        name
      }
    }
  }
}
```

```graphql {{ title: "Array field existence check"}}
{
  starships(query: { manufacturers: { exists: true } }) {
    edges {
      node {
        name
        manufacturers
      }
    }
  }
}
```

Note:

* The `has` operator returns `true` if at least one element in the array matches the specified condition.
* The `all` operator returns `true` only if all elements in the array match the specified condition.
* If an array field's value is null, its `len` is considered 0.
* The `exists` operator can be used to check for the presence of elements in an array.

## Advanced Filters

### And, Or and Not Operators

You can combine filter conditions with logical AND, logical OR, and negation (NOT) across all types.

| Operator | Description                       |
| -------- | --------------------------------- |
| and      | and:\[{condition1, condition2 }] |
| or       | or:\[{condition1, condition2 }]  |
| not      | not:\[{condition}]               |

#### Examples

If you want to query data with different conditions, you don't need to use `and` or `or` operators. You may simply add multiple conditions.

```graphql {{ title: "Pick data where carName equals XXX AND carNumber is greater than 10" }}
{
  cars(query: { carName: { eq: "XXX" }, carNumber: { gt: 10 } }) {
    edges {
      node {
        id
      }
    }
  }
}
```

```graphql {{ title: "Pick data where carName equals XXX AND carName equals YYY"}}
{
  cars(query: { and: [{ carName: { eq: "XXX" } }, { carName: { eq: "YYY" } }] }) {
    edges {
      node {
        id
      }
    }
  }
}
```

```graphql {{ title: "Pick data where carName NOT equals XXX"}}
{
  cars(query: { not: [{ carName: { eq: "XXX" } }] }) {
    edges {
      node {
        id
      }
    }
  }
}
```

If the conditions are matched in one of the not query, then matching data will be excluded from the response.

```graphql {{ title: "Exclude data matching the carName or carNumber"}}
query cars {
  cars(query: { not: [{ carName: { eq: "mercedes" } }, { carNumber: { eq: 10 } }] }) {
    edges {
      node {
        id
        carName
        carNumber
      }
    }
  }
}
```

You can also nest the and/or/not queries.

```graphql {{ title: "Pick data where carName NOT equals XXX OR carNumber is greater than 10"}}
{
  cars(query: { or: { not: { carName: { eq: "XXX" } }, carNumber: { gt: 10 } } }) {
    edges {
      node {
        id
      }
    }
  }
}
```

### Null condition

For all types except `Boolean`, it is possible to filter on null values with the `eq` and `ne` operators.

> Note: For array fields and nested fields, you can use the `exists` operator to check for the existence of elements.

#### Examples

```graphql {{ title: "Null condition"}}
{
  cars(query: { carNumber: { eq: null } }) {
    edges {
      node {
        id
      }
    }
  }
}
```

---

---
url: https://docs.tailor.tech/guides/tailordb/hooks.md
---

# Hooks (Calculated Field)

`Hooks` is a feature in Tailor Platform that offers functionality similar to calculated fields in traditional relational databases.\
When a record is created or modified, Hooks automatically update specified field values based on your expressions.

These expressions serve several purposes:

1. Performing calculations:

You can perform calculations using other fields within the same record. For example, a field like `totalPrice` can be configured to automatically calculate the product of `price` and `quantity` fields.

2. Adding user context:

Hooks allow the addition of the current invoker's context to the record. For instance, a field like `createdById` can be populated with the `invoker.id`.\
Additionally, you can utilize invoker attributes, an array of UUIDs configured in the `AttributesFields` in the Auth service. A typical use case for `invoker.attributes` involves validation. Refer to this [example](/guides/tailordb/validations#exampledemonstratinghowtouseuserattributes).

Furthermore, the field updates itself whenever a new record is created or an existing one is updated.\
This ensures data consistency without manual recalculations, similar to calculated fields in a database, and helps you avoid writing complex logic in [Resolver](/guides/resolver).

## Hooks Properties

The following table shows all available hook properties and their scripting language support:

| Property      | Scripting Language                        | Trigger Event   | Description                                                                                                                                           |
| ------------- | ----------------------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `create`      | [JavaScript](/reference/api/js-scripting) | Record creation | Triggered when a new record is created. You can use `_value` to refer to the current field value and `_data` to refer to the entire record            |
| `update`      | [JavaScript](/reference/api/js-scripting) | Record update   | Triggered when the target record is updated. You can use `_value` to refer to the current field value and `_data` to refer to the entire record       |
| `create_expr` | [CEL](/reference/api/cel-scripting)       | Record creation | Triggered when a new record is created. You can use `_value` to refer to the current field value and `_value.abc` to refer to the specific field      |
| `update_expr` | [CEL](/reference/api/cel-scripting)       | Record update   | Triggered when the target record is updated. You can use `_value` to refer to the current field value and `_value.abc` to refer to the specific field |

## Examples

### JavaScript

```js {{ title: "example" }}
hooks = {  // if shopifyID is null, set status to 'awaiting_payment', else set status to the current value
  create = "_data.shopifyID == null ? 'awaiting_payment' : _value"
}
```

#### CEL &#x20;

```js {{ title: "example" }}
hooks = {  // if shopifyID is null, set status to 'awaiting_payment', else set status to the current value
  create_expr = "_value.shopifyID == null ? 'awaiting_payment' : '_value'"
}
```

#### Compute the total price of an item

```typescript {{ title: "order.ts"}}
import { db } from "@tailor-platform/sdk";

export const order = db
  .table("Order", {
    price: db.int().description("Unit price of a certain product"),
    quantity: db.int().description("Order quantity of a certain product"),
    totalPrice: db.int().description("Total price of a certain product"),
  })
  .hooks({
    create: ({ input }) => ({ totalPrice: input.price * input.quantity }),
    update: ({ input, oldRecord }) => ({
      totalPrice: (input.price ?? oldRecord.price) * (input.quantity ?? oldRecord.quantity),
    }),
  });
```

Field-level hooks can't read other fields, so computing `totalPrice` from `price` and `quantity` requires a type-level hook (`db.table().hooks(...)`) instead.

```sh {{ title: "order.tf"}}
  price = {
    type        = "integer"
    description = "Unit price of a certain product"
  }
  quantity = {
    type        = "integer"
    description = "Order quantity of a certain product"
  }
  totalPrice = {
    type        = "integer"
    description = "Total price of a certain product"
    hooks = {
      create = "_data.price * _data.quantity"
      update = "_data.price * _data.quantity"
    }
  }
```

With such hooks in place, the totalPrice field will be computed and stored whenever the order is created or changed.

#### Add user context to the Supplier model

```typescript {{ title: "supplier.ts"}}
import { db } from "@tailor-platform/sdk";

export const supplier = db.table("Supplier", {
  createdById: db
    .uuid()
    .description("User ID of the logged in user")
    .hooks({
      create: ({ invoker }) => invoker?.id ?? "",
    }),
});
```

```sh {{ title: "supplier.tf"}}
  createdById = {
    type        = "uuid"
    description = "User ID of the logged in user"
    hooks = {
      create = "user.id"
    }
  }
```

#### Set a default value to a field

```typescript {{ title: "order.ts"}}
import { db } from "@tailor-platform/sdk";

export const order = db.table("Order", {
  quantity: db
    .int()
    .description("Order quantity of a certain product")
    .hooks({
      create: ({ input }) => input ?? 2,
    }),
});
```

For a plain, unconditional default like this one, prefer `.default(2)` on the field instead — it also makes the field optional in the create input. Use a hook when the default depends on other fields or the invoker (see [Conditional default values](#conditional-default-values) below).

```sh {{ title: "order.tf"}}
  quantity: {
    type        = "integer"
    description = "Order quantity of a certain product"
    hooks = {
      create = "_value != null ? _value : 2"
    }
  }
```

## Evaluation order

### User input

Hooks run after input evaluation, having the consequence that any passed value may be overwritten by a hook's result, depending on the type of the hooks.

#### Example

```typescript {{ title: "order.ts"}}
import { db } from "@tailor-platform/sdk";

export const order = db
  .table("Order", {
    price: db.int().description("Unit price of a certain product"),
    quantity: db.int().description("Order quantity of a certain product"),
    totalPrice: db.int().description("Total price of a certain product"),
  })
  .hooks({
    create: ({ input }) => ({ totalPrice: input.price * input.quantity }),
    update: ({ input, oldRecord }) => ({
      totalPrice: (input.price ?? oldRecord.price) * (input.quantity ?? oldRecord.quantity),
    }),
  });
```

```sh {{ title: "order.tf"}}
  price = {
    type        = "integer"
    description = "Unit price of a certain product"
  }
  quantity = {
    type        = "integer"
    description = "Order quantity of a certain product"
  }
  totalPrice = {
    type        = "integer"
    description = "Total price of a certain product"
    hooks = {
      create = "_data.price * _data.quantity"
      update = "_data.price * _data.quantity"
    }
  }
```

When passing totalPrice = `100`, price = `5`, and quantity = `10` as inputs, `50` is stored on the `totalPrice` field.

### Validate vs Hooks

Validations are run after hooks.

For an Order model, if price \* quantity is less than 100, the record is created and the computed total price is stored.
If the total exceeds 100, validation fails and the record is not created.

```typescript {{ title: "order.ts"}}
import { db } from "@tailor-platform/sdk";

export const order = db
  .table("Order", {
    price: db.int().description("Unit price of a certain product"),
    quantity: db.int().description("Order quantity of a certain product"),
    totalPrice: db
      .int()
      .description("Total price of a certain product")
      .validate(({ value }) =>
        value >= 100 ? "totalPrice value must be less than 100" : undefined,
      ),
  })
  .hooks({
    create: ({ input }) => ({ totalPrice: input.price * input.quantity }),
    update: ({ input, oldRecord }) => ({
      totalPrice: (input.price ?? oldRecord.price) * (input.quantity ?? oldRecord.quantity),
    }),
  });
```

```sh {{ title: "order.tf"}}
  price = {
    type        = "integer"
    description = "Unit price of a certain product"
  }
  quantity = {
    type        = "integer"
    description = "Order quantity of a certain product"
  }
  totalPrice = {
    type        = "integer"
    description = "Total price of a certain product"
    hooks = {
      create = "_data.price * _data.quantity"
      update = "_data.price * _data.quantity"
    }
    validate = [
      {
        expr   = "_value < 100"
        action = "deny"
      }
    ]
  }
```

## Advanced usage

### createdAt, updatedAt field

The datetime each record was created and updated can be stored as follows

```typescript {{ title: "order.ts"}}
import { db } from "@tailor-platform/sdk";

export const order = db
  .table("Order", {
    createdAt: db.datetime().description("The time when this record is created"),
    updatedAt: db.datetime().description("The time when this record is updated"),
  })
  .hooks({
    // `now` is the same Date instance across every hook in the same operation.
    create: ({ now }) => ({ createdAt: now, updatedAt: now }),
    update: ({ now }) => ({ updatedAt: now }),
  });
```

Or use the built-in timestamps helper:

```typescript {{ title: "order.ts"}}
import { db } from "@tailor-platform/sdk";

export const order = db.table("Order", {
  ...db.fields.timestamps(),
});
```

`db.fields.timestamps()` adds non-null `createdAt` and `updatedAt` fields with this same behavior built in — both are populated on create, and `updatedAt` is refreshed on every update. Provided values are preserved (useful for seeding historical timestamps).

```sh {{ title: "order.tf"}}
  createdAt = {
    type        = "datetime"
    description = "The time when this record is created"
    hooks = {
      create = "(new Date()).toISOString()"
    }
  }
  updatedAt = {
    type        = "datetime"
    description = "The time when this record is updated"
    hooks = {
      update = "(new Date()).toISOString()"
    }
  }
```

In this example, the `createdAt` field is set only on create, while `updatedAt` is set on both create and update.

When the record is created, the current datetime value is stored in both the `createdAt` and `updatedAt` fields.

When the record is updated, the value in the `createdAt` field remains unchanged, while the `updatedAt` field is updated with the current datetime.

### Conditional default values

Hooks can be used to set the default value of a field, especially when it depends on dynamic conditions.

In this example, the default value of the field `price` is determined by the value of the `type` field.

```typescript {{ title: "order.ts"}}
import { db } from "@tailor-platform/sdk";

export const order = db
  .table("Order", {
    type: db
      .enum([
        { value: "ITEMA", description: "Item A" },
        { value: "ITEMB", description: "Item B" },
      ])
      .description("Item category"),
    price: db.int().description("Unit price of a certain product"),
  })
  .hooks({
    create: ({ input }) => ({ price: input.type === "ITEMA" ? 100 : null }),
  });
```

This needs a type-level hook because it reads the `type` field to decide `price` — field-level hooks can't see other fields.

```sh {{ title: "order.tf"}}
  type = {
    type        = "enum"
    description = "Item category"
    allowed_values : [
      {
        value       = "ITEMA"
        description = "Item A"
      },
      {
        value       = "ITEMB"
        description = "Item B"
      }
    ]
  }
  price = {
    type        = "integer"
    description = "Unit price of a certain product"
    hooks = {
      create = "_data.type == 'ITEMA' ? 100 : null"
    }
  }
```

In this example, the `price` field is evaluated only on create events, and if the type is `ITEMA`, then the value `100` is applied to the `price` field.

However, if the type is `ITEMB`, no value is applied to the `price` field.

Additionally, on the update event, regardless of whether the type is `ITEMA` or `ITEMB`, no value is applied.

---

---
url: https://docs.tailor.tech/guides/tailordb/indexes.md
---

# Indexes

The `indexes` field allows you to define multiple indexes for a given type.
By adding this field, you can enable the use of several indexes as well as set uniqueness constraints across multiple fields.
This functionality is especially useful for applications that require efficient data management through multiple indexes.

For instance, consider the definition of the `titleAndSku` index as follows:

```typescript {{ title: 'tailordb/product.ts' }}
db.table("Product", {
  title: db.string(),
  sku: db.string(),
}).indexes({
  fields: ["title", "sku"],
  name: "titleAndSku",
  unique: true,
});
```

Within the `.indexes()` configuration, you can specify the fields to be included in the index using `fields`, and provide a `name` for the index.
In the example provided, we've named the index `titleAndSku`, but this name is flexible and can be customized as needed.

Furthermore, the `unique` attribute specifies the constraint for multiple fields to be unique.
Here, it signifies that each `title` and `sku` pairing must be distinct within the Product type, thereby preventing duplicate entries in the dataset.

For instance, consider the definition of the `title_and_sku` index as follows:

```sh {{ title: 'tailordb_product.tf' }}
resource "tailor_tailordb_type" "product" {
	workspace_id = tailor_workspace.ims.id
	namespace    = tailor_tailordb.ims.namespace
	name         = "Product"
	description  = "Product data schema"

	indexes = {
		title_and_sku = {
			field_names = ["title", "sku"]
			unique = true
		}
    }
}
```

Within the `indexes` configuration, you can specify the name of a composite index key using `field_names`, which identifies the fields to be included in the index.
In the example provided, we've named the index `title_and_sku`, but this name is flexible and can be customized as needed.

Furthermore, the `unique` attribute specifies the constraint for multiple fields to be unique.
Here, it signifies that each `title` and `sku` pairing must be distinct within the Product type, thereby preventing duplicate entries in the dataset.

For instance, consider the definition of the `titleAndSku` index as follows:

Within the `Indexes` configuration, you can specify the name of a composite index key using `FieldNames`, which identifies the fields to be included in the index.
In the example provided, we've named the index `titleAndSku`, but this name is flexible and can be customized as needed.

Furthermore, the `Unique` attribute specifies the constraint for multiple fields to be unique.
Here, it signifies that each `title` and `sku` pairing must be distinct within the Product type, thereby preventing duplicate entries in the dataset.

**Caveat**:
Enum type is not supported for the multiple indexes field.

---

---
url: https://docs.tailor.tech/guides/tailordb/permission.md
---

# Permission

TailorDB's permission system provides enhanced flexibility and performance for controlling access to your data. It introduces two key resources that work together to provide comprehensive access control:

* **`Permission`** - Record-level access control
* **`GQLPermission`** - GraphQL operation-level access control

The new permission system is recommended for all new applications. It addresses several limitations of the legacy permission system (deprecated) including better performance, support for non-UUID fields, and the ability to reference record values directly in permission rules.

## Permission (Record-Level Control)

`Permission` is defined within the Type resource and controls which users can operate on which records.

### Basic Structure

```typescript
db.table("Example", {
  // field definitions
}).permission({
  create: [/* policies */],
  read: [/* policies */],
  update: [/* policies */],
  delete: [/* policies */],
});
```

### Permission Types

Each permission type has different semantics:

#### Read Permission

Read Permission act as automatic filters. Only records that match at least one policy can be retrieved.

```typescript
db.table("Example", {
  userId: db.uuid(),
}).permission({
  read: [[{ record: "userId" }, "=", { user: "id" }]],
});
```

#### Create/Update/Delete Permissions

These Permissions act as validation rules. If a record doesn't match any policy, the operation is prohibited and returns a permission denied error.

```typescript
db.table("Example", {
  // fields
}).permission({
  create: [[{ user: "role" }, "=", "ADMIN"]],
});
```

### Policy Evaluation

Multiple policies can be defined for each permission type. The evaluation follows these rules:

* **Explicit allow required**: If no policy matches, access is denied by default (implicit deny)
* **Explicit deny takes precedence**: A policy with `permit = "deny"` always overrides allow policies
* **All conditions must match**: Within a policy, all conditions must be satisfied for the policy to match

### Operands

The following operands can be used in conditions:

#### `record`

Uses the value of a specified field from the record. Cannot be used in Update Permission (use `old_record` or `new_record` instead).

Supported field types: `String`, `UUID`, `Enum`, `Boolean`, and their array forms.

```typescript
// Check if the record's status is "TODO"
[{ record: "status" }, "=", "TODO"];
```

#### `old_record` / `new_record`

Used in Update Permission to reference the existing or updated record values. Cannot be used in Create/Read/Delete Permissions.

The supported field types are the same as for `record`.

```typescript
// Check if the old record's assigneeId matches the user ID
[{ oldRecord: "assigneeId" }, "=", { user: "id" }];
```

#### `user`

Uses the value of a specified field from the user's AttributeMap (defined in the Auth service).

```typescript
// Check if the user's role is "ADMIN"
[{ user: "role" }, "=", "ADMIN"];
```

#### `value`

Uses a specified value directly. Supports `String`, `Boolean`, and their array types.

```typescript
// Check if the record's status is in a specific set of values
[{ record: "status" }, "in", ["TODO", "IN_PROGRESS"]];
```

### Operators

The following operators are supported:

#### `eq` / `ne`

Equality and inequality comparison.

```typescript
// Check if the record's status is "TODO"
[{ record: "status" }, "=", "TODO"][
  // Check if the user's role is not "ADMIN"
  ({ user: "role" }, "!=", "ADMIN")
];
```

#### `in` / `nin`

Array membership and non-membership.

```typescript
// Check if the record's status is in a set of values
[{ record: "status" }, "in", ["TODO", "IN_PROGRESS"]][
  // Check if the user's role is not in a set of values
  ({ user: "role" }, "nin", ["GUEST", "USER"])
];
```

#### `hasAny` / `nhasAny`

Array overlap and non-overlap. Checks whether two string arrays share any common elements. Both operands must be string arrays.

* `hasAny` — true if the two arrays have at least one element in common
* `nhasAny` — true if the two arrays have no elements in common

Supported array field types: `String`, `UUID`, `Enum`.

```typescript
// Check if the record's roles share any values with the given list
[{ record: "roles" }, "hasAny", ["ADMIN", "EDITOR"]][
  // Check if the user's roles have no overlap with restricted roles
  ({ user: "roles" }, "nhasAny", ["BLOCKED", "SUSPENDED"])
];
```

You can also compare a user attribute array against a record field array:

```typescript
// Allow access if the user's roles overlap with the record's allowedRoles
[{ user: "roles" }, "hasAny", { record: "allowedRoles" }];
```

### Complete Example

```typescript
const TaskStatus = db.enum("TaskStatus", [
  { value: "TODO", description: "Task is pending" },
  { value: "IN_PROGRESS", description: "Task is currently being worked on" },
  { value: "DONE", description: "Task has been completed" },
]);

db.table("Task", {
  title: db.string({ required: true, description: "Task title" }),
  status: TaskStatus({
    description: "Task status",
    hooks: { create: "'TODO'" },
  }),
  assigneeId: db.uuid({
    description: "ID of the user assigned to this task",
    hooks: { create: "user.id" },
  }),
}).permission({
  create: [
    // Administrators can create any task
    [{ user: "role" }, "=", "ADMIN"],
    // Users can create tasks assigned to themselves with TODO status
    [
      [{ record: "assigneeId" }, "=", { user: "id" }],
      [{ record: "status" }, "=", "TODO"],
    ],
  ],
  read: [
    // Administrators can read all tasks
    [{ user: "role" }, "=", "ADMIN"],
    // Users can read tasks assigned to them
    [{ record: "assigneeId" }, "=", { user: "id" }],
  ],
  update: [
    // Administrators can update any task
    [{ user: "role" }, "=", "ADMIN"],
    // Users can update tasks assigned to them
    [
      [{ oldRecord: "assigneeId" }, "=", { user: "id" }],
      [{ newRecord: "assigneeId" }, "=", { user: "id" }],
    ],
  ],
  delete: [
    // Administrators can delete any task
    [{ user: "role" }, "=", "ADMIN"],
  ],
});
```

## GQLPermission (GraphQL-Level Control)

`GQLPermission` is defined as a separate resource and controls which users can execute specific GraphQL operations. This setting does not affect SQL execution via the Function service.

### Basic Structure

```typescript
db.gqlPermission("Example", {
  policies: [
    {
      conditions: [/* conditions */],
      actions: [/* actions */],
      permit: "allow", // or "deny"
      description: "Policy description",
    },
  ],
});
```

### Conditions

The method for defining Conditions is basically the same as `Permission`. Just note that `record` / `old_record` / `new_record` operands are not available here.

### Actions

Each GraphQL operation is categorized into the following actions:

| Action        | GraphQL operation                                  |
| ------------- | -------------------------------------------------- |
| `all`         | All GraphQL operations for the type                |
| `create`      | `create<Type>` mutation                            |
| `read`        | `get<Type>`, `get<Type>By`, `list<Type>s` queries  |
| `update`      | `update<Type>` mutation                            |
| `delete`      | `delete<Type>` mutation                            |
| `aggregate`   | `aggregate<Type>` query                            |
| `bulk_upsert` | `bulkUpsert<Type>`, `bulkUpsert<Type>By` mutations |

### Complete Example

```typescript
db.gqlPermission("Task", {
  policies: [
    {
      conditions: [[{ user: "role" }, "=", "ADMIN"]],
      actions: ["all"],
      permit: "allow",
      description: "Administrators have full access to all GraphQL operations",
    },
    {
      conditions: [[{ user: "loggedIn" }, "=", true]],
      actions: ["create", "read", "update"],
      permit: "allow",
      description: "Authenticated users can create, read, and update tasks",
    },
  ],
});
```

## Auth Integration

User attributes referenced in permissions are defined through the Auth service configuration.

### User Profile Configuration

```typescript
auth.idp.tailordb({
  type: "User",
  usernameField: "email",
  attributeMap: {
    // Reference the value of the role field as "role" using the "user" operand
    role: "role",
  },
});
```

### Machine User Configuration

```typescript
auth.machineUser("admin", {
  // Set the role attribute to "ADMIN"
  role: "ADMIN",
});
```

### Built-in User Attributes

In addition to custom attributes, two built-in fields are always available:

#### `_id`

The user's unique identifier.

```typescript
// Check if the user ID matches the record's assigneeId
[{ user: "id" }, "=", { record: "assigneeId" }];
```

#### `_loggedIn`

Boolean indicating whether the user is authenticated.

```typescript
// Check if the user is logged in
[{ user: "loggedIn" }, "=", true];
```

## SQL Operation Behavior

Unlike `GQLPermission`, `Permission` is enforced at the SQL level as well.

For detailed information about how the settings affect SQL operations when accessing TailorDB via the Function service, see [Permission Enforcement](/guides/function/accessing-tailordb#permission-enforcement).

## GraphQL Operation Behavior

When accessing TailorDB via GraphQL, `Permission` required for each operation is determined based on the corresponding equivalent SQL:

### Create Operations

```graphql
mutation {
  createTask(input: { title: "New task" }) {
    id
  }
}
```

**SQL Equivalent**: `INSERT INTO "Task" ("title") VALUES ('New task') RETURNING "id"`

**Required Permissions**:

* Permission: Create, Read (for returning created record)
* GQLPermission: Create

### Read Operations

```graphql
query {
  tasks(query: { status: { eq: "TODO" } }, first: 10) {
    edges {
      node {
        id
        title
      }
    }
  }
}
```

**SQL Equivalent**: `SELECT "id", "title" FROM "Task" WHERE "status" = 'TODO' LIMIT 10`

**Required Permissions**:

* Permission: Read
* GQLPermission: Read

### Update Operations

```graphql
mutation {
  updateTask(
    id: "<uuid>"
    input: { status: "DONE" }
    condition: { status: { eq: "IN_PROGRESS" } }
  ) {
    id
  }
}
```

**SQL Equivalent**: `UPDATE "Task" SET "status" = 'DONE' WHERE "id" = 'uuid' AND "status" = 'IN_PROGRESS' RETURNING "id"`

**Required Permissions**:

* Permission: Update, Read (for candidate record retrieval and returning updated record)
* GQLPermission: Update

### Delete Operations

```graphql
mutation {
  deleteTask(id: "<uuid>")
}
```

**SQL Equivalent**: `DELETE FROM "Task" WHERE "id" = 'uuid'`

**Required Permissions**:

* Permission: Delete, Read (for candidate record retrieval)
* GQLPermission: Delete

### Bulk Upsert Operations

```graphql
mutation {
  bulkUpsertTasksBy(
    field: title
    input: [{ title: "Task 1", status: "TODO" }, { title: "Task 2", status: "DONE" }]
  )
}
```

**SQL Equivalent**: `INSERT INTO "Task" ("title", "status") VALUES ('Task 1', 'TODO'), ('Task 2', 'DONE') ON CONFLICT ("title") DO UPDATE SET "status" = EXCLUDED."status"`

**Required Permissions**:

* Permission: Create (INSERT case), Update + Read (UPDATE case)
* GQLPermission: BulkUpsert

### Aggregate Operations

```graphql
query {
  aggregateTasks {
    groupBy {
      status
    }
    count
  }
}
```

**SQL Equivalent**: `SELECT "status", COUNT(*) FROM "Task" GROUP BY "status"`

**Required Permissions**:

* Permission: Read
* GQLPermission: Aggregate

## Compatibility

* When both `Permission` and `RecordPermission` are defined, `Permission` takes precedence
* When both `GQLPermission` and `TypePermission` are defined, `GQLPermission` takes precedence
* This ensures backward compatibility while enabling gradual migration

---

---
url: https://docs.tailor.tech/guides/tailordb/relationships.md
---

# Relationship Field

TailorDB allows you to define relationships between types in your GraphQL schema through the `Relationships` field.
This enables you to express type associations directly in your schema, creating a seamless experience for querying related data through natural expressions such as foreign key references and list retrievals.
By using relationship fields, you can build more intuitive and maintainable GraphQL schemas.

## Configuration

The following table describes the available configuration options:

The SDK uses `db.uuid().relation()` to define relationships with automatic index and foreign key constraints:

| Option        | Description                                                                 | Required |
| ------------- | --------------------------------------------------------------------------- | -------- |
| `type`        | Relationship type: `"1-1"` for one-to-one, `"n-1"` for many-to-one          | ✅       |
| `toward.type` | Referenced Type                                                             | ✅       |
| `toward.key`  | Referenced field name (defaults to `"id"`)                                  | ⬜       |
| `toward.as`   | Custom name for accessing the related type from this type                   | ⬜       |
| `backward`    | Custom name for accessing this type from the related type (for 1:N queries) | ⬜       |

| Attribute     | Description                                                    | Required |
| ------------- | -------------------------------------------------------------- | -------- |
| `src_field`   | Source field name (field in the current Type)                  | ✅       |
| `ref_type`    | Referenced Type name                                           | ✅       |
| `ref_field`   | Referenced field name                                          | ✅       |
| `array`       | Set to `true` for 1:N relationships (multiple related records) | ⬜       |
| `description` | Field description                                              | ⬜       |

| Attribute     | Description                                                    | Required |
| ------------- | -------------------------------------------------------------- | -------- |
| `SrcField`    | Source field name (field in the current Type)                  | ✅       |
| `RefType`     | Referenced Type name                                           | ✅       |
| `RefField`    | Referenced field name                                          | ✅       |
| `Array`       | Set to `true` for 1:N relationships (multiple related records) | ⬜       |
| `Description` | Field description                                              | ⬜       |

## Constraints

When implementing relationships, ensure:

* The field specified in `ref_field` must have an `index` set.
* For 1:1 relationships, the referenced field must have `unique` specified.
* For 1:N relationships, the referenced field must not have `unique` specified.

## Examples

### 1:1 Relationship

In a 1:1 relationship, each record in Type A can be associated with at most one record in Type B.

```typescript
import { db } from "@tailor-platform/sdk";

export const species = db.table("Species", "Species data schema", {
  name: db.string().description("Name of the species").required(),
  ...db.fields.timestamps(),
});
export type species = typeof species;

export const character = db.table("Character", "Character data schema", {
  name: db.string().description("Name of the character").required(),
  speciesId: db
    .uuid()
    .description("Species ID of the character")
    .relation({
      type: "1-1",
      toward: { type: species, as: "species" },
    }),
  ...db.fields.timestamps(),
});
export type character = typeof character;
```

```sh
  resource "tailor_tailordb_type" "character" {
    workspace_id = tailor_workspace.example.id
    namespace    = tailor_tailordb.example.namespace
    name         = "Character"
    description  = "Character data schema"

    fields = {
      name = {
        type        = "string"
        description = "Name of the character"
        required    = true
      }
      speciesID = {
        type           = "uuid"
        description    = "Species ID of the character"
        index          = true
        foreign_key    = {
          type = "Species"
        }
      }
    }

    relationships = {
      species = {
        ref_type = "Species"
        ref_field = "id"
        src_field = "speciesID"
        description = "Species of the character"
      }
    }
  }
```

This relationship can be queried as follows:

```graphql
query character {
  character(id: "4c2429c8-b923-490f-a738-04e671896e9d") {
    name
    speciesID
    species {
      id
      name
    }
  }
}
```

### 1:N Relationship

In a 1:N relationship, each record in Type A can be associated with multiple records in Type B.

```typescript
import { db } from "@tailor-platform/sdk";

export const species = db.table("Species", "Species data schema", {
  name: db.string().description("Name of the species").required(),
  ...db.fields.timestamps(),
});
export type species = typeof species;

export const character = db.table("Character", "Character data schema", {
  name: db.string().description("Name of the character").required(),
  speciesId: db
    .uuid()
    .description("Species ID of the character")
    .relation({
      type: "n-1",
      toward: { type: species },
      backward: "characters", // Access characters from Species
    }),
  ...db.fields.timestamps(),
});
export type character = typeof character;
```

With the `backward` option, you can query characters from the Species type. The SDK automatically handles the 1:N relationship configuration.

```sh
  resource "tailor_tailordb_type" "species" {
    workspace_id = tailor_workspace.example.id
    namespace    = tailor_tailordb.example.namespace
    name         = "Species"
    description  = "Species data schema"

    fields = {
      name = {
        type        = "string"
        description = "Name of the species"
        required    = true
      }
    }

    relationships = {
      characters = {
        ref_type = "Character"
        ref_field = "speciesID"
        src_field = "id"
        array = true
        description = "Characters of the species"
      }
    }
  }
```

This relationship can be queried as follows:

```graphql
query species {
  species(id: "01219d7c-b8e3-44c0-845e-4871e8f02366") {
    name
    characters {
      edges {
        node {
          name
        }
      }
    }
  }
}
```

## Advanced Usage

### Nested Relationship Queries

You can query deeply nested relationships by chaining relationship fields:

```graphql
query getSpeciesWithCharactersAndItems {
  species(id: "01219d7c-b8e3-44c0-845e-4871e8f02366") {
    name
    characters {
      edges {
        node {
          name
          items {
            edges {
              node {
                name
                type
              }
            }
          }
        }
      }
    }
  }
}
```

&#x20;There are limitations to nesting depth, which may impact performance.

### Pagination and Filtering

When querying relationships that return multiple records, you can use pagination and filtering options:

```graphql
query getSpeciesWithFilteredCharacters {
  species(id: "01219d7c-b8e3-44c0-845e-4871e8f02366") {
    name
    characters(first: 5, filter: { name: { contains: "A" } }) {
      edges {
        node {
          name
        }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}
```

This query retrieves the first 5 characters whose names contain the letter "A" for the specified species, along with pagination information.

---

---
url: https://docs.tailor.tech/guides/tailordb/validations.md
---

# Data validations

Data validation allows you to define rules for your fields, including acceptable value ranges.

## Validation Properties

Use the `.validate()` method to add validation rules to a field. The method accepts validation rules as arguments, where each rule can be either:

* A validation function that returns `true` for valid values
* A tuple of `[validationFunction, errorMessage]` for custom error messages

```typescript
db.string().validate(
  ({ value }) => (value.includes("@") ? undefined : "Must contain @"),
  ({ value }) => (value.length > 5 ? undefined : "Must be longer than 5 characters"),
);
```

The validation function receives `{ value }` — the field value after hooks have run — and returns an error message string to fail, or `void`/`undefined` to pass. Field-level validators can't access other fields; use a type-level validator (`db.table().validate()`) for cross-field checks.

**Notes:**

* The validation rules are evaluated in order
* Validation cannot access fields provided through relation associations

If `validate` field is set in schema, validation rules will be applied to the field value.
The data type of the field is an array of maps, with `expr` and `action` defined.
The `action` will be evaluated when the `expr` returns true.

| Property        | Type   | Scripting Language                        | Description                                                        |
| --------------- | ------ | ----------------------------------------- | ------------------------------------------------------------------ |
| `script`        | string | [JavaScript](/reference/api/js-scripting) | The JavaScript code to evaluate for validation                     |
| `action`        | string | -                                         | `allow` or `deny`                                                  |
| `error_message` | string | -                                         | A string of error message to be returned when the validation fails |

**Notes:**

* The validation rules are evaluated in descending order
* `expr` cannot access the fields provided through `sourceId` association

If `Validate` field is set in schema, validation rules will be applied to the field value.
The data type of the field is an array of maps, with `Expr` and `Action` defined.
The `Action` will be evaluated when the `Expr` returns true.

| Property       | Type   | Scripting Language                        | Description                                                        |
| -------------- | ------ | ----------------------------------------- | ------------------------------------------------------------------ |
| `Script.Expr`  | string | [JavaScript](/reference/api/js-scripting) | An expression in JavaScript                                        |
| `Action`       | string | -                                         | `tailordb.#Permit.Allow` or `tailordb.#Permit.Deny`                |
| `ErrorMessage` | string | -                                         | A string of error message to be returned when the validation fails |

**Notes:**

* The validation rules are evaluated in descending order
* `Expr` cannot access the fields provided through `SourceId` association

## Examples

```typescript
// reportNumber value must be less than 100 or over 103
reportNumber: db.int().validate(({ value }) =>
  value < 100 || value > 103 ? undefined : "reportNumber value must be less than 100 or over 103",
);
```

```typescript
// Description length should be less than 40 characters
description: db.string()
  .description("Description of the product.")
  .validate(({ value }) =>
    value.length < 40 ? undefined : "Description length should be less than 40 characters.",
  );
```

Field-level validators only see `{ value }`, so a check like "the invoker must be logged in" — which depends on the invoker, not the field's own value — needs a type-level validator instead:

```typescript
// User must be logged in to create an item
export const item = db
  .table("Item", {
    itemStatus: db.string(),
    // ...other fields
  })
  .validate(({ invoker }, issues) => {
    if (!invoker) {
      issues("itemStatus", "You must be logged in to create an item");
    }
  });
```

```javascript
  reportNumber  = {
    type          = "integer"
    validate      = [
      // reportNumber value must be less than 100 or over 103
      {
        script        = "((value, data) => { return value >=100 && value <=103})(_value, _data)"
        action        = "deny"
        error_message = "reportNumber value must be less than 100 or over 103"
      }
    ]
  }
```

```javascript
description = {
  type        = "string"
  description = "Description of the product."
  validate    = [{
    script        = "((value, data) => { return !(value.length < 40)})(_value, _data)"
    action        = "deny"
    error_message = "Description length should be less than 40 characters."
  }]
}
```

```javascript
itemStatus = {
  type     = "string"
  validate = [{
    script        = "((value, data) => { return Object.keys(user).length === 0 })(_value, _data)"
    action        = "deny"
    error_message =  "You must be logged in to create an item"
  }]
}
```

```javascript
  reportNumber: {
    Type:        tailordb.#TypeInt
    Validate: [
      // reportNumber value must be less than 100 or over 103
      {
        Script: common.#Script & {
          Expr: """
            ((value, data) => {
              return value >=100 && value <=103
            })(_value, _data)
          """
        }
        Action: tailordb.#Permit.Deny
        ErrorMessage: "reportNumber value must be less than 100 or over 103"
      }
    ]
  }
```

```javascript
description: {
  Type:        tailordb.#TypeString
  Description: "Description of the product."
  Validate: [{
    Script: common.#Script & {
      Expr: """
        ((value, data) => {
          return !(value.length < 40)
        })(_value, _data)
      """
    }
    Action: tailordb.#Permit.Deny
    ErrorMessage: "Description length should be less than 40 characters."
  }]
}
```

```javascript
itemStatus: {
  Type: tailordb.#TypeString
  Validate: [{
    Script: common.#Script & {
      Expr: """
        ((value, data) => {
          return Object.keys(user).length === 0
        })(_value, _data)
        """
      }
    Action:       tailordb.#Permit.Deny
    ErrorMessage: "You must be logged in to create an item"
  }]
}
```

### Example demonstrating how to use user attributes

```typescript
export const item = db
  .table("Item", {
    itemCode: db.string(),
    // ...other fields
  })
  .validate(({ invoker }, issues) => {
    if (!invoker?.attributeList.includes("{ADMIN_ID}")) {
      issues("itemCode", "To create an item, you must be the Admin");
    }
  });
```

```javascript
  itemCode = {
    type     = "string"
    validate = [{
      script        = "((value, data) => { return !user.attributes.includes(\"{ADMIN_ID}\") })(_value, _data)"
      action        = "deny"
      error_message =  "To create an item, you must be the Admin"
    }]
  }
```

```javascript
  itemCode: {
    Type: tailordb.#TypeString
    Validate: [
      {
        Script: common.#Script & {
          Expr: """
            ((value, data) => {
              return !user.attributes.includes(\"{ADMIN_ID}\")
            })(_value, _data)
          """
        }
        Action:       tailordb.#Permit.Deny
        ErrorMessage: "To create an item, you must be the Admin"
      }
    ]
  }
```

## Accessible variables in expressions

You can use `_value` to refer to the current field value and `_data` to refer to the entire record.

| Variable                                    | Description                                                                                                                                                                                                                |
| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `_value`                                    | This accesses its own field value.                                                                                                                                                                                         |
| `_data.{other_field_name}`                  | Other fields can be accessed using the field name. ex. `foo == 2` accesses `foo` field                                                                                                                                     |
| `_data.{array_name}[{index}]`               | This accesses the array value. ex. `arr[0]` accesses the first value of `arr`                                                                                                                                              |
| `_data.{associative_array_name}.{key_name}` | This accesses associative array value. ex. `dict.nestedValue` accesses the `dict` associative array's `nestedValue` key value                                                                                              |
| `user`                                      | This accesses the user context. ex. `user.id` accesses the logged in user id and `user.attributes` acessess user's attributes which is an array of UUIDs that are configured in the `AttributesFields` in the Auth service |

---

---
url: https://docs.tailor.tech/guides/tailordb/versioning.md
---

# Versioning with History Tables

Some applications require preserving previous versions of data when updates or changes occur.
Using [TailorDB CDC](/guides/tailordb/advanced-settings/tailordb-cdc), you can capture and log data modifications in real-time, storing prior record versions in a dedicated history table.
This approach preserves historical data and enables change monitoring and analysis over time.

## How to enable Data Versioning

1. Create a history table
2. Enable `publishEvents` feature
3. Add an event based trigger

## Example

### 1. Create a history table

Let's create a history table for the `StockSummary` table to log its data changes.

```typescript
db.table("StockSummaryHistory", {
  variantID: db.uuid({ required: true, description: "Variant ID" }),
  variant: db.link("ProductVariant", "variantID"),
  onHoldQuantity: db.float({ required: true, description: "onHoldQuantity" }),
  availableQuantity: db.float({
    required: true,
    description: "availableQuantity",
  }),
  inStockQuantity: db.float({
    description: "DO NOT UPDATE FROM THE FRONT END. The quantity of the product in stock.",
    hooks: {
      create: "decimal(_value.onHoldQuantity) + decimal(_value.availableQuantity)",
      update: "decimal(_value.onHoldQuantity) + decimal(_value.availableQuantity)",
    },
  }),
  totalCost: db.float({ required: true, description: "totalCost" }),
  averageCost: db.float({
    description: "averageCost",
    hooks: {
      create: `(decimal(_value.onHoldQuantity) + decimal(_value.availableQuantity)) != decimal(0.0) ?
          decimal(_value.totalCost) / (decimal(_value.onHoldQuantity) + decimal(_value.availableQuantity)) :
          decimal(0.0)`,
      update: `(decimal(_value.onHoldQuantity) + decimal(_value.availableQuantity)) != decimal(0.0) ?
          decimal(_value.totalCost) / (decimal(_value.onHoldQuantity) + decimal(_value.availableQuantity)) :
          decimal(0.0)`,
    },
  }),
});
```

### 2. Enable `publishEvents` feature

By enabling `publishEvents` in the `StockSummary` features, you can create an event-based trigger that executes on every `StockSummary` record update.

```typescript
db.table("StockSummary", {
  // fields...
}).features({
  publishEvents: true,
});
```

### 3. Add an event based trigger

The `stockSummaryHistoryWithEvent` trigger executes on each `StockSummary` record update.
It logs the old record by creating an entry in the history table.

```typescript
executor
  .event("tailordb.type_record.updated")
  .condition(`args.namespaceName == "my-tailordb" && args.typeName == "StockSummary"`)
  .graphql({
    query: `
        mutation ($input: StockSummaryHistoryCreateInput!) {
          createStockSummaryHistory(input: $input) {
            id
          }
        }
      `,
    variables: `({
        "input": {
          "variantID": args.oldRecord.variantID,
          "onHoldQuantity": args.oldRecord.onHoldQuantity,
          "availableQuantity": args.oldRecord.availableQuantity,
          "totalCost": args.oldRecord.totalCost
        }
      })`,
  });
```

Refer to the [Event based trigger](/tutorials/setup-executor/event-based-trigger) tutorial for detailed steps on setting up an event-based trigger.
Once the trigger is configured, proceed with the following steps to confirm it is working correctly.

1. Create a record in `StockSummary` table.

```graphql {{title: 'GraphQL'}}
mutation {
  createStockSummary(
    input: {
      variantID: "fc9349f5-2398-5aa6-a6a7-478c8db009ec"
      onHoldQuantity: 20
      availableQuantity: 20
      totalCost: 800
    }
  ) {
    id
  }
}
```

2. Update the record in `StockSummary` table.

```graphql {{title: 'GraphQL'}}
mutation {
  updateStockSummary(id: "f701637c-12b1-4dab-ab45-3e952d8ff0b6", input: { availableQuantity: 60 }) {
    id
  }
}
```

Execute the following query to view the update history of the record in the history table.

```graphql {{title: 'GraphQL'}}
{
  stockSummaryHistories(query: { variantID: { eq: "fc9349f5-2398-5aa6-a6a7-478c8db009ec" } }) {
    edges {
      node {
        id
        variantID
        availableQuantity
      }
    }
  }
}
```

```graphql {{title: 'Result'}}
{
  "data": {
    "stockSummaryHistories": {
      "edges": [
        {
          "node": {
          	"id": "323c9cff-a75f-45a5-aea5-33a367b4e0ce",
          	"variantID": "fc9349f5-2398-5aa6-a6a7-478c8db009ec",
         	"availableQuantity": 20
          }
        }
      ]
    }
  }
}
```

---

---
url: https://docs.tailor.tech/guides/tailordb/advanced-settings/overview.md
---

# Advanced Settings

Enabling extra features in `settings` field allows you to generate additional GraphQL queries.
These features include:

* [Aggregating values](aggregation)
* [Bulk upsert](bulk-upsert)
* [Plural form for uncountable nouns](uncountable-nouns)
* [TailorDB Change Data Capture(CDC)](tailordb-cdc) - Publish record events for database triggers

Below is a table listing all the available `settings`, with each field and its corresponding type.

| Field Name            | Type                                                                                                          |
| --------------------- | ------------------------------------------------------------------------------------------------------------- |
| Aggregation           | `bool`                                                                                                        |
| BulkUpsert            | `bool`                                                                                                        |
| Draft                 | `bool`                                                                                                        |
| DefaultQueryLimitSize | `int`: Default number of records returned by a query is 100.                                                  |
| MaxBulkUpsertSize     | `int`: Maximum number of records that can be processed in a single bulk upsert operation is limited to 1,000. |
| PluralForm            | `bool`                                                                                                        |
| PublishRecordEvents   | `bool`                                                                                                        |

Also, we can utilize the following advanced GraphQL schema configuration to optimize GraphQL queries.

* Directives
* Extends

## Directives

Directive is a GraphQL concept, that provides a way to add additional instructions to GraphQL queries without having to modify the schema.
This allows developers to use GraphQL to access the same data in different ways without having to change the underlying data structure.
The `Directives` field holds a map structure data, where the key is directive name and the value is a map of arguments defined in the `Args` key.

For example, we can define the directive of `@key(fields: "id")` as the following:

```typescript
import { db } from "@tailor-platform/sdk";

export const myType = db
  .table("MyType", "My type with directives", {
    // ...fields
  })
  .directives([
    {
      name: "key",
      args: [{ name: "fields", value: "id" }],
    },
  ]);
```

```sh
  // enable directives
  directives = [
    {
      name = "key"
      args = [
        {
          name  = "fields"
          value = "id"
        }
      ]
    }
  ]
```

See [GraphQL Directives](https://graphql.org/learn/queries/#directives) for more details.

## Extends

The `Extends` option enables the extension of the types defined in other sub-graphs, like StateFlow.
With this option enabled, CRUD GraphQL queries become available in TailorDB.
To make this work, the directive of `@key(fields: "id")` must be defined.

For example, if we want to extend State resource in StateFlow, we can define the `extend` and directives in the schema as follows:
This will generate `createExtendState`, `updateExtendState`, `deleteExtendState`, and `changeExtendState` API.

```typescript
import { db } from "@tailor-platform/sdk";

// Example of extending State type
export const state = db
  .table("State", "State type with extends", {
    // ...fields
  })
  .extends(true)
  .directives([
    {
      name: "key",
      args: [{ name: "fields", value: "id" }],
    },
  ]);
```

```sh
  // example of state.tf enabling extends
  resource "tailor_tailordb_type" "state" {
    workspace_id = tailor_workspace.ims.id
    namespace    = tailor_tailordb.ims.namespace
    name         = "State"

    // Set true for extends setting
    extends = true

    // You must define @key(fields: "id") directive as follows
    directives = [{
      name = "key"
      args = [
        {
          name  = "fields"
          value = "id"
        }
      ]
    }]
  }
```

---

---
url: https://docs.tailor.tech/guides/tailordb/advanced-settings/aggregation.md
---

# Aggregation

Aggregation queries enable the summarization and analysis of large datasets.\
Through leveraging these aggregation queries, you can quickly aggregate your records to identify trends, relationships, and anomalies, which provide insights for your decision-making.

You can enable the `Aggregation` setting for your type, which will automatically generate the aggregate query type: `aggregate<type_name>s`.\
Available operations are `count`, `max`, `min`, `sum`, `avg`, `totalSize`, and `groupBy`.

## Example

```typescript
import { db } from "@tailor-platform/sdk";

export const payroll = db
  .table("Payroll", "payroll model", {
    name: db.string().description("name"),
    paidAt: db.datetime().description("paidAt").required(),
    paidAmount: db.int().description("paidAmount").required(),
    payrollType: db.enum(["PAID", "UNPAID"]).description("paidType").required(),
    payrollCode: db.string().description("payrollCode"),
    customerID: db.uuid().description("customerID"),
  })
  .features({
    aggregation: true,
  });
```

TailorDB auto-generates `aggregatePayrolls`, allowing you to quickly retrieve summarized results for Payroll.\
Based on the `payroll` table, here's the sample query to aggregate the payroll data:

```graphql {{ title: 'query' }}
query {
  aggregatePayrolls {
    max {
      paidAmount
    }
    sum {
      paidAmount
    }
    min {
      paidAmount
    }
    avg {
      paidAmount
    }
    count {
      name
      toHour {
        paidAt
      }
    }
    totalSize
    groupBy {
      toDay {
        paidAt
      }
      name
    }
  }
}
```

In the `[PayrollsAggregationResult]` type, you can specify how you aggregate the data by using `groupBy`.\
Other fields such as `count` and `sum` will return results based on the grouping specified in `groupBy`.\
However `totalSize` always returns the total number of records regardless of the grouping.

The calculation fields `count`, `sum` `min` and `max` will be applicable only for the `Integer` and `Float` types.\
Besides, grouping by time windows such as `toDay` and `toHour` will be applicable only for the `Datetime` and `Date` types.

For SQL-based aggregate operations in Function service, see [SQL aggregate functions](/guides/function/accessing-tailordb#aggregatefunctions).

---

---
url: https://docs.tailor.tech/guides/tailordb/advanced-settings/bulk-upsert.md
---

# Bulk Upsert

Bulk Upsert queries enable inserting or updating large amounts of resources with a single query.
We can enable the `bulkUpsert` setting for your type, which will automatically generate the bulk upsert query type: `bulkUpsert<type_name>s`.

```typescript
import { db } from "@tailor-platform/sdk";

export const document = db
  .table("Document", "Document model", {
    // ...fields
  })
  .features({
    bulkUpsert: true,
  });
```

TailorDB auto-generates `bulkUpsertDocuments`, allowing you to quickly bulk upsert data for Document.
Use the following query to upsert existing document resources:

```graphql {{ title: 'query' }}
mutation {
  bulkUpsertDocuments(
    input: [
      { id: "<resource_uuid_1>", documentStatus: "documentToUpdate1" }
      { id: "<resource_uuid_2>", documentStatus: "documentToUpdate2" }
    ]
  )
}
```

If the input contains existing IDs, the data properties will be updated for those inputs. New data records will be created if the ID does not exist, is null, or is not passed as an input property.

Here are examples of queries for creating new records in TailorDB when using bulk upsert.

```graphql {{ title: 'query' }}
mutation {
  bulkUpsertDocuments(
    input: [
      { id: null, documentStatus: "createsNewDocument1" }
      { id: null, documentStatus: "createsNewDocument2" }
    ]
  )
}
```

```graphql {{ title: 'query' }}
mutation {
  bulkUpsertDocuments(
    input: [{ documentStatus: "createsNewDocument1" }, { documentStatus: "createsNewDocument2" }]
  )
}
```

The maximum number of items that can be included in a single bulk upsert operation is 1000.

## BulkUpsert with PluralForm settings

When `PluralForm` is configured in the settings, as mentioned in the example below, TailorDB auto-generates `bulkUpsertUserDataList` instead of `bulkUpsertUserData` for bulk upserting data of the `UserData` table. Refer [PluralForm](/guides/tailordb/advanced-settings/uncountable-nouns) to learn about its setting.

```typescript
import { db } from "@tailor-platform/sdk";

export const userData = db
  .table("UserData", "UserData model", {
    // ...fields
  })
  .features({
    bulkUpsert: true,
    pluralForm: "UserDataList",
  });
```

---

---
url: https://docs.tailor.tech/guides/tailordb/advanced-settings/tailordb-cdc.md
---

# TailorDB CDC

## Publish record events for database triggers

Change data capture (CDC) enables you to track and capture all changes in your data within TailorDB, including new record insertions, updates to existing records, and deletions. To use this feature, enable `PublishRecordEvents` in the settings for your desired table in TailorDB. Once enabled, any changes to records of this table will trigger the publication of record events. These events are then processed by the corresponding `Executor` service, which initiates the jobs defined based on these changes.

For example, to call a trigger for every PurchaseOrder type record created, you'll need to enable `PublishRecordEvents` in the settings. Refer [Event based trigger](/tutorials/setup-executor/event-based-trigger#4enablepublishrecordeventssettings) to learn more.

```typescript
import { db } from "@tailor-platform/sdk";

export const purchaseOrder = db
  .table(
    "PurchaseOrder",
    "Model for Purchase Order. Each record of the Purchase Order represents unique combination of a Product, a Location, and a Supplier.",
    {
      // ...fields
    },
  )
  .features({
    aggregation: true,
    publishRecordEvents: true,
  });
```

---

---
url: >-
  https://docs.tailor.tech/guides/tailordb/advanced-settings/uncountable-nouns.md
---

# Plural form for uncountable nouns

The `PluralForm` field accepts the plural form for an uncountable noun table in your TailorDB.
This setting is necessary to access individual records when the table name is an uncountable noun.

For example, to create table `userData` in the TailorDB, configure the `PluralForm` in the settings as the following:

```typescript
import { db } from "@tailor-platform/sdk";

export const userData = db
  .table("UserData", "User Data Model", {
    name: db.string().description("Name of the user"),
    ...db.fields.timestamps(),
  })
  .features({
    pluralForm: "UserDataList",
  });
export type userData = typeof userData;
```

The following query retrieves the list:

```graphql
query {
  UserDataList {
    edges {
      node {
        name
      }
    }
  }
}
```

Here is the query to retrieve individual records of the UserData table:

```graphql
query{
  userData(id:<userDataId>){
    name
  }
}
```

---

---
url: https://docs.tailor.tech/guides/tailordb/advanced-settings/vector-search.md
---

# Vector Search

Vector Search enables searching data using natural language queries.
We can enable the `Vector Field` for your fields properties, which will automatically calculate embeddings and generate vector query params.
Currently, Vector Search can only be enabled for `#TypeString` and cannot be used in conjunction with nested or array types.

```typescript
import { db } from "@tailor-platform/sdk";

export const product = db.table("Product", "Product model", {
  // ...
  description: db.string().description("Product description").vector(),
  ...db.fields.timestamps(),
});
export type product = typeof product;
```

We can use Vector Search specifying `vector: {<field name>: "natural language query"}`, which returns results in the order they match the query:

```graphql {{ title: 'query' }}
query VectorSearchProduct {
  products(vector: { description: "What products are associated with A and B?" })
}
```

It is useful to specify the `first` and to use a [query filter](/guides/tailordb/filters) to narrow down the results with Vector Search.

```graphql {{ title: 'query' }}
query VectorSearchProduct {
  products(
    first: 10
    query: { name: { contains: "XX" } }
    vector: { description: "What products are associated with A and B?" }
  )
}
```

## Function Service Support

Vector Search is also available in the Function service using SQL syntax. You can use the `vector_similarity` function to sort records by similarity. For more details, see [Accessing TailorDB from Function service](/guides/function/accessing-tailordb#vector-similarity-search).

---

---
url: https://docs.tailor.tech/guides/executor/overview.md
---

# Executor Service

The Executor Service offers a robust and integrated solution for automating tasks and managing workflows across the platform's core services.

## Quick Start with SDK

Create event-driven handlers with TypeScript:

```typescript
import { createExecutor, recordCreatedTrigger } from "@tailor-platform/sdk";
import { user } from "../tailordb/user";

export default createExecutor({
  name: "user-welcome",
  description: "Send welcome email to new users",
  trigger: recordCreatedTrigger({
    type: user,
    condition: ({ newRecord }) => !!newRecord.email && newRecord.isActive,
  }),
  operation: {
    kind: "function",
    body: async ({ newRecord }) => {
      // Send welcome email logic here
      console.log(`Welcome ${newRecord.email}!`);
    },
  },
});
```

### Schedule-based Trigger

```typescript
import { createExecutor, scheduleTrigger } from "@tailor-platform/sdk";

export default createExecutor({
  name: "daily-cleanup",
  trigger: scheduleTrigger({ cron: "0 0 * * *" }), // Every day at midnight
  operation: {
    kind: "function",
    body: async () => {
      // Cleanup logic
    },
  },
});
```

### Webhook Trigger

```typescript
import { createExecutor, incomingWebhookTrigger } from "@tailor-platform/sdk";

interface WebhookPayload {
  body: { event: string; data: unknown };
  headers: Record<string, string>;
}

export default createExecutor({
  name: "external-webhook",
  trigger: incomingWebhookTrigger<WebhookPayload>(),
  operation: {
    kind: "function",
    body: async ({ body, headers }) => {
      console.log(`Received event: ${body.event}`);
    },
  },
});
```

## Overview

Executors consist of two main properties:

1. `trigger`: defines when the execution should happen.

2. `operation`: defines what action should be performed.

## Trigger

The `Trigger` property defines the conditions under which the Executor service initiates an action. It specifies the event type and condition that must be met for the action to be triggered.

You can configure the following three types of triggers to execute the user defined tasks.

1. [Event-based trigger](event-based-trigger)

2. [Incoming webhook trigger](incoming-webhook-trigger)

3. [Schedule-based trigger](schedule-based-trigger)

## Operation

The `operation` property defines the action to be executed when the Trigger condition is met. You can describe the specific task or operation to be performed, such as querying TailorDB, sending notifications, or triggering workflows.
There are five types of targets:

1. [TailorGraphql](tailor-graphql-operation)

This involves interaction with the TailorDB and performs operations such as querying data or making changes (mutations).

2. [Webhook](webhook-operation)

With this type of operation, you can send a HTTP request from your executor service. Currently we only support POST method.

3. [Function](function-operation)

This operation type executes JavaScript/TypeScript code synchronously via the Function Service. Functions return results directly and are ideal for custom business logic, data transformations, and API integrations.

4. [Job Function](job-function-operation)

This operation type executes JavaScript/TypeScript code asynchronously via the Function Service. Job functions are typically used for asynchronous task processing, long-running operations, and background processing.

5. [Workflow](workflow-operation)

This operation type triggers workflow executions from the Executor service. Workflows are ideal for complex, multi-step processes and long-running orchestrations that need to be triggered by events, webhooks, or schedules.

Each Trigger can be configured with the above five target types, providing fifteen ways to configure them.

## Timeouts

Both operations `TailorGraphql` and `Webhook` have a timeout set to 60 seconds. If the process exceeds this limit, it is considered a failure, and a retry will be triggered (up to a maximum of 10 attempts).

You can view the number of attempts for each job created for an executor in the [Tailor Console](https://console.tailor.tech).

For more details on the number of attempts, refer to the [Verify the trigger](/tutorials/setup-executor/event-based-trigger#5verifythetrigger) section of the event-based trigger tutorial.

Additionally, executor operations are subject to a recursive call depth limit of 10 levels when triggering other platform services. See [Platform Limits](/reference/platform/platform-limits#recursive-call-detection) for more details.

---

---
url: https://docs.tailor.tech/guides/executor/event-based-trigger.md
---

# Event-based Trigger

In this trigger, you can specify the type of event that initiates it (e.g., TailorDB data update, IdP user changes, authentication events, or workflow execution state transitions) and outline the specific conditions or criteria for its execution.

Refer [Supported Events](/guides/events) to learn about the different types of events supported in the Tailor Platform. Follow the [tutorial](/tutorials/setup-executor/event-based-trigger) for setup instructions.

## Basic Event-Based Trigger Configuration

The following example shows the basic structure of an event-based trigger using the SDK:

```typescript {{title:'executors/event-based-executor.ts'}}
import { createExecutor, recordCreatedTrigger } from "@tailor-platform/sdk";

export default createExecutor({
  name: "event-based-executor",
  description: "Execute operation based on an event",
  trigger: recordCreatedTrigger({
    type: Category,
    condition: ({ newRecord }) => !!newRecord.id,
  }),
  operation: {
    // Choose one of the operation types:
    // kind: "tailorGraphql", ...
    // kind: "webhook", ...
    // kind: "function", ...
    // kind: "jobFunction", ...
  },
});
```

## Event Data Access

Event-based triggers provide access to event-specific data through the `args` object. The available data depends on the event type.

`args.eventType` is available for all event types, indicating which specific event triggered the executor (e.g., `tailordb.type_record.created`). This is useful when an executor listens to multiple event types and needs to differentiate between them.

### TailorDB Events

* `args.eventType` - The type of event that occurred (e.g., `tailordb.type_record.created`)
* `args.namespaceName` - The namespace where the event occurred
* `args.typeName` - The type name of the record
* `args.newRecord` - The new/created record data (available for created and updated events)
* `args.oldRecord` - The previous record data (available for updated and deleted events)

### IdP Events

* `args.eventType` - The type of event that occurred (e.g., `idp.user.created`)
* `args.namespaceName` - The namespace where the event occurred
* `args.userId` - The ID of the affected IdP user

### Auth Events

* `args.eventType` - The type of event that occurred (e.g., `auth.access_token.issued`)
* `args.namespaceName` - The namespace where the event occurred

### Resolver Events

* `args.eventType` - The type of event that occurred (e.g., `pipeline.resolver.executed`)
* `args.namespaceName` - The namespace where the event occurred
* `args.resolverName` - The name of the resolver
* `args.result` - The resolver execution result (on success)
* `args.error` - The error message (on failure)

### Workflow Execution Events

Workflow triggers expose the short event name on `args.event` for type narrowing, and the full event type on `args.rawEvent`. Workflows are not scoped to an application namespace, so these args carry no `args.namespaceName`.

* `args.event` - The short event name (`started`, `completed`, `retried`, `resumed`, `wait_started`, or `wait_resolved`)
* `args.rawEvent` - The full event type (e.g., `workflow.workflow_execution.completed`)
* `args.workflowId` - The ID of the workflow resource
* `args.workflowName` - The name of the workflow
* `args.workflowExecutionId` - The ID of the workflow execution
* `args.success` - Whether the execution succeeded (on `completed`)
* `args.error` - The error message (on `completed` when `args.success` is `false`)
* `args.retryCount` / `args.retryAfter` - The number of retries already attempted and the timestamp the retry is scheduled for (on `retried`)

Job-level triggers receive the same fields, with `args.event` narrowed to `started`, `completed`, `wait_started`, or `wait_resolved`, plus:

* `args.workflowJobExecutionId` - The ID of the job execution
* `args.jobFunctionName` - The name of the job, as passed to `createWorkflowJob`
* `args.waitKey` - The wait point key (on `wait_started` and `wait_resolved`)
* `args.waitPayload` - The JSON-serialized payload recorded with the wait point, when it recorded one (on `wait_started`)

```typescript {{title:'executors/order-workflow-finished.ts'}}
import { createExecutor, workflowExecutionTrigger } from "@tailor-platform/sdk";
import orderWorkflow from "../workflows/order";

export default createExecutor({
  name: "order-workflow-finished",
  description: "Notify when the order workflow finishes",
  trigger: workflowExecutionTrigger({
    workflow: orderWorkflow,
    events: ["completed", "retried"],
  }),
  operation: {
    kind: "function",
    body: async (args) => {
      if (args.event === "completed" && !args.success) {
        console.error(args.error);
      }
    },
  },
});
```

Single-event helpers are also available: `workflowExecutionStartedTrigger()`, `workflowExecutionCompletedTrigger()`, `workflowExecutionRetriedTrigger()`, `workflowExecutionResumedTrigger()`, `workflowExecutionWaitStartedTrigger()`, and `workflowExecutionWaitResolvedTrigger()`, along with their `workflowJobExecution*` counterparts and the multi-event `workflowJobExecutionTrigger()`.

These triggers require the target resource to publish execution events, which `deploy` enables automatically. A `workflowExecution*` trigger enables it on the workflow it names, and a `workflowJobExecution*` trigger enables it on every job that workflow runs. Set `publishEvents` on the workflow or the job to override that. See [Execution Events](/guides/workflow/monitoring-executions#execution-events).

## Operation Types

For detailed operation properties, see the dedicated operation pages:

* [TailorGraphql Operation](tailor-graphql-operation)
* [Webhook Operation](webhook-operation)
* [Function Operation](function-operation)
* [Job Function Operation](job-function-operation)

## Related Documentation

* [Supported Events](/guides/events)
* [Event-based Trigger Tutorial](/tutorials/setup-executor/event-based-trigger)

---

---
url: https://docs.tailor.tech/guides/executor/function-operation.md
---

# Function Operation

The Function operation executes JavaScript/TypeScript code synchronously via the Function Service. Functions return results directly and are ideal for custom business logic that cannot be expressed in GraphQL, data transformations, integration with external APIs, and complex calculations.

For more details on writing functions, refer to the [Function Service](/guides/function/overview) documentation.

## Configuration Example

```typescript
createExecutor({
  name: "function-executor",
  description: "Execute synchronous function",
  trigger: recordCreatedTrigger({ type: dataRecord }),
  operation: {
    kind: "function",
    body: async ({ newRecord }) => {
      // Process the data
      const data = newRecord;
      const timestamp = new Date().toISOString();
      // Function logic here
      return { data, timestamp };
    },
  },
});
```

## Properties

**Executor Properties**

| Property      | Type   | Required | Description                                                                                                                                 |
| ------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`        | string | Yes      | The name of the executor. The name field has the validation rule `^[a-z0-9][a-z0-9-]{1,61}[a-z0-9]$`, and it does not allow capital letters |
| `description` | string | No       | The description of the executor                                                                                                             |
| `trigger`     | object | Yes      | The type of trigger (e.g., `recordCreatedTrigger`, `webhookTrigger`, `scheduleTrigger`)                                                     |

**Function Operation Properties**

| Property | Type     | Required | Description                                                                                                              |
| -------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------ |
| `kind`   | string   | Yes      | Must be `"function"` for function operations                                                                             |
| `body`   | function | Yes      | An async function containing the business logic. Receives trigger context (e.g., `newRecord`, `oldRecord`) as parameters |

**Executor Properties**

| Property       | Type   | Required | Description                                                                                                                                 |
| -------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`         | string | Yes      | The name of the executor. The name field has the validation rule `^[a-z0-9][a-z0-9-]{1,61}[a-z0-9]$`, and it does not allow capital letters |
| `workspace_id` | string | Yes      | The ID of the workspace that the executor namespace belongs to                                                                              |
| `description`  | string | No       | The description of the executor                                                                                                             |
| `trigger`      | object | Yes      | The type of trigger (webhook, event, or schedule)                                                                                           |

**Function Operation Properties**

| Property    | Type   | Supports Scripting                                                              | Required | Description                                                                               |
| ----------- | ------ | ------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------- |
| `name`      | string | -                                                                               | Yes      | The name of the function                                                                  |
| `script`    | string | -                                                                               | Yes      | The JavaScript/TypeScript code to execute                                                 |
| `invoker`   | object | -                                                                               | No       | The invoker of the operation                                                              |
| `variables` | string | [JavaScript](/reference/api/js-scripting) / [CEL](/reference/api/cel-scripting) | No       | The variables to pass to the function. Can access trigger-specific data via `args` object |

**Executor Properties**

| Property      | Type   | Required | Description                                                                                                                                 |
| ------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `Name`        | string | Yes      | The name of the executor. The name field has the validation rule `^[a-z0-9][a-z0-9-]{1,61}[a-z0-9]$`, and it does not allow capital letters |
| `Description` | string | No       | The description of the executor                                                                                                             |
| `Trigger`     | object | Yes      | The type of trigger (e.g., #TriggerIncomingWebhook, #TriggerEvent, #TriggerSchedule)                                                        |

**TargetFunction Properties**

| Property     | Type   | Supports Scripting                                                              | Required | Description                                                                               |
| ------------ | ------ | ------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------- |
| `Name`       | string | -                                                                               | Yes      | The name of the function                                                                  |
| `ScriptPath` | string | -                                                                               | Yes      | The path to the JavaScript/TypeScript script file                                         |
| `Invoker`    | object | -                                                                               | No       | The invoker of the operation                                                              |
| `Variables`  | string | [JavaScript](/reference/api/js-scripting) / [CEL](/reference/api/cel-scripting) | No       | The variables to pass to the function. Can access trigger-specific data via `args` object |

## Related Documentation

* [Function Service Overview](/guides/function/overview)
* [Function Service Examples](/guides/function/examples)
* [Accessing TailorDB from Functions](/guides/function/accessing-tailordb)
* [Event-Based Trigger](/guides/executor/event-based-trigger)
* [Incoming Webhook Trigger](/guides/executor/incoming-webhook-trigger)
* [Schedule-Based Trigger](/guides/executor/schedule-based-trigger)

---

---
url: https://docs.tailor.tech/guides/executor/incoming-webhook-trigger.md
---

# Incoming Webhook Trigger

The incoming webhook trigger exposes an HTTP endpoint that can be called by external services to trigger executor operations. This enables integration with third-party systems and services.

Follow the [tutorial](/tutorials/setup-executor/incoming-webhook-trigger) for setup instructions.

## Basic Incoming Webhook Trigger Configuration

The following example shows the basic structure of an incoming webhook trigger:

```typescript {{ title: 'incoming-webhook-based-executor.ts' }}
import { createExecutor, incomingWebhookTrigger } from "@tailor-platform/sdk";

export default createExecutor({
  name: "incoming-webhook-based-executor",
  description: "exposes an endpoint",
  trigger: incomingWebhookTrigger<{
    body: { event: string };
    headers: Record<string, string>;
  }>(),
  operation: {
    // Choose one of the operation types:
    // kind: "tailorGraphql", ...
    // kind: "webhook", ...
    // kind: "function", ...
    // kind: "jobFunction", ...
  },
});
```

## Payload Format

The payload structure received by the Executor's Incoming Webhook will have the following format:

```json
{
  "args": {
    "method": "POST", // The HTTP method (e.g., POST, GET)
    "headers": {
      "x-name": "example", // Headers are available in lowercase with hyphens
      "x-array-elements": ["element1", "element2"] // header can be array
    },
    "body": {
      "name": "John",
      "full_name": { "first_name": "John", "last_name": "Doe" }
    }
  }
}
```

The Executor's incoming webhook supports both `application/json` and `application/x-www-form-urlencoded` content types. When using form-urlencoded, form data is parsed into the body object with single values as strings and multiple values as arrays.

Here's an example of how to access different parts of the webhook payload:

When receiving form-urlencoded data, you can access the values directly from the body object:

## Webhook Data Access

Incoming webhook triggers provide access to HTTP request data through the `args` object:

* `args.body` - The request payload/body
* `args.headers` - The HTTP headers from the request
* `args.method` - The HTTP method used (typically POST)
* `args.query` - Query parameters from the URL

This data can be used in operation variables to process the incoming webhook data appropriately.

## Response

By default, the incoming webhook trigger responds with `204 No Content`. The executor operation runs asynchronously after the response is sent.

To customize the response, pass a `response` option to `incomingWebhookTrigger()`. The function receives the same `args` as the operation and returns the response body. The status code defaults to `200` when `response` is set, and can be overridden with `statusCode`.

```typescript
incomingWebhookTrigger<WebhookPayload>({
  response: (args) => ({ challenge: args.body.challenge }),
});
```

## Rate Limits

Incoming webhook endpoints are rate limited to **100 requests per second per workspace**, counted across all incoming webhook executors in the workspace. Requests above the limit are rejected at the gateway with `429 Too Many Requests` and the executor is not invoked.

Responses include `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` headers so senders can track remaining headroom. When you control the sending side, retry `429` responses with exponential backoff.

See [Incoming Webhook Rate Limit](/reference/platform/platform-limits#incoming-webhook-rate-limit) for details.

## Properties

**Incoming Webhook Trigger Properties**

| Property  | Type   | Required | Description                                 |
| --------- | ------ | -------- | ------------------------------------------- |
| `webhook` | object | Yes      | Empty object `{}` to enable webhook trigger |

For detailed operation properties, see the dedicated operation pages:

* [TailorGraphql Operation Properties](tailor-graphql-operation#properties)
* [Webhook Operation Properties](webhook-operation#properties)
* [Function Operation Properties](function-operation#properties)
* [Job Function Operation Properties](job-function-operation#properties)

Refer to the [Tailor Platform Provider documentation](https://registry.terraform.io/providers/tailor-platform/tailor/latest/docs/resources/executor) for more details on executor properties.

## Related Documentation

* [Incoming Webhook Trigger Tutorial](/tutorials/setup-executor/incoming-webhook-trigger)

---

---
url: https://docs.tailor.tech/guides/executor/job-function-operation.md
---

# Job Function Operation

The Job Function operation executes JavaScript or TypeScript code asynchronously via the Function Service. It is typically used for tasks that do not require an immediate response, long-running operations that may exceed synchronous request timeouts, and background processes triggered by events or schedules.

Unlike synchronous functions, which return results directly, a Job Function returns an execution ID that can be used to track the status of the task.

For more details on writing functions, refer to the [Function Service](/guides/function/overview) documentation.

## Configuration Example

```typescript
createExecutor({
  name: "job-function-executor",
  description: "Execute asynchronous job function",
  trigger: scheduleTrigger({ cron: "0 0 * * *" }),
  operation: {
    kind: "jobFunction",
    body: async () => {
      // Long-running task logic
      const taskId = `task-${Date.now()}`;
      const timestamp = new Date().toISOString();
      // Background processing logic here
    },
  },
});
```

## Properties

**Executor Properties**

| Property      | Type   | Required | Description                                                                                                                                 |
| ------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`        | string | Yes      | The name of the executor. The name field has the validation rule `^[a-z0-9][a-z0-9-]{1,61}[a-z0-9]$`, and it does not allow capital letters |
| `description` | string | No       | The description of the executor                                                                                                             |
| `trigger`     | object | Yes      | The type of trigger (e.g., `scheduleTrigger`, `eventTrigger`, `webhookTrigger`)                                                             |

**Job Function Operation Properties**

| Property | Type     | Required | Description                                              |
| -------- | -------- | -------- | -------------------------------------------------------- |
| `kind`   | string   | Yes      | Must be `"jobFunction"` for job function operations      |
| `body`   | function | Yes      | An async function containing the long-running task logic |

**Executor Properties**

| Property       | Type   | Required | Description                                                                                                                                 |
| -------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`         | string | Yes      | The name of the executor. The name field has the validation rule `^[a-z0-9][a-z0-9-]{1,61}[a-z0-9]$`, and it does not allow capital letters |
| `workspace_id` | string | Yes      | The ID of the workspace that the executor namespace belongs to                                                                              |
| `description`  | string | No       | The description of the executor                                                                                                             |
| `trigger`      | object | Yes      | The type of trigger (webhook, event, or schedule)                                                                                           |

**Job Function Operation Properties**

| Property    | Type   | Supports Scripting                                                              | Required | Description                                                                                   |
| ----------- | ------ | ------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------- |
| `name`      | string | -                                                                               | Yes      | The name of the job function                                                                  |
| `script`    | string | -                                                                               | Yes      | The JavaScript/TypeScript code to execute                                                     |
| `invoker`   | object | -                                                                               | No       | The invoker of the operation                                                                  |
| `variables` | string | [JavaScript](/reference/api/js-scripting) / [CEL](/reference/api/cel-scripting) | No       | The variables to pass to the job function. Can access trigger-specific data via `args` object |

**Executor Properties**

| Property      | Type   | Required | Description                                                                                                                                 |
| ------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `Name`        | string | Yes      | The name of the executor. The name field has the validation rule `^[a-z0-9][a-z0-9-]{1,61}[a-z0-9]$`, and it does not allow capital letters |
| `Description` | string | No       | The description of the executor                                                                                                             |
| `Trigger`     | object | Yes      | The type of trigger (e.g., #TriggerIncomingWebhook, #TriggerEvent, #TriggerSchedule)                                                        |

**TargetJobFunction Properties**

| Property     | Type   | Supports Scripting                                                              | Required | Description                                                                                   |
| ------------ | ------ | ------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------- |
| `Name`       | string | -                                                                               | Yes      | The name of the job function                                                                  |
| `ScriptPath` | string | -                                                                               | Yes      | The path to the JavaScript/TypeScript script file                                             |
| `Invoker`    | object | -                                                                               | No       | The invoker of the operation                                                                  |
| `Variables`  | string | [JavaScript](/reference/api/js-scripting) / [CEL](/reference/api/cel-scripting) | No       | The variables to pass to the job function. Can access trigger-specific data via `args` object |

## Concurrency

Up to **100 job function operations run concurrently per workspace**, regardless of trigger type. Executions beyond the limit are never rejected — they are queued and start automatically, oldest first, as running executions complete. This means a large burst (for example, a bulk import fanning out into thousands of event-triggered executions) is processed at a steady rate rather than all at once, and executions may start minutes after they were triggered. Design time-sensitive integrations to react to completion events rather than assuming a fixed completion time.

See [Platform Limits](/reference/platform/platform-limits#executor-job-function-concurrency-limit) for details.

## Use Cases

Job functions are ideal for:

* **Long-running operations**: Tasks that may take several minutes or hours to complete
* **Background processing**: Operations that don't require immediate response
* **Batch processing**: Processing large datasets or multiple records
* **External API integrations**: Calling external services that may have high latency
* **File processing**: Uploading, downloading, or transforming files
* **Email notifications**: Sending emails or other notifications
* **Data synchronization**: Syncing data between systems

## Related Documentation

* [Function Service Overview](/guides/function/overview)
* [Function Service Examples](/guides/function/examples)
* [Accessing TailorDB from Functions](/guides/function/accessing-tailordb)
* [Event-Based Trigger](/guides/executor/event-based-trigger)
* [Incoming Webhook Trigger](/guides/executor/incoming-webhook-trigger)
* [Schedule-Based Trigger](/guides/executor/schedule-based-trigger)

---

---
url: https://docs.tailor.tech/guides/executor/schedule-based-trigger.md
---

# Schedule-based Trigger

Schedule-based triggers enable you to automate task execution at specified intervals using cron expressions. This is ideal for periodic data processing, maintenance tasks, and scheduled operations.

Follow the [tutorial](/tutorials/setup-executor/schedule-based-trigger) for setup instructions.

## Basic Schedule-Based Trigger Configuration

The following example shows the basic structure of a schedule-based trigger:

```typescript {{title:'executors/scheduled-event-executor.ts'}}
import { createExecutor, scheduleTrigger } from "@tailor-platform/sdk";

export default createExecutor({
  name: "scheduled-event-executor",
  description: "execute operation on schedule",
  trigger: scheduleTrigger({
    cron: "* * * * *",
    timezone: "UTC",
  }),
  operation: {
    // Choose one of the operation types:
    // kind: "tailorGraphql", ...
    // kind: "webhook", ...
    // kind: "function", ...
    // kind: "jobFunction", ...
  },
});
```

## Schedule Configuration

Schedule-based triggers use cron expressions to define when operations should execute:

* `frequency` - A cron expression defining the schedule (e.g., `"0 */6 * * *"` for every 6 hours)
* `timezone` - The timezone for schedule interpretation (e.g., `"UTC"`, `"America/New_York"`)

### Common Cron Expression Examples

* `"* * * * *"` - Every minute
* `"0 * * * *"` - Every hour
* `"0 0 * * *"` - Every day at midnight
* `"0 0 * * 0"` - Every Sunday at midnight
* `"0 9 * * 1-5"` - Every weekday at 9 AM

## Properties

**Schedule-Based Trigger Properties**

| Property    | Type   | Required | Description                                                                                           |
| ----------- | ------ | -------- | ----------------------------------------------------------------------------------------------------- |
| `timezone`  | string | No       | This refers to the specific time zone in which the job's scheduled times are interpreted and executed |
| `frequency` | string | Yes      | The intervals at which the job is scheduled to run (cron expression)                                  |

For detailed operation properties, see the dedicated operation pages:

* [TailorGraphql Operation Properties](tailor-graphql-operation#properties)
* [Webhook Operation Properties](webhook-operation#properties)
* [Function Operation Properties](function-operation#properties)
* [Job Function Operation Properties](job-function-operation#properties)

Learn more about executor properties in the [Tailor Platform Provider documentation](https://registry.terraform.io/providers/tailor-platform/tailor/latest/docs/resources/executor).

## Related Documentation

* [Schedule-based Trigger Tutorial](/tutorials/setup-executor/schedule-based-trigger)

---

---
url: https://docs.tailor.tech/guides/executor/tailor-graphql-operation.md
---

# TailorGraphql Operation

The TailorGraphql operation enables interaction with TailorDB to perform operations such as querying data or making changes (mutations).
This operation type is ideal for database operations triggered by events, webhooks, or schedules.

## Configuration Example

```typescript {{title:'executor.ts'}}
import { createExecutor, recordCreatedTrigger } from "@tailor-platform/core/executor";
import { product } from "./tailordb/product";

export const tailorGraphqlExecutor = createExecutor({
  name: "tailor-graphql-executor",
  description: "Execute GraphQL operations",
  trigger: recordCreatedTrigger({ type: product }),
  operation: {
    kind: "graphql",
    appName: "ims",
    invoker: "eventUser",
    query: `
        mutation createProduct($categoryID: ID!, $title: String!) {
          createProduct(input: {
            categoryID: $categoryID
            title: $title
          }) {
            id
          }
        }
      `,
    variables: ({ newRecord }) => ({
      categoryID: newRecord.id,
      title: newRecord.name + " Product",
    }),
  },
});
```

## Properties

**Executor Properties**

| Property      | Type   | Required | Description                                                                                                                                 |
| ------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`        | string | Yes      | The name of the executor. The name field has the validation rule `^[a-z0-9][a-z0-9-]{1,61}[a-z0-9]$`, and it does not allow capital letters |
| `description` | string | No       | The description of the executor                                                                                                             |
| `trigger`     | object | Yes      | The type of trigger (webhook, event, or schedule)                                                                                           |

**GraphQL Operation Properties**

| Property    | Type     | Required | Description                                                            |
| ----------- | -------- | -------- | ---------------------------------------------------------------------- |
| `kind`      | string   | Yes      | Must be `"graphql"` for TailorGraphql operations                       |
| `appName`   | string   | Yes      | The name of the TailorDB application                                   |
| `query`     | string   | Yes      | The GraphQL query or mutation to execute                               |
| `variables` | function | No       | A function that returns the variables to pass to the GraphQL operation |
| `invoker`   | string   | No       | The invoker of the operation (e.g., `"eventUser"`)                     |

**Executor Properties**

| Property       | Type   | Required | Description                                                                                                                                 |
| -------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`         | string | Yes      | The name of the executor. The name field has the validation rule `^[a-z0-9][a-z0-9-]{1,61}[a-z0-9]$`, and it does not allow capital letters |
| `workspace_id` | string | Yes      | The ID of the workspace that the executor namespace belongs to                                                                              |
| `description`  | string | No       | The description of the executor                                                                                                             |
| `trigger`      | object | Yes      | The type of trigger (webhook, event, or schedule)                                                                                           |

**TailorGraphql Operation Properties**

| Property    | Type   | Supports Scripting                                                              | Required | Description                                    |
| ----------- | ------ | ------------------------------------------------------------------------------- | -------- | ---------------------------------------------- |
| `app_name`  | string | -                                                                               | Yes      | The name of the TailorDB application           |
| `query`     | string | [JavaScript](/reference/api/js-scripting) / [CEL](/reference/api/cel-scripting) | Yes      | The GraphQL query or mutation to execute       |
| `variables` | string | [JavaScript](/reference/api/js-scripting) / [CEL](/reference/api/cel-scripting) | No       | The variables to pass to the GraphQL operation |
| `invoker`   | object | -                                                                               | No       | The invoker of the operation                   |

Refer to the [Tailor Platform Provider documentation](https://registry.terraform.io/providers/tailor-platform/tailor/latest/docs/resources/executor) for more details on executor properties.

**Executor Properties**

| Property      | Type   | Required | Description                                                                                                                                 |
| ------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `Name`        | string | Yes      | The name of the executor. The name field has the validation rule `^[a-z0-9][a-z0-9-]{1,61}[a-z0-9]$`, and it does not allow capital letters |
| `Description` | string | No       | The description of the executor                                                                                                             |
| `Trigger`     | object | Yes      | The type of trigger (e.g., #TriggerIncomingWebhook, #TriggerEvent, #TriggerSchedule)                                                        |

**TargetTailorGraphql Properties**

| Property    | Type   | Supports Scripting                                                              | Required | Description                                    |
| ----------- | ------ | ------------------------------------------------------------------------------- | -------- | ---------------------------------------------- |
| `AppName`   | string | -                                                                               | Yes      | The name of the TailorDB application           |
| `Query`     | string | [JavaScript](/reference/api/js-scripting) / [CEL](/reference/api/cel-scripting) | Yes      | The GraphQL query or mutation to execute       |
| `Variables` | string | [JavaScript](/reference/api/js-scripting) / [CEL](/reference/api/cel-scripting) | No       | The variables to pass to the GraphQL operation |
| `Invoker`   | object | -                                                                               | No       | The invoker of the operation                   |

## Related Documentation

* [TailorDB Overview](/guides/tailordb/overview)
* [Auto-generated API](/guides/tailordb/auto-generated-api)
* [Event-Based Trigger](/guides/executor/event-based-trigger)
* [Incoming Webhook Trigger](/guides/executor/incoming-webhook-trigger)
* [Schedule-Based Trigger](/guides/executor/schedule-based-trigger)

---

---
url: https://docs.tailor.tech/guides/executor/webhook-operation.md
---

# Webhook Operation

The Webhook operation enables sending HTTP requests from your executor service to external endpoints. Currently, only POST method is supported. This operation type is ideal for integrating with external services, sending notifications, or triggering workflows in other systems.

## Configuration Example

```typescript {{title:'executor.ts'}}
import { createExecutor } from "@tailor-platform/dev-kit/executor";

createExecutor({
  name: "webhook-executor",
  description: "Send HTTP requests to external endpoints",
  trigger: {
    // Choose one of the trigger types:
    // eventTrigger({ ... })
    // incomingWebhookTrigger({ ... })
    // scheduleTrigger({ ... })
  },
  operation: {
    kind: "webhook",
    url: "https://api.example.com/webhook",
    headers: { "Content-Type": "application/json" },
    requestBody: ({ record }) => ({
      message: "Notification from executor",
      data: record,
    }),
  },
});
```

## Properties

**Executor Properties**

| Property      | Type   | Required | Description                                                                                                                                 |
| ------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`        | string | Yes      | The name of the executor. The name field has the validation rule `^[a-z0-9][a-z0-9-]{1,61}[a-z0-9]$`, and it does not allow capital letters |
| `description` | string | No       | The description of the executor                                                                                                             |
| `trigger`     | object | Yes      | The type of trigger (eventTrigger, incomingWebhookTrigger, or scheduleTrigger)                                                              |

**Webhook Operation Properties**

| Property      | Type     | Required | Description                                                       |
| ------------- | -------- | -------- | ----------------------------------------------------------------- |
| `kind`        | string   | Yes      | Must be `"webhook"`                                               |
| `url`         | string   | Yes      | The URL of the API endpoint                                       |
| `headers`     | object   | No       | Key-value pairs for HTTP headers                                  |
| `requestBody` | function | No       | A function that returns the payload to be included in the request |

**Executor Properties**

| Property       | Type   | Required | Description                                                                                                                                 |
| -------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`         | string | Yes      | The name of the executor. The name field has the validation rule `^[a-z0-9][a-z0-9-]{1,61}[a-z0-9]$`, and it does not allow capital letters |
| `workspace_id` | string | Yes      | The ID of the workspace that the executor namespace belongs to                                                                              |
| `description`  | string | No       | The description of the executor                                                                                                             |
| `trigger`      | object | Yes      | The type of trigger (webhook, event, or schedule)                                                                                           |

**Webhook Operation Properties**

| Property  | Type   | Supports Scripting                                                              | Required | Description                                          |
| --------- | ------ | ------------------------------------------------------------------------------- | -------- | ---------------------------------------------------- |
| `url`     | string | [JavaScript](/reference/api/js-scripting) / [CEL](/reference/api/cel-scripting) | Yes      | The URL of the API endpoint                          |
| `body`    | string | [JavaScript](/reference/api/js-scripting) / [CEL](/reference/api/cel-scripting) | No       | The payload or message to be included in the request |
| `headers` | array  | -                                                                               | No       | The headers to send with the webhook                 |

Learn more about executor properties in the [Tailor Platform Provider documentation](https://registry.terraform.io/providers/tailor-platform/tailor/latest/docs/resources/executor).

**Executor Properties**

| Property      | Type   | Required | Description                                                                                                                                 |
| ------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `Name`        | string | Yes      | The name of the executor. The name field has the validation rule `^[a-z0-9][a-z0-9-]{1,61}[a-z0-9]$`, and it does not allow capital letters |
| `Description` | string | No       | The description of the executor                                                                                                             |
| `Trigger`     | object | Yes      | The type of trigger (e.g., #TriggerIncomingWebhook, #TriggerEvent, #TriggerSchedule)                                                        |

**TargetWebhook Properties**

| Property  | Type   | Supports Scripting                                                              | Required | Description                                          |
| --------- | ------ | ------------------------------------------------------------------------------- | -------- | ---------------------------------------------------- |
| `URL`     | string | [JavaScript](/reference/api/js-scripting) / [CEL](/reference/api/cel-scripting) | Yes      | The URL of the API endpoint                          |
| `Body`    | string | [JavaScript](/reference/api/js-scripting) / [CEL](/reference/api/cel-scripting) | No       | The payload or message to be included in the request |
| `Headers` | array  | -                                                                               | No       | The headers to send with the webhook                 |

## Related Documentation

* [Event-Based Trigger](/guides/executor/event-based-trigger)
* [Incoming Webhook Trigger](/guides/executor/incoming-webhook-trigger)
* [Schedule-Based Trigger](/guides/executor/schedule-based-trigger)
* [Supported Events](/guides/events)

---

---
url: https://docs.tailor.tech/guides/executor/workflow-operation.md
---

# Workflow Operation

The Workflow operation enables triggering workflows from the Executor service. This operation type is ideal for automatically starting workflows in response to events, webhooks, or scheduled tasks.

For more details on workflows, refer to the [Workflow Service](/guides/workflow/) documentation.

## Configuration Example

```typescript {{ title: 'executor.ts' }}
import { createWorkflow, createExecutor } from "@tailor-platform/sdk";
import { order } from "./types";

const processOrderWorkflow = createWorkflow({
  name: "process-order",
  steps: [
    // workflow steps...
  ],
});

createExecutor({
  name: "workflow-executor",
  description: "Trigger workflow execution",
  // Choose one of the trigger types:
  // trigger: recordCreatedTrigger({ type: order }),
  // trigger: webhookTrigger(),
  // trigger: scheduleTrigger({ cron: "0 * * * *" }),
  operation: {
    kind: "workflow",
    workflow: processOrderWorkflow,
    args: ({ newRecord }) => ({
      orderId: newRecord.id,
      timestamp: new Date().toISOString(),
    }),
  },
});
```

## Properties

**Executor Properties**

| Property      | Type   | Required | Description                                                                                                                                 |
| ------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`        | string | Yes      | The name of the executor. The name field has the validation rule `^[a-z0-9][a-z0-9-]{1,61}[a-z0-9]$`, and it does not allow capital letters |
| `description` | string | No       | The description of the executor                                                                                                             |
| `trigger`     | object | Yes      | The type of trigger (e.g., `recordCreatedTrigger`, `webhookTrigger`, `scheduleTrigger`)                                                     |

**Workflow Operation Properties**

| Property   | Type         | Required | Description                                                                                                              |
| ---------- | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------ |
| `kind`     | `"workflow"` | Yes      | Specifies this is a workflow operation                                                                                   |
| `workflow` | Workflow     | Yes      | The workflow to trigger (created with `createWorkflow()`)                                                                |
| `args`     | function     | No       | A function that returns the arguments to pass to the workflow. Receives trigger context (e.g., `newRecord`, `oldRecord`) |

**Executor Properties**

| Property       | Type   | Required | Description                                                                                                                                 |
| -------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`         | string | Yes      | The name of the executor. The name field has the validation rule `^[a-z0-9][a-z0-9-]{1,61}[a-z0-9]$`, and it does not allow capital letters |
| `workspace_id` | string | Yes      | The ID of the workspace that the executor namespace belongs to                                                                              |
| `description`  | string | No       | The description of the executor                                                                                                             |
| `trigger`      | object | Yes      | The type of trigger (webhook, event, or schedule)                                                                                           |

**Workflow Operation Properties**

| Property        | Type   | Supports Scripting                                                              | Required | Description                                                                               |
| --------------- | ------ | ------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------- |
| `workflow_name` | string | -                                                                               | Yes      | The name of the workflow to trigger                                                       |
| `invoker`       | object | -                                                                               | No       | The invoker of the operation                                                              |
| `variables`     | string | [JavaScript](/reference/api/js-scripting) / [CEL](/reference/api/cel-scripting) | No       | The variables to pass to the workflow. Can access trigger-specific data via `args` object |

Learn more about executor properties in the [Tailor Platform Provider documentation](https://registry.terraform.io/providers/tailor-platform/tailor/latest/docs/resources/executor).

**Executor Properties**

| Property      | Type   | Required | Description                                                                                                                                 |
| ------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `Name`        | string | Yes      | The name of the executor. The name field has the validation rule `^[a-z0-9][a-z0-9-]{1,61}[a-z0-9]$`, and it does not allow capital letters |
| `Description` | string | No       | The description of the executor                                                                                                             |
| `Trigger`     | object | Yes      | The type of trigger (e.g., #TriggerIncomingWebhook, #TriggerEvent, #TriggerSchedule)                                                        |

**TargetWorkflow Properties**

| Property       | Type   | Supports Scripting                                                              | Required | Description                                                                               |
| -------------- | ------ | ------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------- |
| `WorkflowName` | string | -                                                                               | Yes      | The name of the workflow to trigger                                                       |
| `Invoker`      | object | -                                                                               | No       | The invoker of the operation                                                              |
| `Variables`    | string | [JavaScript](/reference/api/js-scripting) / [CEL](/reference/api/cel-scripting) | No       | The variables to pass to the workflow. Can access trigger-specific data via `args` object |

## Use Cases

Workflow operations are ideal for:

* **Event-driven automation**: Automatically trigger workflows when database records are created, updated, or deleted
* **Webhook processing**: Start workflows in response to external webhooks from third-party services
* **Scheduled workflows**: Execute workflows on a regular schedule (e.g., daily reports, periodic data synchronization)
* **Microservices orchestration**: Coordinate complex business processes across multiple services
* **Long-running processes**: Handle tasks that require multiple steps or extended processing time
* **Asynchronous task processing**: Trigger workflows for background processing without blocking the main request

## Related Documentation

* [Workflow Service Overview](/guides/workflow/)
* [Creating Workflows](/guides/workflow/creating-workflows)
* [Triggering Workflows](/guides/workflow/triggering-workflow)
* [Monitoring Executions](/guides/workflow/monitoring-executions)
* [Event-Based Trigger](/guides/executor/event-based-trigger)
* [Incoming Webhook Trigger](/guides/executor/incoming-webhook-trigger)
* [Schedule-Based Trigger](/guides/executor/schedule-based-trigger)

---

---
url: https://docs.tailor.tech/guides/function/overview.md
---

# Function service

## Overview

Function service lets you run your JavaScript code as serverless functions in Tailor Platform.
You can write your code and deploy it to Tailor Platform, and then trigger it from resolvers or Executors.
This provides a flexible way to extend your application's functionality with custom business logic.

With Function service, you can:

* Send HTTP requests to 3rd party applications
* Access and execute SQL queries to TailorDB
* Manage IdP users, secrets, files, and workflows via [built-in interfaces](/guides/function/builtin-interfaces)
* Process data transformations
* Implement custom business logic with npm packages

To keep the this guide simple, we'll focus on a basic example of writing a function that returns a greeting message.
For more advanced use cases, you can refer to these sections:

* [Built-in interfaces](/guides/function/builtin-interfaces) — all platform APIs available as global variables
* [Sending HTTP request](/guides/function/sending-request)
* [Accessing TailorDB](/guides/function/accessing-tailordb)

## How to write and deploy your code in Function service

The deployment process involves three main steps:

1. Write your function
2. Set up the function in your Resolver or Executor
3. Execute the function from your application

You can see the actual code examples [here](https://github.com/tailor-platform/templates/tree/main/docs/sample-inventory-management).

### 1. Writing Your Function

With SDK, functions are defined inline within the resolver or executor files using TypeScript.

### 2. Set up the function in your resolver or Executor

#### Directory Structure

Here's the sample directory structure for an SDK project.
Your function code is defined inline within the resolver or executor files.

```sh {{ title: 'SDK directory structure' }}
.
├── tailor.config.ts
├── package.json
├── resolvers
│   └── function-sample-hello.ts
├── executors
│   └── webhook-function.ts
└── tailordb
    └── ...
```

#### Resolver Example

With SDK, the schema definition is inferred from the input/output types.
Here's a sample SDK configuration for setting up a resolver with a function:

```typescript {{ title: 'function-sample-hello.ts' }}
import { createResolver, t } from "@tailor-platform/sdk";

export default createResolver({
  name: "functionSampleHello",
  description: "query resolver for function sample",
  operation: "query",
  input: {
    message: t.string(),
  },
  body: (context) => {
    return {
      message: context.input.message,
    };
  },
  output: t.object({
    message: t.string().nullable(),
  }),
});
```

#### Executor incoming webhook Example

```typescript {{ title: 'webhook-function.ts' }}
import { createExecutor, incomingWebhookTrigger } from "@tailor-platform/sdk";

export default createExecutor({
  name: "sample-function-01",
  description: "sample function",
  trigger: incomingWebhookTrigger(),
  operation: {
    kind: "function",
    body: async () => {
      return {
        message: "hi " + new Date().toISOString(),
      };
    },
  },
});
```

Once you've defined the SDK configuration, you can deploy it to Tailor Platform.
Please confirm your tailor.config.ts points to your target workspace and run this command:

```bash
npx tailor deploy
```

### 3. Execute the function from your application

After deploying your function, you can open the graphql playground and run the query.

To open the graphql playground, run the following command:

```bash
npx tailor app open -n {APP_NAME}
```

Then, you can run the query in the playground:

```graphql
query {
  functionSampleHello(input: { message: "test" }) {
    message
  }
}
```

Function operations are subject to a recursive call depth limit of 10 levels when calling other platform services. See [Platform Limits](/reference/platform/platform-limits#recursive-call-detection) for more details.

## Using the principal (`caller` / `invoker`)

When using the Function service with resolvers or Executors, you can access the current principal — a `TailorPrincipal` — from the body function. Resolvers expose it as `caller`; `function`/`jobFunction` executor operations expose it as `invoker`. Both are `null` for anonymous calls.

`TailorPrincipal` has the following properties:

* `id`: The ID of the principal
* `type`: `"user"` or `"machine_user"`
* `workspaceId`: The ID of the workspace the principal belongs to
* `attributes`: A map of the principal's attributes
* `attributeList`: A list of the principal's attribute IDs

### Resolver Example

In SDK, you can access the current caller's information via `context.caller` in the body function:

```typescript {{ title: 'function-sample-hello.ts' }}
import { createResolver, t } from "@tailor-platform/sdk";

export default createResolver({
  name: "functionSampleHello",
  description: "query resolver for function sample",
  operation: "query",
  input: {
    message: t.string(),
  },
  body: (context) => {
    return {
      message: context.caller?.id,
    };
  },
  output: t.object({
    message: t.string().nullable(),
  }),
});
```

#### Executor Example

```typescript {{ title: 'webhook-function.ts' }}
import { createExecutor, incomingWebhookTrigger } from "@tailor-platform/sdk";

export default createExecutor({
  name: "sample-function-01",
  description: "sample function",
  trigger: incomingWebhookTrigger(),
  operation: {
    kind: "function",
    body: async (context) => {
      return {
        message: "hi " + context.invoker?.id,
      };
    },
  },
});
```

## Further details

For more advanced use cases, you can refer to these sections:

* [Built-in interfaces](/guides/function/builtin-interfaces) — all platform APIs available as global variables (IdP, secrets, files, workflows, etc.)
* [Sending HTTP request](/guides/function/sending-request)
* [Accessing TailorDB](/guides/function/accessing-tailordb)

For list of supported packages, please refer to [Appendix](/guides/function/appendix).

---

---
url: https://docs.tailor.tech/guides/function/builtin-interfaces.md
---

# Built-in interfaces

Functions (Resolvers, Workflows, Executors) have access to built-in interfaces as global variables.
These provide direct access to platform services without external HTTP calls or token management.

All interfaces are typed via [`@tailor-platform/function-types`](https://github.com/tailor-platform/function/tree/main/packages/types) — install the package to get full TypeScript support.

Importing from `@tailor-platform/sdk` no longer activates these ambient `tailor.*` / `tailordb.*` globals automatically. Add `import "@tailor-platform/sdk/runtime/globals"` as a side-effect import in your function file (or use the typed wrappers from `@tailor-platform/sdk/runtime` instead) — see [Runtime](/sdk/runtime) for details.

## Overview

| Service                                   | Description                                                        |
| ----------------------------------------- | ------------------------------------------------------------------ |
| [IdP Client](#idp-client)                 | Create, update, delete IdP users and send password reset emails    |
| [Secret Manager](#secret-manager)         | Retrieve secrets from vaults                                       |
| [Auth Connection](#auth-connection)       | Get access tokens for external auth connections                    |
| [Character Encoding](#character-encoding) | Convert between character encodings (iconv)                        |
| [Workflow](#workflow)                     | Start workflows and execute job functions                          |
| [TailorDB Client](#tailordb-client)       | Execute SQL queries against TailorDB                               |
| [TailorDB File](#tailordb-file)           | Upload, download, and manage files in TailorDB                     |
| [Logger](#logger)                         | Emit structured logs with severity levels and queryable attributes |

## IdP Client

**Interface**: `tailor.idp.Client`

Manage Built-in IdP users directly from your function. No external HTTP calls or machine user tokens needed.

**See also**: [Managing IdP Users in Functions](/guides/function/managing-idp-users)

```typescript
const client = new tailor.idp.Client({ namespace: "my-namespace" });

// Create a user
const user = await client.createUser({ name: "user@example.com", password: "secret" });

// List users with filtering
const { users, totalCount } = await client.users({
  first: 10,
  query: { names: ["user@example.com"] },
});

// Get by ID or by name
const user = await client.user(userId);
const userByName = await client.userByName("foo@example.com");
await client.updateUser({ id: userId, name: "new@example.com" });
await client.deleteUser(userId);

// Send password reset email
await client.sendPasswordResetEmail({
  userId: user.id,
  redirectUri: "https://app.example.com/reset",
  fromName: "My App Support", // optional: overrides namespace default
  subject: "Reset your password", // optional: overrides namespace default
});
```

| Method                          | Returns                      | Description                                       |
| ------------------------------- | ---------------------------- | ------------------------------------------------- |
| `users(options?)`               | `Promise<ListUsersResponse>` | List users with optional filtering and pagination |
| `user(userId)`                  | `Promise<User>`              | Get a user by ID                                  |
| `userByName(name)`              | `Promise<User>`              | Get a user by name                                |
| `createUser(input)`             | `Promise<User>`              | Create a new user                                 |
| `updateUser(input)`             | `Promise<User>`              | Update an existing user                           |
| `deleteUser(userId)`            | `Promise<boolean>`           | Delete a user by ID                               |
| `sendPasswordResetEmail(input)` | `Promise<boolean>`           | Send a password reset email                       |

## Secret Manager

**Interface**: `tailor.secretmanager`

Retrieve secrets stored in Tailor Platform vaults.

```typescript
// Get a single secret
const apiKey = await tailor.secretmanager.getSecret("my-vault", "API_KEY");

// Get multiple secrets at once
const secrets = await tailor.secretmanager.getSecrets("my-vault", [
  "API_KEY",
  "API_SECRET",
] as const);
// secrets.API_KEY, secrets.API_SECRET
```

| Function                   | Returns                                    | Description                                           |
| -------------------------- | ------------------------------------------ | ----------------------------------------------------- |
| `getSecret(vault, name)`   | `Promise<string \| undefined>`             | Get a single secret. Returns `undefined` if not found |
| `getSecrets(vault, names)` | `Promise<Partial<Record<string, string>>>` | Get multiple secrets. Missing keys are omitted        |

## Auth Connection

**Interface**: `tailor.authconnection`

Get access tokens for configured external auth connections (e.g., OAuth providers).

```typescript
const token = await tailor.authconnection.getConnectionToken("my-google-connection");
// Use token to call external APIs
```

| Function                             | Returns        | Description                                      |
| ------------------------------------ | -------------- | ------------------------------------------------ |
| `getConnectionToken(connectionName)` | `Promise<any>` | Get the access token for a named auth connection |

## Character Encoding

**Interface**: `tailor.iconv`

Convert between character encodings. Useful for processing files in non-UTF-8 encodings (e.g., Shift\_JIS CSV files).

```typescript
// Convert Shift_JIS buffer to UTF-8 string
const text = tailor.iconv.decode(shiftJisBuffer, "Shift_JIS");

// Encode a string to Shift_JIS
const encoded = tailor.iconv.encode("こんにちは", "Shift_JIS");

// Convert between encodings
const result = tailor.iconv.convert(buffer, "EUC-JP", "UTF-8");

// List supported encodings
const encodings = tailor.iconv.encodings();
```

| Function                                 | Returns                | Description                                                      |
| ---------------------------------------- | ---------------------- | ---------------------------------------------------------------- |
| `convert(str, fromEncoding, toEncoding)` | `string \| Uint8Array` | Convert between encodings. Returns `string` when target is UTF-8 |
| `decode(buffer, encoding)`               | `string`               | Decode a buffer to a UTF-8 string                                |
| `encode(str, encoding)`                  | `string \| Uint8Array` | Encode a string to the specified encoding                        |
| `encodings()`                            | `string[]`             | List all supported encodings                                     |

The `Iconv` class is also available for node-iconv compatibility:

```typescript
const converter = new tailor.iconv.Iconv("Shift_JIS", "UTF-8");
const result = converter.convert(inputBuffer);
```

## Workflow

**Interface**: `tailor.workflow`

Start workflows and job functions from within a function.

```typescript
// Start a workflow
const executionId = await tailor.workflow.startWorkflow("processOrder", {
  orderId: "order-123",
});

// Start with a specific machine user
const executionId = await tailor.workflow.startWorkflow(
  "processOrder",
  { orderId: "order-123" },
  {
    authInvoker: {
      namespace: "my-namespace",
      machineUserName: "workflow-runner",
    },
  },
);

// Execute a job function
const result = await tailor.workflow.execJobFunction("calculateTax", {
  amount: 1000,
});

// Route the dispatch through a workspace-registered execution policy for
// per-key concurrency control (see the SDK Workflow guide for policy setup).
const scoped = await tailor.workflow.execJobFunction(
  "syncTenant",
  { tenantId: "acme" },
  { executionPolicyKey: `tenant-api.acme` },
);
```

| Function                                 | Returns           | Description                                                                                                                                                        |
| ---------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `startWorkflow(name, args?, options?)`   | `Promise<string>` | Start a workflow. Returns the execution ID                                                                                                                         |
| `execJobFunction(name, args?, options?)` | `Promise<any>`    | Execute a job function and return its result. `options.executionPolicyKey` routes the dispatch through a matching execution policy for per-key concurrency control |

For details on declaring execution policies and the key grammar, see [Execution Policies](/sdk/services/workflow#execution-policies) in the SDK Workflow reference.

## TailorDB Client

**Interface**: `tailordb.Client`

Execute SQL queries directly against TailorDB. For ORM-style access, consider using `@tailor-platform/function-kysely-tailordb`.

**See also**: [Accessing TailorDB](/guides/function/accessing-tailordb)

```typescript
const db = new tailordb.Client({ namespace: "my-namespace" });
await db.connect();

try {
  const result = await db.queryObject<{ id: string; name: string }>(
    "SELECT id, name FROM users WHERE active = $1",
    [true],
  );
  console.log(result.rows); // [{ id: "...", name: "..." }, ...]
} finally {
  await db.end();
}
```

| Method                       | Returns                   | Description                                      |
| ---------------------------- | ------------------------- | ------------------------------------------------ |
| `connect()`                  | `Promise<void>`           | Open the database connection                     |
| `end()`                      | `Promise<void>`           | Close the database connection                    |
| `queryObject<T>(sql, args?)` | `Promise<QueryResult<T>>` | Execute a SQL query with parameterized arguments |

## TailorDB File

**Interface**: `tailordb.file`

Upload, download, and manage files attached to TailorDB records.

```typescript
// Upload a file
const { metadata } = await tailordb.file.upload(
  "my-namespace",
  "Document",
  "attachment",
  recordId,
  fileData,
  { contentType: "application/pdf" },
);

// Download a file
const { data, metadata } = await tailordb.file.download(
  "my-namespace",
  "Document",
  "attachment",
  recordId,
);

// Download as Base64 (for embedding in JSON responses)
const { data: base64 } = await tailordb.file.downloadAsBase64(
  "my-namespace",
  "Document",
  "attachment",
  recordId,
);

// Stream download large files (>10MB)
await tailordb.file.downloadStream("my-namespace", "Document", "attachment", recordId);

// Stream upload a file
await tailordb.file.uploadStream(
  "my-namespace",
  "Document",
  "attachment",
  recordId,
  readableStream,
);

// Get metadata without downloading
const meta = await tailordb.file.getMetadata("my-namespace", "Document", "attachment", recordId);

// Delete a file
await tailordb.file.delete("my-namespace", "Document", "attachment", recordId);
```

**Note**: All methods take `(namespace, typeName, fieldName, recordId)` as the first four arguments.

| Method                                        | Returns                                 | Description                                      |
| --------------------------------------------- | --------------------------------------- | ------------------------------------------------ |
| `upload(..., data, options?)`                 | `Promise<FileUploadResponse>`           | Upload a file                                    |
| `download(...)`                               | `Promise<FileDownloadResponse>`         | Download a file as `Uint8Array`. Throws if >10MB |
| `downloadAsBase64(...)`                       | `Promise<FileDownloadAsBase64Response>` | Download as Base64 string. Throws if >10MB       |
| `delete(...)`                                 | `Promise<void>`                         | Delete a file                                    |
| `getMetadata(...)`                            | `Promise<FileMetadata>`                 | Get file metadata without downloading            |
| `downloadStream(...)`                         | `Promise<FileDownloadStreamResponse>`   | Download a file as a `ReadableStream`            |
| `uploadStream(..., readableStream, options?)` | `Promise<FileUploadResponse>`           | Upload a file using a `ReadableStream`           |

## Logger

**Interface**: `tailor.logger`

Emit structured logs with a severity level and optional attributes. The message is written to standard output, and the full entry with its attributes is exported as an OpenTelemetry log through [TelemetryRouter](/guides/opentelemetry) to your configured backend.

```typescript
tailor.logger.info("order processed", {
  orderId: "o-123",
  amount: 4980,
  items: ["sku-1", "sku-2"],
});

// Set attributes once, applied to every subsequent log in the same execution
tailor.logger.setAttributes({ tenantId: "t-001", requestId: "req-abc" });
tailor.logger.info("start"); // tenantId / requestId attached
```

| Method                        | Description                                                             |
| ----------------------------- | ----------------------------------------------------------------------- |
| `debug(message, attributes?)` | Emit a log at debug severity                                            |
| `info(message, attributes?)`  | Emit a log at info severity                                             |
| `warn(message, attributes?)`  | Emit a log at warning severity                                          |
| `error(message, attributes?)` | Emit a log at error severity                                            |
| `setAttributes(attributes)`   | Set attributes applied to every subsequent log in the current execution |

Attribute limits and other details are documented in the JSDoc.

---

---
url: https://docs.tailor.tech/guides/function/accessing-tailordb.md
---

# Accessing TailorDB

In order to access TailorDB from Function service, you need to instantiate the `Client` object from the `tailordb` package.
`tailordb` exists in the Function service environment by default, so you can use it without any additional installation.
Please specify the `namespace` of the TailorDB you want to connect to when creating the `Client` object.

Importing from `@tailor-platform/sdk` no longer activates the ambient `tailordb.*` global automatically. Add `import "@tailor-platform/sdk/runtime/globals"` as a side-effect import in your function file (or use the typed wrapper from `@tailor-platform/sdk/runtime` instead) — see [Runtime](/sdk/runtime) for details.

Here is the `Client` interface:

```ts
export interface Client {
  connect(): Promise<void>;
  end(): Promise<void>;
  queryObject<T>(sql: string, args?: readonly any[]): Promise<{ rows: T[] }>;
  createTransaction(name: string): Transaction;
  new (config?: { namespace?: string }): Client;
}

type Transaction = {
  begin(): Promise<void>;
  commit(): Promise<void>;
  rollback(): Promise<void>;
  queryObject<T>(sql: string, args?: readonly any[]): Promise<{ rows: T[] }>;
};
```

Please refer to the [Supported SQL queries](#supported-sql-queries) for more information on the SQL syntax supported in `Client.queryObject`.

## Sample codes to access TailorDB in JavaScript

### Getting data from TailorDB

```js {{ title: 'get_data_function.js' }}
globalThis.main = async function () {
  const client = new tailordb.Client({
    namespace: "ims",
  });

  await client.connect();
  const product = await client.queryObject("SELECT * FROM Product");
  await client.end();

  return {
    Product: product.rows,
  };
};
```

### Inserting data to TailorDB

```js {{ title: 'insert_data_function.js' }}
globalThis.main = async function (args) {
  const client = new tailordb.Client({
    namespace: "ims",
  });
  await client.connect();
  try {
    const millis = Date.now();
    const products = await client.queryObject("SELECT * FROM Product");
    const len = products.rows.length;
    if (len !== 0) {
      throw new Error(`The size of Product, expected:0 got:${len}`);
    }
    const fixtures = [
      `${millis} - Product 1`,
      `${millis} - Product 2`,
      `${millis} - Product 3`,
      `${millis} - Product 4`,
    ];
    const transaction = client.createTransaction("add_products");
    try {
      await transaction.begin();
      for (const i of fixtures) {
        const ret = await transaction.queryObject(`INSERT INTO Product (title) VALUES ('${i}')`);
      }
      await transaction.commit();
      const products = await client.queryObject(
        `SELECT * FROM Product WHERE title like '${millis}%'`,
      );
      const len = products.rows.length;
      if (len !== 4) {
        throw new Error(`The size of Product, expected:4 got:${len}`);
      }
      return {
        success: len === 4,
      };
    } catch (e) {
      throw new Error(`add_products failed with error:${e}\n${e.cause}`);
    }
  } finally {
    await client.end();
  }
};
```

## Deploy sample functions

### Directory Structure

Here's the sample directory structure for an SDK project.
Let's deploy the `insertData` resolver to Tailor Platform.
**Since we don't use npm packages in this example, we don't need to bundle the function.**

```sh {{ title: 'SDK directory structure' }}
.
├── tailor.config.ts
├── package.json
├── resolvers
│   └── insert-data.ts
└── tailordb
    └── product.ts
```

### Resolver Example

With SDK, you can use the Kysely query builder to access TailorDB in a type-safe manner.
Here's a sample SDK configuration for setting up a resolver that accesses TailorDB:

```typescript {{ title: 'insert-data.ts' }}
import { createResolver, t } from "@tailor-platform/sdk";
import { getDB } from "../generated/tailordb";

export default createResolver({
  name: "insertData",
  description: "sample mutation resolver",
  operation: "mutation",
  input: {
    title: t.string(),
  },
  body: async (context) => {
    const db = getDB("ims");
    const millis = Date.now();

    // Check if products already exist
    const existingProducts = await db.selectFrom("Product").selectAll().execute();

    if (existingProducts.length !== 0) {
      throw new Error(`The size of Product, expected:0 got:${existingProducts.length}`);
    }

    // Insert products using transactions
    const fixtures = [
      `${millis} - Product 1`,
      `${millis} - Product 2`,
      `${millis} - Product 3`,
      `${millis} - Product 4`,
    ];

    for (const title of fixtures) {
      await db.insertInto("Product").values({ title }).execute();
    }

    // Verify inserted products
    const products = await db
      .selectFrom("Product")
      .selectAll()
      .where("title", "like", `${millis}%`)
      .execute();

    return {
      success: products.length === 4,
    };
  },
  output: t.object({
    success: t.boolean().nullable(),
  }),
});
```

### TailorDB Example

To execute the function, you need to set up the Product table in TailorDB.

```typescript {{ title: 'product.ts' }}
import { db, auth } from "@tailor-platform/sdk";

export const product = db.table("Product", {
  title: db.string().description("Title of the product"),
  ...db.fields.timestamps(),
});
export type product = typeof product;
```

### Deployment

Let's deploy the function to Tailor Platform.

```sh
npx tailor deploy
```

## Supported SQL queries

Strictly speaking, the SQL statements here are executed via a proxy to TailorDB.
The SQL that can be issued is a subset of PostgreSQL, so the fundamental syntax follows PostgreSQL conventions.

### SELECT

#### Retrieve specific columns

```sql
SELECT "id", "name" FROM "Character";
```

#### Retrieve all columns

```sql
SELECT * FROM "Character";
```

#### Join tables

Only records where the user has `Read` permission for all joined records are returned.

Self-joins (joining the same table multiple times) are not supported.

```sql
SELECT * FROM "Character" JOIN "Species" ON "Character"."speciesID" = "Species"."id";
```

#### Use table aliases

You can specify aliases for table names to make queries more concise and readable. This is particularly useful in complex queries with multiple joins.

```sql
SELECT c.*, s.* FROM "Character" AS c LEFT JOIN "Species" AS s ON c."speciesID" = s."id";
```

You can also omit the `AS` keyword:

```sql
SELECT c."name", s."name" FROM "Character" c JOIN "Species" s ON c."speciesID" = s."id";
```

&#x20;Self-joins are not supported at this time. Assigning different aliases to the same table in the same query will result in an error.

#### Filter by condition

For specific supported operators, see `condition` in [Syntax](#syntax) section.

```sql
SELECT * FROM "Character" WHERE "name" = 'Alice';
```

#### Sort by column

As in PostgreSQL, when the order is omitted, the default is `ASC`.

`NULLS` cannot be specified, so null values are always treated as greater than non-null values.

```sql
SELECT * FROM "Character" ORDER BY "name" DESC;
```

#### Aggregate functions

You can use aggregate functions to perform calculations on sets of rows. The supported functions are `COUNT`, `SUM`, `AVG`, `MAX`, and `MIN`.

**COUNT function** - Count rows or non-null values in specific columns:

```sql
SELECT count(*), count(id), count(name), count(speciesID) FROM "Character";
```

**SUM function** - Calculate the sum of numeric values (Integer and Float fields only):

```sql
SELECT sum(age), sum(height) FROM "Character";
```

**AVG function** - Calculate the average of numeric values (Integer and Float fields only):

```sql
SELECT avg(age), avg(height) FROM "Character";
```

**MAX function** - Find the maximum value:

```sql
SELECT max(age), max(height) FROM "Character";
```

**MIN function** - Find the minimum value:

```sql
SELECT min(age), min(height) FROM "Character";
```

You can also use column aliases with any aggregate function:

```sql
SELECT count(*) as total, sum(age) as total_age, avg(height) as avg_height FROM "Character";
```

Aggregate functions with JOIN operations:

```sql
SELECT count(c.id), sum(c.age), avg(s.lifespan) FROM "Character" AS c LEFT JOIN "Species" AS s ON c.speciesID = s.id;
```

**Field type restrictions**

| Function | Allowed Field Types                                |
| -------- | -------------------------------------------------- |
| SUM      | Integer, Float                                     |
| AVG      | Integer, Float                                     |
| MAX      | Integer, Float, String, Enum, Date, Time, DateTime |
| MIN      | Integer, Float, String, Enum, Date, Time, DateTime |
| COUNT    | All field types                                    |

#### Group by columns

You can use the `GROUP BY` clause to group rows that have the same values in specified columns and perform aggregate calculations on each group.

```sql
SELECT "speciesID", COUNT(*) FROM "Character" GROUP BY "speciesID";
```

Filter groups using `HAVING`:

```sql
SELECT "speciesID", AVG("height") FROM "Character" GROUP BY "speciesID" HAVING COUNT(*) > 5;
```

For GraphQL-based aggregation queries in TailorDB, see [TailorDB Aggregation](/guides/tailordb/advanced-settings/aggregation).

#### Vector similarity search

You can use the `vector_similarity` function to sort records by similarity to a natural language query. This function is only available for fields that have been configured as Vector Fields in your TailorDB schema.

```sql
SELECT * FROM "Product" ORDER BY vector_similarity("description", 'What products are associated with A and B?') DESC LIMIT 5;
```

**Important notes:**

* If the specified field is not a Vector Field, an error will occur
* To retrieve the most similar records, be sure to explicitly use `DESC` in the `ORDER BY` clause
* For more information on setting up Vector Fields, see [Vector Search](/guides/tailordb/advanced-settings/vector-search)

#### Limit and offset the results

```sql
SELECT * FROM "Character" LIMIT 1 OFFSET 1;
```

#### Lock rows

```sql
SELECT * FROM "Character" FOR UPDATE;
```

### INSERT

#### Insert a single row

As in `TailorDB`, if no value is specified for `id`, a new UUID is automatically generated.

```sql
INSERT INTO "Starship" (
    "name",               -- String (text)
    "crew",               -- Int (int4)
    "length",             -- Float (float8)
    "isArmed",            -- Bool (bool)
    "status",             -- Enum (text)
    "serialNumber",       -- UUID (uuid)
    "manufactureDate",    -- Date (date)
    "maintenanceTime",   -- Time (time)
    "lastLaunchDateTime", -- DateTime (timestamptz)
    "hyperdriveRating",   -- Nested (jsonb)
    "manufacturers"       -- String Array (_text)
) VALUES (
    'Millennium Falcon',
    4,
    34.75,
    TRUE,
    'ACTIVE',
    'a845e77f-2bce-462a-9e25-8d9296c3545b',
    '1977-05-25',
    '22:00',
    '2019-12-20T00:00:00Z',
    '{"main": 0.5, "backup": 10.0}',
    ARRAY['Corellian Engineering Corporation']
);
```

#### Insert multiple rows

```sql
INSERT INTO "Character" ("name") VALUES ('Alice'), ('Bob');
```

#### Insert default values

With support for `DEFAULT`, fields can be explicitly omitted when values are automatically generated via Hooks, etc.

```sql
INSERT INTO "Character" ("name", "createdAt") VALUES ('Alice', DEFAULT);
```

When omitting all columns, `DEFAULT VALUES` can be used.

```sql
INSERT INTO "Character" DEFAULT VALUES;
```

#### Upsert

The conflict target (e.g., `id` in the example below) can only contain a single column.
Specify either `id` or a column with `Unique=true`.

```sql
INSERT INTO "Character" ("id", "name") VALUES ('a845e77f-2bce-462a-9e25-8d9296c3545b', 'Alice') ON CONFLICT ("id") DO UPDATE SET "name" = EXCLUDED."name";
```

#### Return the inserted row

```sql
INSERT INTO "Character" ("name") VALUES ('Alice') RETURNING *;
```

### UPDATE

#### Update specific columns

```sql
UPDATE "Character" SET "name" = 'Alice' WHERE "id" = 'a845e77f-2bce-462a-9e25-8d9296c3545b';
```

#### Return the updated row

```sql
UPDATE "Character" SET "name" = 'Alice' WHERE "id" = 'a845e77f-2bce-462a-9e25-8d9296c3545b' RETURNING *;
```

#### Arithmetic updates

```sql
UPDATE "Starship" SET "crew" = "crew" + 5 WHERE "id" = 'a845e77f-2bce-462a-9e25-8d9296c3545b';
```

### DELETE

#### Delete rows

```sql
DELETE FROM "Character" WHERE "id" = 'a845e77f-2bce-462a-9e25-8d9296c3545b';
```

#### Return the deleted row

```sql
DELETE FROM "Character" WHERE "id" = 'a845e77f-2bce-462a-9e25-8d9296c3545b' RETURNING *;
```

### Transaction

#### Insert multiple rows in a transaction

```sql
BEGIN;
INSERT INTO "Character" ("name") VALUES ('Alice');
INSERT INTO "Character" ("name") VALUES ('Bob');
COMMIT;
```

## Permission Enforcement

TailorDB Permission settings are enforced at the SQL level, based on PostgreSQL's Row-Level Security (RLS) specifications. When accessing TailorDB via the Function service, it's important to understand how the settings affect SQL operations.

### Important Notes

* **Hooks, Validate, Serial, OnConflict, and ForeignKey operations ignore Permission** - This corresponds to PostgreSQL ignoring RLS for consistency checks
* **Be mindful of covert channels** - Users might infer other record values based on ForeignKey constraints even without Read Permission

### SQL Operation Details

#### INSERT

1. Execute Hooks/Serial
2. Retrieve existing records by ON CONFLICT fields
3. For INSERT case:
   * Check Create Permission
   * If RETURNING clause: Check Read Permission
   * Execute Validate/ForeignKey
4. For UPDATE case:
   * Check Read Permission on record before update
   * Continue with UPDATE flow

#### SELECT

1. Retrieve records while filtering by Read Permission

#### UPDATE

1. Retrieve records while filtering by Read Permission
2. Execute Hooks
3. Check Update Permission
4. If RETURNING clause: Check Read Permission on updated record
5. Execute Validate/ForeignKey

#### DELETE

1. Retrieve records while filtering by Read Permission
2. Check Delete Permission
3. Execute ForeignKey

For more information on configuring TailroDB Permission, see the [Permission documentation](/guides/tailordb/permission).

## Syntax

```
statement ::=
    select
    | insert
    | update
    | delete
    | begin
    | commit
    | rollback

select ::=
    SELECT select_item [, ...]
    FROM table_with_alias
    [ join [...] ]
    [ WHERE condition ]
    [ GROUP BY qualified_column_name [, ...] ]
    [ HAVING condition ]
    [ ORDER BY column_name_or_vector [ ASC | DESC ] [, ...] ]
    [ LIMIT int_value ]
    [ OFFSET int_value ]
    [ FOR { UPDATE | SHARE } [...] ]

table_with_alias ::=
    table_name [ [ AS ] alias ]

select_item ::=
    qualified_column_name [ AS alias ]
    | [ table_name . ] *
    | aggregate_function [ AS alias ]

aggregate_function ::=
    COUNT ( { [ DISTINCT ] qualified_column_name | * } )
    | { SUM | AVG | MIN | MAX } ( [ DISTINCT ] qualified_column_name )

join ::=
    [ INNER | { LEFT | RIGHT | FULL } [ OUTER ] ] JOIN table_with_alias ON condition
    | CROSS JOIN table_with_alias

column_name_or_vector ::=
    qualified_column_name
    | vector_similarity ( qualified_column_name , column_value )

insert ::=
    INSERT INTO table_name
    { ( column_name [, ...] ) VALUES ( { column_value | DEFAULT } [, ...] ) [, ...]
      | DEFAULT VALUES }
    [ ON CONFLICT ( column_name ) conflict_action ]
    [ RETURNING select_item [, ...] ]

conflict_action ::=
    DO NOTHING
    | DO UPDATE SET column_name = { column_value | EXCLUDED . column_name } [, ...]
      [ WHERE condition ]

update ::=
    UPDATE table_name
    SET column_name = column_name_or_value [ arithmetic_operator column_name_or_value ] [, ...]
    [ WHERE condition ]
    [ RETURNING select_item [, ...] ]

arithmetic_operator ::=
    + | - | * | /

delete ::=
    DELETE FROM table_name
    [ WHERE condition ]
    [ RETURNING select_item [, ...] ]

begin ::=
    { BEGIN [ WORK | TRANSACTION ] | START TRANSACTION }
    [ transaction_mode [, ...] ]

transaction_mode ::=
    ISOLATION LEVEL { SERIALIZABLE | REPEATABLE READ | READ COMMITTED | READ UNCOMMITTED }
    | READ WRITE | READ ONLY
    | [ NOT ] DEFERRABLE

commit ::=
    COMMIT [ WORK | TRANSACTION ]

rollback ::=
    ROLLBACK [ WORK | TRANSACTION ]

condition ::=
    left_operand binary_operator column_name_or_value
    | left_operand [ NOT ] IN ( column_name_or_value [, ...] )
    | left_operand [ NOT ] BETWEEN column_name_or_value AND column_name_or_value
    | left_operand IS [ NOT ] NULL
    | condition { AND | OR } condition
    | ( condition )

left_operand ::=
    qualified_column_name
    | aggregate_function

binary_operator ::=
    = | <> | < | <= | > | >=
    | ~~ | !~~ | ~~* | !~~*
    | ~ | !~ | ~* | !~*
    | [ NOT ] LIKE | [ NOT ] ILIKE

column_name_or_value ::=
    qualified_column_name
    | column_value

qualified_column_name ::=
    [ table_or_alias . ] column_name

table_or_alias ::=
    table_name | alias
```

## Working with Files

TailorDB File Type can be accessed programmatically from functions using the `tailordb.file` API. This allows you to upload, download, and manage files directly within your function code. For GraphQL-based file operations and HTTP endpoints, see the [File Type documentation](/guides/tailordb/file-type).

The file API is available through the global `tailordb` object in your function runtime and provides methods for complete file lifecycle management.

### Upload Files

You can upload files by providing either string content or binary data as a `Uint8Array`. The upload method returns metadata about the uploaded file.

```typescript {{ title: 'Upload a text file' }}
const uploadResponse = await tailordb.file.upload(
  namespace,
  typeName,
  fieldName,
  recordId,
  "File content as string",
  { contentType: "text/plain" },
);

console.log(`Uploaded: ${uploadResponse.metadata.fileSize} bytes`);
console.log(`SHA256: ${uploadResponse.metadata.sha256sum}`);
```

For binary files like images, use `Uint8Array`:

```typescript {{ title: 'Upload a binary file' }}
const pngData = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);

const imageUploadResponse = await tailordb.file.upload(
  namespace,
  typeName,
  fieldName,
  recordId,
  pngData,
  { contentType: "image/png" },
);
```

### Download Files

Download files to retrieve both the file content and metadata. The content is returned as a `Uint8Array`.

Files larger than 10 MB cannot be downloaded using download() or downloadAsBase64(). Attempting to download a file that exceeds this limit will throw a FILE\_TOO\_LARGE error. For larger files, use downloadStream(), as shown [here](#stream-large-files).

```typescript {{ title: 'Download a file' }}
const downloadResponse = await tailordb.file.download(namespace, typeName, fieldName, recordId);

console.log(`Downloaded: ${downloadResponse.metadata.fileSize} bytes`);
console.log(`Content type: ${downloadResponse.metadata.contentType}`);

const textContent = new TextDecoder().decode(downloadResponse.data);
```

The download response includes:

* `data`: The file content as `Uint8Array`
* `metadata`: File metadata object (see [API Reference](#api-reference))

### Download Files as Base64

For scenarios where you need the file content as a base64-encoded string (e.g., embedding in JSON responses or passing to external APIs), use `downloadAsBase64()`.

```typescript {{ title: 'Download a file as base64' }}
const base64Response = await tailordb.file.downloadAsBase64(
  namespace,
  typeName,
  fieldName,
  recordId,
);

console.log(`Downloaded: ${base64Response.metadata.fileSize} bytes`);
console.log(`Content type: ${base64Response.metadata.contentType}`);
console.log(`Base64 content: ${base64Response.data}`);
```

The response includes:

* `data`: The file content as a base64-encoded string
* `metadata`: File metadata object (see [API Reference](#api-reference))

### Get File Metadata

Retrieve file metadata without downloading the actual file content. This is useful for checking file properties without the overhead of downloading the entire file.

```typescript {{ title: 'Get file metadata' }}
const metadata = await tailordb.file.getMetadata(namespace, typeName, fieldName, recordId);

console.log(`URL Path: ${metadata.urlPath}`);
console.log(`Content Type: ${metadata.contentType}`);
console.log(`File Size: ${metadata.fileSize} bytes`);
console.log(`SHA256: ${metadata.sha256sum}`);
console.log(`Last Uploaded: ${metadata.lastUploadedAt}`);
```

### Stream Large Files

For large files, use `downloadStream()` to process files efficiently without loading the entire content into memory at once. It returns a standard Web `ReadableStream`.

```typescript {{ title: 'Stream download a large file' }}
const { body, metadata } = await tailordb.file.downloadStream(
  namespace,
  typeName,
  fieldName,
  recordId,
);

console.log(`Content type: ${metadata.contentType}`);
console.log(`File size: ${metadata.fileSize} bytes`);
// body is a ReadableStream<Uint8Array>
```

### Stream Upload Files

Use `uploadStream()` to upload large files using a `ReadableStream`. This is useful when you want to pipe data from one source directly into TailorDB without buffering the entire content in memory.

```typescript {{ title: 'Stream upload a file' }}
const { metadata } = await tailordb.file.uploadStream(
  namespace,
  typeName,
  fieldName,
  recordId,
  readableStream, // ReadableStream<Uint8Array | ArrayBuffer>
);
```

### Delete Files

Delete a file attached to a record. This removes the file but does not delete the record itself.

```typescript {{ title: 'Delete a file' }}
await tailordb.file.delete(namespace, typeName, fieldName, recordId);

console.log("File deleted successfully");
```

### Error Handling

All file operations throw `TailorDBFileError` on failure. Use this for proper error handling and diagnostics.

```typescript {{ title: 'Handle file errors' }}
try {
  await tailordb.file.upload(namespace, typeName, fieldName, recordId, fileContent, {
    contentType: "text/plain",
  });
} catch (error) {
  if (error instanceof TailorDBFileError) {
    console.error(`File error code: ${error.code}`);
    console.error(`Message: ${error.message}`);
  } else {
    console.error(`Unexpected error: ${error}`);
  }
}
```

### API Reference

#### File Metadata Properties

All file operations return or accept metadata with the following properties:

| Property         | Type     | Description                                             |
| ---------------- | -------- | ------------------------------------------------------- |
| `contentType`    | `string` | MIME type of the file (e.g., "image/png", "text/plain") |
| `fileSize`       | `number` | Size of the file in bytes                               |
| `sha256sum`      | `string` | SHA-256 checksum of the file content                    |
| `lastUploadedAt` | `string` | ISO 8601 timestamp of the last upload                   |
| `urlPath`        | `string` | Path portion of the URL                                 |

#### Method Signatures

```typescript
tailordb.file.upload(
  namespace: string,
  typeName: string,
  fieldName: string,
  recordId: string,
  content: string | Uint8Array,
  options: { contentType: string }
): Promise<{ metadata: FileMetadata }>

tailordb.file.download(
  namespace: string,
  typeName: string,
  fieldName: string,
  recordId: string
): Promise<{ data: Uint8Array; metadata: FileMetadata }>

tailordb.file.downloadAsBase64(
  namespace: string,
  typeName: string,
  fieldName: string,
  recordId: string
): Promise<{ data: string; metadata: FileMetadata }>

tailordb.file.getMetadata(
  namespace: string,
  typeName: string,
  fieldName: string,
  recordId: string
): Promise<FileMetadata>

tailordb.file.downloadStream(
  namespace: string,
  typeName: string,
  fieldName: string,
  recordId: string
): Promise<{ body: ReadableStream<Uint8Array>; metadata: DownloadMetadata }>

tailordb.file.uploadStream(
  namespace: string,
  typeName: string,
  fieldName: string,
  recordId: string,
  readableStream: ReadableStream<Uint8Array | ArrayBuffer>,
  options?: { contentType?: string; fileSize?: number }
): Promise<{ metadata: UploadMetadata }>

tailordb.file.delete(
  namespace: string,
  typeName: string,
  fieldName: string,
  recordId: string
): Promise<void>
```

### See Also

* [File Type documentation](/guides/tailordb/file-type) - For GraphQL operations, HTTP endpoints, and schema definitions
* [TailorDB Schema](/guides/tailordb/overview) - For defining fields in your schema

---

---
url: https://docs.tailor.tech/guides/function/appendix.md
---

# Appendix

## Operation confirmed packages in Function Service

These packages are confirmed to work in Function Service.\
Function service can use any npm packages not depending node runtime API.\
Please contact us if you have any questions or issues when you use these packages.

### Web Standard API

#### Crypto

* https://developer.mozilla.org/en-US/docs/Web/API/Crypto
* https://developer.mozilla.org/en-US/docs/Web/API/CryptoKey
* https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto

#### URL

* https://developer.mozilla.org/en-US/docs/Web/API/URL
* https://developer.mozilla.org/en-US/docs/Web/API/URLPattern
* https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams

#### Web

* https://developer.mozilla.org/en-US/docs/Web/API/Fetch\_API
* https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream
* https://developer.mozilla.org/en-US/docs/Web/API/WritableStream
* https://developer.mozilla.org/en-US/docs/Web/API/TextEncoder
* https://developer.mozilla.org/en-US/docs/Web/API/TextDecoder

#### Window

* https://developer.mozilla.org/en-US/docs/Web/API/Window/btoa
* https://developer.mozilla.org/en-US/docs/Web/API/Window/atob
* https://developer.mozilla.org/en-US/docs/Web/API/Window/clearInterval
* https://developer.mozilla.org/en-US/docs/Web/API/Window/clearTimeout
* https://developer.mozilla.org/en-US/docs/Web/API/Window/setInterval
* https://developer.mozilla.org/en-US/docs/Web/API/Window/setTimeout

### NPM modules

#### Date

* https://moment.github.io/luxon/#/
* https://day.js.org/
* https://date-fns.org/

#### Utility

* https://remedajs.com/
* https://lodash.com/
* https://underscorejs.org/

#### Big

* https://github.com/MikeMcl/big.js/wiki

#### Fetch

* https://github.com/axios/axios
* https://github.com/developit/redaxios

#### GraphQL

* https://www.npmjs.com/package/graphql-request
* https://www.npmjs.com/package/graphql

### JSR modules

All deno standard libraries registered on JSR should work on FR.

---

---
url: https://docs.tailor.tech/guides/function/debugging.md
---

# Debugging your function

When you write a function in Function service, you may encounter errors while running the function.
In this case, you can debug your code by checking the logs from your function.

## Example

Assuming you have a function like below:

```js {{ title: 'get_pokemon_function.js' }}
import { gql, request } from "graphql-request";

globalThis.main = async function (args) {
  const document = gql`
    query ExampleQuery($pokemon: String!) {
      getFuzzyPokemon(pokemon: $pokemon) {
        species
      }
    }
  `;

  console.log(JSON.stringify(args)); // log the input args

  const variables = {
    pokemon: args.pokemon, // e.g., "rayquaza"
  };
  let res = await request("https://graphqlpokemon.favware.tech/v8", document, variables);
  console.log(JSON.stringify(res)); // log the response

  return { species: res.getFuzzyPokemon[0].species };
};
```

After deploying the function with [these steps](/guides/function/sending-request), you can view the function execution logs using the SDK CLI.

## Viewing Function Logs

Use the `tailor function logs` command to view function execution logs:

```bash {{ title: 'List all function logs' }}
tailor function logs
```

```bash {{ title: 'View specific execution logs' }}
tailor function logs <execution-id>
```

Example output:

```sh {{ title: 'output' }}
Execution ID: abc123-def456-ghi789
Status: SUCCESS
Started: 2025-02-14T07:16:31Z
Finished: 2025-02-14T07:16:32Z

Logs:
2025-02-14T07:16:31.590771150Z INFO {"pokemon":"ay"}
2025-02-14T07:16:32.467262922Z INFO {"getFuzzyPokemon":[{"species":"rayquaza"}]}

Result:
{"species":"rayquaza"}
```

**Options:**

* `--json` / `-j`: Output as JSON
* `--workspace-id` / `-w`: Specify workspace ID
* `--profile` / `-p`: Use workspace profile

For more details, see the [Function CLI Reference](/sdk/cli/function)

---

---
url: https://docs.tailor.tech/guides/function/examples.md
---

# Examples

These examples show how to use the Function service to run JavaScript as serverless functions on the Tailor Platform, deploy them, and trigger them via resolvers.

Here are the code [examples](https://github.com/tailor-platform/templates/tree/main/examples).

We use TypeScript in the examples.

---

---
url: https://docs.tailor.tech/guides/function/managing-idp-users.md
---

# Managing Built-in IdP Users&#x20;

The Function service provides a built-in `tailor.idp` namespace that allows you to manage users in the Built-in IdP directly from your JavaScript functions. This enables programmatic user management operations such as creating, updating, deleting, and listing users without needing to make GraphQL calls.

## Overview

The `tailor.idp` namespace provides a `Client` class that you can use to interact with the Built-in IdP service. The client requires a namespace parameter that corresponds to your Built-in IdP service namespace.

:::tip
This feature requires a configured Built-in IdP service. For information on setting up Built-in IdP, see [Built-in IdP](/guides/auth/integration/built-in-idp).
:::

Importing from `@tailor-platform/sdk` no longer activates the ambient `tailor.*` global automatically. Add `import "@tailor-platform/sdk/runtime/globals"` as a side-effect import in your function file (or use the typed wrapper from `@tailor-platform/sdk/runtime` instead) — see [Runtime](/sdk/runtime) for details.

## Client Interface

The `tailor.idp.Client` class provides the following interface:

```ts
interface ClientConfig {
  namespace: string;
}

interface User {
  id: string;
  name: string;
  disabled: boolean;
  createdAt?: string;
  mfaEnrolled: boolean;
  mfaFactorIds: string[];
}

interface UserQuery {
  ids?: string[];
  names?: string[];
}

interface ListUsersOptions {
  first?: number;
  after?: string;
  query?: UserQuery;
}

interface ListUsersResponse {
  users: User[];
  nextPageToken: string | null;
  totalCount: number;
}

interface CreateUserInput {
  name: string;
  password?: string;
  disabled?: boolean;
}

interface UpdateUserInput {
  id: string;
  name?: string;
  password?: string;
  clearPassword?: boolean;
  disabled?: boolean;
}

interface SendPasswordResetEmailInput {
  userId: string;
  redirectUri: string;
  fromName?: string;
  subject?: string;
}

interface UnenrollMfaInput {
  userId: string;
  mfaFactorId: string;
}

class Client {
  constructor(config: ClientConfig);
  users(options?: ListUsersOptions): Promise<ListUsersResponse>;
  user(userId: string): Promise<User>;
  userByName(name: string): Promise<User>;
  createUser(input: CreateUserInput): Promise<User>;
  updateUser(input: UpdateUserInput): Promise<User>;
  deleteUser(userId: string): Promise<boolean>;
  sendPasswordResetEmail(input: SendPasswordResetEmailInput): Promise<boolean>;
  unenrollMfa(input: UnenrollMfaInput): Promise<boolean>;
}
```

## Creating a Client

To use the `tailor.idp` namespace, first create a client instance by specifying the namespace of your Built-in IdP service:

```js
const idpClient = new tailor.idp.Client({ namespace: "builtin-idp" });
```

## Client Methods

### List Users

The `users` method retrieves a list of users with optional pagination and filtering.

```js
export default async (args) => {
  const idpClient = new tailor.idp.Client({ namespace: args.namespaceName });

  // List first 10 users
  const result = await idpClient.users({
    first: 10,
  });

  return {
    users: result.users,
    totalCount: result.totalCount,
    hasNextPage: !!result.nextPageToken,
  };
};
```

You can also filter users by their IDs or names:

```js
export default async (args) => {
  const idpClient = new tailor.idp.Client({ namespace: args.namespaceName });

  // Filter users by names
  const result = await idpClient.users({
    query: {
      names: ["user1@example.com", "user2@example.com"],
    },
  });

  return {
    users: result.users,
    totalCount: result.totalCount,
  };
};
```

For pagination, use the `after` parameter with the `nextPageToken` from the previous response:

```js
export default async (args) => {
  const idpClient = new tailor.idp.Client({ namespace: args.namespaceName });

  // Get first page
  const firstPage = await idpClient.users({ first: 10 });

  // Get next page if available
  if (firstPage.nextPageToken) {
    const secondPage = await idpClient.users({
      first: 10,
      after: firstPage.nextPageToken,
    });
    return { users: secondPage.users };
  }

  return { users: firstPage.users };
};
```

### Get User

The `user` method retrieves a single user by their ID.

```js
export default async (args) => {
  const idpClient = new tailor.idp.Client({ namespace: args.namespaceName });

  const user = await idpClient.user(args.userId);

  return {
    id: user.id,
    name: user.name,
    disabled: user.disabled,
    createdAt: user.createdAt,
  };
};
```

### Get User by Name

The `userByName` method retrieves a single user by their name.

```js
export default async (args) => {
  const idpClient = new tailor.idp.Client({ namespace: args.namespaceName });

  const user = await idpClient.userByName(args.userName);

  return {
    id: user.id,
    name: user.name,
    disabled: user.disabled,
    createdAt: user.createdAt,
  };
};
```

### Create User

The `createUser` method creates a new user in the Built-in IdP. The `password` field is optional; if omitted, the user is created without a password and will not be able to log in until a password is set (e.g., via `sendPasswordResetEmail`).

```js
export default async (args) => {
  const idpClient = new tailor.idp.Client({ namespace: args.namespaceName });

  const newUser = await idpClient.createUser({
    name: args.email,
    password: args.password,
    disabled: false,
  });

  return {
    userId: newUser.id,
    userName: newUser.name,
  };
};
```

To create a user without a password:

```js
export default async (args) => {
  const idpClient = new tailor.idp.Client({ namespace: args.namespaceName });

  const newUser = await idpClient.createUser({
    name: args.email,
    disabled: false,
  });

  await idpClient.sendPasswordResetEmail({
    userId: newUser.id,
    redirectUri: "https://your-app.com/set-password",
  });

  return {
    userId: newUser.id,
    userName: newUser.name,
  };
};
```

### Update User

The `updateUser` method updates an existing user. You can update the user's name, password, disabled status, or clear the user's password using `clearPassword`.

:::warning
The `password` and `clearPassword` fields are mutually exclusive. Setting both at the same time will result in an error.
:::

```js
export default async (args) => {
  const idpClient = new tailor.idp.Client({ namespace: args.namespaceName });

  // Disable a user account
  const updatedUser = await idpClient.updateUser({
    id: args.userId,
    disabled: true,
  });

  return {
    userId: updatedUser.id,
    disabled: updatedUser.disabled,
  };
};
```

To clear a user's password (the user will not be able to log in until a new password is set):

```js
export default async (args) => {
  const idpClient = new tailor.idp.Client({ namespace: args.namespaceName });

  const updatedUser = await idpClient.updateUser({
    id: args.userId,
    clearPassword: true,
  });

  return {
    userId: updatedUser.id,
  };
};
```

### Delete User

The `deleteUser` method deletes a user by their ID.

```js
export default async (args) => {
  const idpClient = new tailor.idp.Client({ namespace: args.namespaceName });

  return idpClient.deleteUser(args.userId);
};
```

### Send Password Reset Email

The `sendPasswordResetEmail` method sends a password reset email to a user. This can be used for resetting existing users' passwords, setting initial passwords for users created without a password, or setting a new password after clearing a user's password with `clearPassword`.

```js
export default async (args) => {
  const idpClient = new tailor.idp.Client({ namespace: args.namespaceName });

  return idpClient.sendPasswordResetEmail({
    userId: args.userId,
    redirectUri: "https://your-app.com/reset-password-complete",
    fromName: "My App Support",
    subject: "Password Reset for Your My App Account",
  });
};
```

**Input fields:**

* `userId` (string, required) — The ID of the user to send the password reset email to.
* `redirectUri` (string, required) — The URL to redirect the user to after password reset. Must be a valid absolute URL with `http` or `https` scheme.
* `fromName` (string, optional) — Overrides the sender display name for this email. When omitted, falls back to the namespace-level `emailConfig.fromName`, then to `"Tailor Platform IdP"`.
* `subject` (string, optional) — Overrides the email subject line for this email. When omitted, falls back to the namespace-level `emailConfig.passwordResetSubject`, then to the localized default.

:::tip
Password reset emails are sent from `no-reply@idp.erp.dev`.
:::

### Unenroll MFA Factor

The `unenrollMfa` method removes a single MFA factor from a user, identified by `mfaFactorId`. The operation is subject to the namespace's `unenrollMfa` permission policy and additionally requires read access to the target user (the same `read` policy that governs `user` / `userByName`); a namespace that denies `read` will reject `unenrollMfa` as well.

To remove one specific factor:

```js
export default async (args) => {
  const idpClient = new tailor.idp.Client({ namespace: args.namespaceName });
  return idpClient.unenrollMfa({
    userId: args.userId,
    mfaFactorId: args.mfaFactorId,
  });
};
```

To reset a user's MFA entirely — for example when the user has lost their authenticator device and needs to re-enroll on a new one — iterate over every entry in `User.mfaFactorIds`:

```js
export default async (args) => {
  const idpClient = new tailor.idp.Client({ namespace: args.namespaceName });

  const user = await idpClient.user(args.userId);

  const results = await Promise.all(
    user.mfaFactorIds.map((mfaFactorId) => idpClient.unenrollMfa({ userId: user.id, mfaFactorId })),
  );

  const unenrolledFactorIds = user.mfaFactorIds.filter((_, index) => results[index]);

  return { unenrolledFactorIds };
};
```

**Input fields:**

* `userId` (string, required) — The ID of the user whose factor will be unenrolled.
* `mfaFactorId` (string, required) — The ID of the factor to unenroll. Factor IDs are returned on the user record as `mfaFactorIds`.

This method is available only when the IdP namespace has `enableMfa: true`. See [Multi-Factor Authentication (TOTP)](/guides/auth/integration/built-in-idp#multi-factor-authentication-totp) for the full configuration.

## Related Documentation

* [Built-in IdP](/guides/auth/integration/built-in-idp) - Learn how to configure the Built-in IdP service
* [Function Service Overview](/guides/function/overview) - Learn the basics of the Function service
* [Accessing TailorDB](/guides/function/accessing-tailordb) - Learn how to access TailorDB from functions

---

---
url: https://docs.tailor.tech/guides/function/sending-request.md
---

# Sending requests from Function service

The Function service allows you to send HTTP requests to third-party applications.
This enables you to integrate with external services and retrieve data from them.

**Currently, sending requests from the Function service to your application on the Tailor Platform is not supported.**
**You can only send requests to external services.**

The one exception is [AI Gateway](/guides/ai-gateway), which functions can call directly — and without an `Authorization` header, since the platform authenticates those requests as the identity the function runs as. See [Calling from a Function](/guides/ai-gateway#calling-from-a-function).

In this guide, we will show you how to send an HTTP request from the Function service using npm packages.

## 1. Write your function and bundle it for deployment

When you use npm packages in Function service, you need to bundle your function with the packages.
In this guide, we use `esbuild` to bundle your function with npm packages but any bundlers can be used.

Assuming you have a function like below:

```js {{ title: 'get_pokemon_function.js' }}
import { gql, request } from "graphql-request";

globalThis.main = async function (args) {
  const document = gql`
    query ExampleQuery($pokemon: String!) {
      getFuzzyPokemon(pokemon: $pokemon) {
        species
      }
    }
  `;

  const variables = {
    pokemon: args.pokemon, // e.g., "rayquaza"
  };
  let res = await request("https://graphqlpokemon.favware.tech/v8", document, variables);

  return { species: res.getFuzzyPokemon[0].species };
};
```

You need to bundle the function with a bundler.
In this case, we use `esbuild` to bundle the function.

```sh
esbuild get_pokemon_function.js --bundle --minify --outfile=dist/get_pokemon_function.js
```

**caveat**: You have to setup package.json and install the packages before bundling the function.

Once you bundle the function, you can deploy it to Tailor Platform.

## 2. Deploy your function

### Directory Structure

Here's the sample directory structure for an SDK project.
In this example, we place the bundled function code in the `functions` directory.

```sh {{ title: 'SDK directory structure' }}
.
├── tailor.config.ts
├── package.json
├── functions
│   └── get_pokemon_function.js
├── resolvers
│   └── get-pokemon.ts
└── tailordb
    └── ...
```

#### Resolver Example

With SDK, the schema definition is inferred from the input/output types.
Here's a sample SDK configuration for setting up a resolver that sends HTTP requests:

```typescript {{ title: 'get-pokemon.ts' }}
import { createResolver, t } from "@tailor-platform/sdk";
import { gql, request } from "graphql-request";

export default createResolver({
  name: "getPokemon",
  description: "sample query resolver",
  operation: "query",
  input: {
    pokemon: t.string(),
  },
  body: async (context) => {
    const document = gql`
      query ExampleQuery($pokemon: String!) {
        getFuzzyPokemon(pokemon: $pokemon) {
          species
        }
      }
    `;

    const variables = {
      pokemon: context.input.pokemon,
    };

    const res = await request("https://graphqlpokemon.favware.tech/v8", document, variables);

    return { species: res.getFuzzyPokemon[0].species };
  },
  output: t.object({
    species: t.string().nullable(),
  }),
});
```

#### Deployment

Let's deploy the function to Tailor Platform.

```sh
npx tailor deploy
```

Once the deployment is complete, you can send a request to the function.
Navigate to your application's GraphQL playground at:

```
https://{APP_NAME}-{WORKSPACE_HASH}.erp.dev/query
```

Then, you can run the query in the playground

```graphql
query {
  getPokemon(input: { pokemon: "ray" }) {
    species
  }
}
```

you'll get the response like below:

```json
{
  "data": {
    "getPokemon": {
      "species": "rayquaza"
    }
  }
}
```

---

---
url: https://docs.tailor.tech/guides/auth/overview.md
---

# Auth Service

The Auth service is a comprehensive authentication and authorization solution that enables secure user management and access control for your Tailor Platform applications. It provides seamless integration with external Identity Providers (IdPs) and manages user profiles, roles, and permissions within your application ecosystem.

## Key Capabilities

* **Single Sign-On (SSO) Integration**: Connect with external Identity Providers using industry-standard protocols (OIDC, SAML)
* **User Profile Management**: Store and manage user information with customizable attributes and roles
* **Access Control**: Control user access to resources based on roles and attributes
* **Machine User Support**: Create service accounts for automated processes and API access
* **Subgraph Integration**: Query user information directly through GraphQL when Auth is used as a subgraph
* **Auth Hooks**: Run custom logic during authentication flows. See [Auth Hooks](/guides/auth/hook)

## Quick Start with SDK

Configure Auth service using `defineAuth()`:

```typescript
import { defineAuth } from "@tailor-platform/sdk";
import { user } from "./tailordb/user";

const auth = defineAuth("my-auth", {
  userProfile: {
    type: user,
    usernameField: "email",
    attributes: { role: true },
  },
  machineUsers: {
    "admin-machine-user": {
      attributes: { role: "ADMIN" },
    },
  },
  oauth2Clients: {
    "my-oauth2-client": {
      redirectURIs: ["https://example.com/callback"],
      grantTypes: ["authorization_code", "refresh_token"],
    },
  },
  idProvider: idp.provider("my-provider", "my-client"),
});
```

### User Profile Configuration

Maps authenticated identities to a TailorDB type:

```typescript
// tailordb/user.ts
import { db } from "@tailor-platform/sdk";

export const user = db.table("User", {
  email: db.string().unique(), // usernameField must have unique constraint
  role: db.enum(["admin", "user"]),
  ...db.fields.timestamps(),
});
export type user = typeof user;
```

### Machine Users

Service accounts for automated access without user interaction:

```typescript
machineUsers: {
  "admin-machine-user": {
    attributes: { role: "ADMIN" },
  },
  "readonly-machine-user": {
    attributes: { role: "READER" },
  },
},
```

Get a machine user token using the CLI:

```bash
tailor machineuser token <name>
```

### OAuth 2.0 Clients

Configure OAuth 2.0 clients for third-party applications:

```typescript
oauth2Clients: {
  "my-oauth2-client": {
    redirectURIs: ["https://example.com/callback"],
    grantTypes: ["authorization_code", "refresh_token"],
    accessTokenLifetimeSeconds: 3600,    // 1 hour
    refreshTokenLifetimeSeconds: 604800, // 7 days
  },
},
```

## Supported Identity Providers

The Auth service supports integration with major Identity Providers:

These Identity Provider integrations are specifically for **user authentication** - enabling your end users to log into your application using their existing organizational credentials through Single Sign-On (SSO).

For step-by-step tutorials on setting up authentication, see [Setting up Auth](/tutorials/setup-auth/overview).

## Auth Hooks

The Auth service supports hooks that let you run custom Functions at specific points in the authentication flow. For example, the `beforeLogin` hook runs after IdP authentication succeeds but before identity resolution, enabling use cases like Just-In-Time user provisioning.

For configuration details and examples, see the [Auth Hooks guide](/guides/auth/hook).

## OAuth2 Connections for Functions

In addition to user authentication, the Auth service also provides [AuthConnection](/guides/auth/authconnection) for **application-to-application OAuth2 flows**. Unlike IdP integrations which authenticate users, AuthConnection enables your Functions to securely access external APIs (like Google APIs, Microsoft Graph, or QuickBooks) on behalf of your application. This is useful when your backend needs to integrate with external services that require OAuth2 authentication.

## Authentication

Auth service offers an authentication with SSO (Single Sign-On).\
Currently, OIDC (OpenID Connect), SAML (Security Assertion Markup Language), and ID Token protocols are supported.

### OIDC

In the Tailor Platform, when OIDC authentication is configured with an IdP, the following authorization flow is used to obtain an access token.

```mermaid
sequenceDiagram
  participant User
  participant Client
  participant PF AS TailorPF
  participant IdP AS IdP(OIDC)
  User->>+Client: Access protected resource
  Client-->>-User: Redirect to TailorPF's authorization endpoint
  User->>+PF: Authorization request to TailorPF
  rect rgba(0, 255, 255, .1)
    PF-->>-User: Redirect to IdP's authorization endpoint
    User->>+IdP: Authorization request to IdP
    IdP->>-User: Returns authentication screen
    User->>+IdP: Submits authentication information
    IdP-->>-User: Redirects to TailorPF's redirect URL
    User->>+PF: Authorization response from IdP
    PF->>+IdP: ID token request to IdP
    IdP->>-PF: ID token response from IdP
  end
  PF-->>-User: Redirect to Client's redirect URL
  User->>+Client: Authorization response from TailorPF
  Client->>+PF: Access token request to TailorPF
  PF->>-Client: Access token
  Client->>-User: Grant access to protected resource
```

Since the authentication flow with the IdP (the part enclosed in the blue square) is separated from the client,\
the client can execute the authorization flow with TailorPF without being aware of the IdP's existence.

Here is an example of an OIDC configuration with the SDK:

```typescript
import { defineAuth, idp, secrets } from "@tailor-platform/sdk";
import { user } from "./tailordb/user";

const auth = defineAuth("my-auth", {
  idProvider: idp.oidc("my-idp", {
    clientId: "<client-id>",
    clientSecret: secrets.value("default", "oidc-client-secret"),
    providerUrl: "<your_auth_provider_url>",
    // In the case of Auth0 "https://<your_tenant>.auth0.com"
  }),
  userProfile: {
    type: user,
    usernameField: "email",
    attributes: { roles: true },
  },
  machineUsers: {
    machine_user: {
      attributes: { roles: ["<role-uuid>"] },
    },
  },
});
```

| Property         | Description                                                          |
| ---------------- | -------------------------------------------------------------------- |
| **idProvider**   | An Identity Provider for SSO configured via `idp.oidc()`.            |
| - clientId       | A client ID for the identity provider **(required)**.                |
| - clientSecret   | A client secret. Managed via `secrets.value()` **(required)**.       |
| - providerUrl    | The URL of the identity provider you want to use **(required)**.     |
| **userProfile**  | Configuration for the user profile provider.                         |
| - type           | Reference to the TailorDB type for user profiles **(required)**.     |
| - usernameField  | Field to map username (e.g., `email`) **(required)**.                |
| - attributes     | Object mapping attribute fields to `true` (e.g., `{ roles: true }`). |
| **machineUsers** | Object mapping machine user names to their configurations.           |
| - attributes     | Object mapping attribute fields to values.                           |

Refer to the [Tailor Platform Provider documentation](https://registry.terraform.io/providers/tailor-platform/tailor/latest/docs/resources/auth_idp_config) for more details on IdP config properties.

### SAML

SAML is an XML-based open standard for exchanging authentication and authorization data between service provider (SP) and the identity provider (IdP).

**Service Provider Configuration**

When configuring SAML, Tailor Platform acts as the Service Provider (SP). Key SP configuration elements include:

* **EntityID**: Uniquely identifies your Tailor Platform application (format: `https://api.tailor.tech/saml/{workspace_id}/{auth_namespace}/metadata.xml`)
* **ACS URL**: The callback endpoint where SAML assertions are received (format: `https://{application_url}/oauth2/callback`)
* **Request Signing**: The platform provides a built-in key for signing SAML authentication requests. Enable via `enableSignRequest`.

For detailed steps on setting up the IdP with SAML, refer to the [tutorial](/tutorials/setup-auth/setup-identity-provider#2settingupidpforsaml).

**IdP-initiated flow**

The Tailor Platform does not support the SAML IdP-initiated flow, because SP-initiated flows provide stronger security guarantees. For applications that still need to start a flow from the IdP side, the platform provides a redirect mechanism: when a SAML assertion arrives without a `RelayState`, the platform redirects the user to the `defaultRedirectURL` configured on the IdP. Applications typically point this URL at their own login entry point, which then starts a normal SP-initiated flow.

Here is an example of a SAML configuration with the SDK:

```typescript
import { defineAuth, idp } from "@tailor-platform/sdk";
import { user } from "./tailordb/user";

const auth = defineAuth("my-auth", {
  idProvider: idp.saml("saml-local", {
    metadataUrl: "{METADATA_URL}",
    enableSignRequest: false,
    defaultRedirectURL: "https://your-app.example.com/login",
  }),
  userProfile: {
    type: user,
    usernameField: "email",
    attributes: { roles: true },
  },
  machineUsers: {
    machine_user: {
      attributes: { roles: ["<role-uuid>"] },
    },
  },
});
```

| Property             | Description                                                                                                                                            |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **idProvider**       | An Identity Provider for SSO configured via `idp.saml()`.                                                                                              |
| - metadataUrl        | Metadata URL of the identity provider.                                                                                                                 |
| - enableSignRequest  | Whether to enable signing of SAML authentication requests (optional, defaults to `false`). When enabled, the platform uses a built-in key for signing. |
| - defaultRedirectURL | URL the platform redirects to when a SAML assertion arrives without a `RelayState`.                                                                    |
| **userProfile**      | Configuration for the user profile provider.                                                                                                           |
| - type               | Reference to the TailorDB type for user profiles **(required)**.                                                                                       |
| - usernameField      | Field to map username (e.g., `email`) **(required)**.                                                                                                  |
| - attributes         | Object mapping attribute fields to `true` (e.g., `{ roles: true }`).                                                                                   |
| **machineUsers**     | Object mapping machine user names to their configurations.                                                                                             |
| - attributes         | Object mapping attribute fields to values.                                                                                                             |

### ID Token

ID Token authentication uses the JWT Bearer Grant Type flow ([RFC 7523](https://datatracker.ietf.org/doc/html/rfc7523)) to enable OAuth 2.0 clients to obtain access tokens by presenting a signed JWT to the authorization server. This method is particularly useful for server-to-server communication and scenarios where you already have an ID token from your identity provider.

```mermaid
sequenceDiagram
  participant Client
  participant PF AS TailorPF
  participant IdP AS IdP(ID Token)
  Client->>+IdP: Request ID token (direct authentication)
  IdP->>-Client: Returns ID token (JWT)
  Client->>+PF: Present ID token (JWT Bearer Grant)
  PF->>+IdP: Validate ID token
  IdP->>-PF: Token validation response
  PF->>-Client: Access token
  Client->>Client: Use access token for API calls
```

The ID Token flow allows clients to exchange a valid ID token (JWT) directly for an access token, bypassing the traditional OAuth authorization flow when the client already possesses valid credentials.

Here is an example of an ID Token configuration with the SDK:

```typescript
import { defineAuth, idp } from "@tailor-platform/sdk";
import { user } from "./tailordb/user";

const auth = defineAuth("my-auth", {
  idProvider: idp.idToken("my-idp", {
    clientId: "<client-id>",
    providerUrl: "<your_auth_provider_url>",
    // In the case of Auth0 "https://<your_tenant>.auth0.com"
  }),
  userProfile: {
    type: user,
    usernameField: "email",
    attributes: { roles: true },
  },
  machineUsers: {
    machine_user: {
      attributes: { roles: ["<role-uuid>"] },
    },
  },
});
```

| Property         | Description                                                          |
| ---------------- | -------------------------------------------------------------------- |
| **idProvider**   | An Identity Provider for SSO configured via `idp.idToken()`.         |
| - clientId       | A client ID for the identity provider **(required)**.                |
| - providerUrl    | The URL of the identity provider you want to use **(required)**.     |
| - issuerUrl      | The URL of the token issuer (optional).                              |
| - usernameClaim  | The claim that contains the username (optional).                     |
| **userProfile**  | Configuration for the user profile provider.                         |
| - type           | Reference to the TailorDB type for user profiles **(required)**.     |
| - usernameField  | Field to map username (e.g., `email`) **(required)**.                |
| - attributes     | Object mapping attribute fields to `true` (e.g., `{ roles: true }`). |
| **machineUsers** | Object mapping machine user names to their configurations.           |
| - attributes     | Object mapping attribute fields to values.                           |

## Machine user

A Machine user can manage users and application data, including creating, modifying, and deleting them.
To add a Machine user to the application, you must first define the user roles in the TailorDB, and then assign a specific role in the Auth service.

Here is an example of a Machine user configuration with the SDK:

```typescript
import { defineAuth, idp, secrets } from "@tailor-platform/sdk";
import { user } from "./tailordb/user";

const auth = defineAuth("my-auth", {
  idProvider: idp.oidc("my-idp", {
    // ... idp configuration
  }),
  userProfile: {
    type: user,
    usernameField: "email",
    attributes: { roles: true },
  },
  machineUsers: {
    machine_user: {
      attributes: { roles: ["<role-uuid>"] },
    },
  },
});
```

| Property         | Description                                                              |
| ---------------- | ------------------------------------------------------------------------ |
| **machineUsers** | Object mapping machine user names to their configurations.               |
| - attributes     | Object mapping attribute fields to values (e.g., `{ roles: ["uuid"] }`). |

After adding the Machine user, run the following command to get the access token.

```bash
tailor machineuser token {MACHINE_USER_NAME}
```

Once you get an access token, you can use it in the playground to run queries.

### Client credentials flow

You can use the machine user's credentials in the client application to authenticate and gain access to APIs without user interaction, using the client credentials flow.

Run the following command to view the machine user credentials.

```bash
tailor machineuser list
```

#### Request an Access Token

To initiate the flow, the client app needs to post its client credentials to the Tailor app token endpoint.

Here’s an example to make a POST request with the client credentials.

```bash
curl --request POST \
  --url 'https://{APP_DOMAIN}/oauth2/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data 'client_id={CLIENT_ID}' \
  --data 'client_secret={CLIENT_SECRET}'
```

## Auth as a Subgraph

When Auth service is configured as a subgraph in your application, you can query user information directly through GraphQL. This enables you to fetch user profiles, roles, and attributes alongside your application data in a single query.

### Querying User Information

Here are examples of how to query user data when Auth is used as a subgraph:

#### Basic User Query

```graphql
query GetCurrentUser {
  currentUser {
    id
    email
    name
    roles
    createdAt
    updatedAt
  }
}
```

#### User with Role Information

```graphql
query GetUserWithRoles($userId: ID!) {
  user(id: $userId) {
    id
    email
    name
    roles
    attributes
  }
}
```

#### List Users with Filtering

```graphql
query ListUsers($filter: UserFilter) {
  users(filter: $filter) {
    edges {
      node {
        id
        email
        name
        roles
        createdAt
      }
    }
    pageInfo {
      hasNextPage
      hasPreviousPage
    }
  }
}
```

### Schema Considerations

When using Auth as a subgraph, consider these schema requirements:

* **User Type**: Your TailorDB must include a User type that matches the Auth service configuration
* **Username Field**: Configure a field (typically `email`) that uniquely identifies users
* **Attribute Fields**: Define fields for storing user roles and attributes (must be UUID arrays)
* **Permissions**: Set appropriate type permissions to control access to user data

### Example User Schema

Here's an example of a User type configured for Auth integration:

```typescript {{title:'tailordb/user.ts'}}
import { db } from "@tailor-platform/sdk";

export const user = db
  .table("User", {
    name: db.string({
      description: "Name of the user",
      index: true,
      required: true,
    }),
    email: db.string({
      description: "Email of the user",
      required: true,
      unique: true,
    }),
    roles: db.uuid({ description: "Role IDs of the user", array: true }),
    ...db.fields.timestamps(),
  })
  .permission(permissionEveryone);
export type user = typeof user;
```

For more detailed examples and setup instructions, see the [Auth setup tutorial](/tutorials/setup-auth/overview).

```bash {{ title: "example response", id: "response-2" }}
{
    "access_token":"tpmu_oex61JfmZnSLoaOVayWzagDhQ7WR5tg3",
    "token_type":"Bearer",
    "expires_in":86400
}
```

You can now include this access token in the HTTP `Authorization` header to access protected resources.
To include the token in GraphQL Playground, navigate to the `Headers` tab and add the token to the `Authorization` header.

```json {{title:'json'}}
{
  "Authorization": "Bearer {ACCESS_TOKEN}"
}
```

---

---
url: https://docs.tailor.tech/guides/auth/app-login.md
---

# Log in to your app

Applications on the Tailor Platform use both authentication and authorization:

* Authentication: Handled by an external Identity Provider (Okta, Entra ID, Google Workspace) to verify user credentials.

* Authorization: Enforced by the Tailor Auth service, which maps the authenticated identity to a valid TailorDB user and applies permissions.

After integrating your Identity Provider (IdP) with the Auth service, a user must exist in both the IdP and the Tailor Platform to successfully log in. This guide explains the concepts for:

1. **User Profile Management**: How Tailor Platform connects authentication with TailorDB user profiles
2. **OAuth2 Client Configuration**: How Tailor Platform's auth service acts as a standalone authentication service
3. **Login Process**: Using OAuth2 flows with `tailor`

## Authentication Architecture

Tailor Platform's auth service acts as a **standalone authentication service** that abstracts away the complexity of your Identity Provider. Instead of your applications directly integrating with Auth0, Okta, or other IdPs, they authenticate against Tailor Platform's unified OAuth2 interface.

```mermaid
sequenceDiagram
  participant App as Your Application
  participant TP as Tailor Platform Auth
  participant IdP as Identity Provider (Auth0/Okta/etc)
  participant DB as TailorDB

  App->>TP: OAuth2 Authorization Request
  TP->>IdP: Redirect to IdP Login
  IdP->>TP: User Authentication
  TP->>DB: Lookup User Profile
  TP->>App: OAuth2 Access Token
  App->>TP: API Requests with Token
```

## Part 1: User Profile Management

### Connecting Auth with TailorDB

Tailor Platform uses a **User Profile Provider** to connect authentication identities with your application's user data stored in TailorDB. This connection is configured through the `tailor_auth_user_profile_config`:

```typescript
import { defineAuth } from "@tailor-platform/sdk";
import { user } from "./tailordb/types";

const auth = defineAuth("my-auth", {
  userProfile: {
    type: user,
    usernameField: "email",
    attributes: { roles: true },
  },
});
```

Properties

| Property        | Description                                       |
| --------------- | ------------------------------------------------- |
| userProfile     | The configuration for the TailorDB user profile   |
| - type          | The TailorDB type to use for user profiles.       |
| - usernameField | The field that contains the username.             |
| - attributes    | Map of attributes to include in the user profile. |

With this `attributes` configuration, the Auth service fetches the `roles` field from the `user` table and assigns its value to the roles attribute for permission checks.

This configuration tells Tailor Platform:

* **Where to find user data**: The TailorDB namespace and type
* **How to match users**: Using the email field as the username
* **What attributes to include**: User roles for authorization

&#x20;The `attribute_fields` configuration (which uses UUID arrays) is for the deprecated legacy permissions system, while `attribute_map` is used for the newer Permission/GQLPermission system.
Both can coexist in the same configuration, but it's recommended to migrate to the new Permission system.

For more details on managing permissions, see the [Permission Guide](/guides/tailordb/permission).

### Creating Users in Your Application

Follow the [Create Users Tutorial](/tutorials/setup-auth/login/create-user) for a step-by-step guide.

## Part 2: OAuth2 Client Configuration

### Understanding OAuth2 in Tailor Platform

Tailor Platform's auth service acts as an **OAuth2 Authorization Server** that sits between your applications and your Identity Provider. This means:

* **Your applications** authenticate against Tailor Platform's OAuth2 endpoints
* **Tailor Platform** handles the complexity of integrating with your specific IdP (Auth0, Okta, etc.)
* **Users** experience a seamless login flow regardless of the underlying IdP

This architecture allows you to:

* Use standard OAuth2 flows in your applications
* Switch Identity Providers without changing application code
* Leverage Tailor Platform's user profile management and authorization

### Configuring OAuth2 Clients

OAuth2 clients represent your applications that need to authenticate users. Each client has specific configuration for security and callback handling:

```typescript
import { defineAuth } from "@tailor-platform/sdk";
import { user } from "./tailordb/types";

const auth = defineAuth("my-auth", {
  userProfile: {
    type: user,
    usernameField: "email",
    attributes: { roles: true },
  },
  oauth2Clients: {
    // Confidential client for server-side applications
    "server-app": {
      redirectURIs: ["https://myapp.example.com/auth/callback"],
      grantTypes: ["authorization_code", "refresh_token"],
    },
    // Public client for mobile applications
    "mobile-app": {
      clientType: "public",
      redirectURIs: ["com.myapp://auth/callback"],
      grantTypes: ["authorization_code", "refresh_token"],
    },
    // Browser client for Single Page Applications
    "spa-app": {
      clientType: "browser",
      redirectURIs: [
        "https://myapp.example.com/auth/callback",
        "http://localhost:3000/auth/callback",
      ],
      grantTypes: ["authorization_code", "refresh_token"],
    },
  },
});
```

### OAuth2 Client Properties

| Property                       | Description                                                                       | Security Considerations                            |
| ------------------------------ | --------------------------------------------------------------------------------- | -------------------------------------------------- |
| `Name`/`name`                  | Unique identifier for the OAuth2 client                                           | Use descriptive names for easier management        |
| `ClientType`/`client_type`     | `confidential` for server-side apps, `public` for mobile apps, `browser` for SPAs | Browser clients provide enhanced security for SPAs |
| `GrantTypes`/`grant_types`     | Supported OAuth2 flows: `authorization_code`, `refresh_token`                     | Authorization code is most secure for web apps     |
| `RedirectURIs`/`redirect_uris` | Valid callback URLs after authentication                                          | Must match exactly; wildcards not supported        |

### Choosing the Right Client Type

**Use `confidential` client type when:**

* Building server-side applications (Node.js, Python, Java, etc.)
* Your application can securely store client secrets
* The OAuth flow happens on the server side

**Use `public` client type when:**

* Building mobile applications (iOS, Android)
* Your application cannot securely store secrets but doesn't run in a browser

**Use `browser` client type when:**

* Building Single Page Applications (SPAs) with React, Vue, Angular, etc.
* Your application runs entirely in the browser

#### Browser Client Security

Browser clients provide enhanced security for SPAs through multiple mechanisms:

* **Authorization flow**: The authorization flow between the browser client and the authentication service is the same as for public clients, but the access token and refresh token are issued as HTTP-only cookies rather than in the response body
* **CSRF protection**: Requires a custom `X-Tailor-Nonce` header to defend against CSRF attacks

**Safari Limitation**: Browser clients may fail authentication in Safari due to its Intelligent Tracking Prevention (ITP) feature. ITP blocks cross-site cookies, which prevents the HTTP-only cookies used by browser clients from being stored or sent. If your application needs to support Safari, consider using a `confidential` client type with server-side token handling instead.

## Part 3: Login Process

### Using `tailor` for Testing

The `tailor` command provides a convenient way to test your OAuth2 configuration:

```bash
tailor login
```

**What happens during this flow:**

1. **OAuth2 Authorization**: `tailor` initiates the OAuth2 authorization code flow
2. **IdP Redirect**: Your browser opens to Tailor Platform's auth service, which redirects to your configured IdP
3. **User Authentication**: You authenticate with your IdP (Auth0, Okta, etc.)
4. **Profile Lookup**: Tailor Platform looks up your user profile in TailorDB using the email from your IdP
5. **Token Issuance**: An access token is issued with your user's roles and permissions
6. **API Access**: The token can be used to access your application's GraphQL API

## Troubleshooting

**User not found after authentication**

* Ensure the user exists in TailorDB with the correct email address
* Verify the email matches exactly between IdP and TailorDB
* Check that `UserProfileProviderConfig` is correctly configured

**OAuth2 client errors**

* Verify redirect URIs match your application URLs exactly
* Ensure client credentials are correctly configured
* Confirm grant types include `authorization_code`
* Check that the client type matches your application architecture

**Permission denied**

* Confirm user has appropriate roles assigned in TailorDB
* Verify TailorDB type permissions for the User model
* Check that machine user has admin privileges for user creation
* Ensure `AttributesFields`/`attribute_map` includes the roles field in your auth configuration

**Role assignment issues**

* For UUID-based roles: Verify role UUIDs exist in your roles table
* For string-based roles: Ensure role strings match exactly (case-sensitive)
* Check that roles are properly seeded in your database

## Next Steps

* **For specific IdP setup**: See [Auth0](/guides/auth/integration/auth0), [Okta](/guides/auth/integration/okta), [Microsoft Entra ID](/guides/auth/integration/entra-id), or [Google Workspace](/guides/auth/integration/google-workspace)
* **For authentication using ID tokens**: See [ID Token authentication](/tutorials/setup-auth/login/id-token)
* **For user management**: Explore [creating users](/tutorials/setup-auth/login/create-user) and [OAuth2 clients](/tutorials/setup-auth/login/create-oauth2-client)

---

---
url: https://docs.tailor.tech/guides/auth/authconnection.md
---

# AuthConnection

AuthConnection enables OAuth2 authentication connections with external providers, featuring server-side secret management and seamless Function runtime integration. Unlike traditional auth integrations focused on user authentication, AuthConnection is designed for application-to-application OAuth2 flows where your functions need to access external APIs on behalf of your application.

## Overview

AuthConnection provides a secure way to:

* Manage OAuth2 connections with external providers (Google, Microsoft 365, QuickBooks)
* Store client secrets server-side eliminating client-side secret exposure
* Access tokens from Functions
* Handle token refresh automatically for long-running integrations

## Prerequisites

* A Tailor Platform workspace with Auth service enabled
* OAuth2 application configured with your chosen provider
* Basic understanding of OAuth2 flows
* Function service enabled (for runtime integration)
* An SDK project with a `tailor.config.ts` — see the [SDK Quickstart](/sdk/quickstart)

## Setup Flow

An auth connection can be managed two ways: through your **SDK config** (`defineAuth()` in `tailor.config.ts`, deployed with the rest of your app) or entirely through the **Console**. Either way, setting up a connection is two steps:

1. **Create** the connection (registers the OAuth2 provider credentials)
2. **Authorize** the connection (runs the OAuth2 flow to obtain and store tokens)

A given connection can only be managed by one side at a time — see [Choosing a Management Method](#choosing-a-management-method) below.

### Option A: Manage via SDK Config

#### 1. Configure the Connection

Add a `connections` block to `defineAuth()` in `tailor.config.ts`:

```typescript
import { defineAuth } from "@tailor-platform/sdk";

export const auth = defineAuth("my-auth", {
  // ...other auth config
  connections: {
    "google-connection": {
      type: "oauth2",
      providerUrl: "https://accounts.google.com",
      issuerUrl: "https://accounts.google.com",
      clientId: process.env.GOOGLE_CLIENT_ID!,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
    },
  },
});
```

Store the client ID and secret in your `.env` file or CI secrets — never commit them.

**Connection config fields:**

| Field          | Type     | Required | Description                                 |
| -------------- | -------- | -------- | ------------------------------------------- |
| `type`         | `string` | Yes      | Connection type. Currently only `"oauth2"`. |
| `providerUrl`  | `string` | Yes      | OAuth2 provider URL.                        |
| `issuerUrl`    | `string` | Yes      | Token issuer URL for JWT validation.        |
| `clientId`     | `string` | Yes      | OAuth2 client ID from the provider.         |
| `clientSecret` | `string` | Yes      | OAuth2 client secret from the provider.     |
| `authUrl`      | `string` | No       | Override for the authorization endpoint.    |
| `tokenUrl`     | `string` | No       | Override for the token endpoint.            |

Deploy to register the connection with the platform:

```bash
tailor deploy
```

This creates (or updates) the connection record. A newly created connection exists but is not yet authorized — it has no tokens yet.

> \[!NOTE]
> Deploy updates existing connections **in-place**, preserving the OAuth token. If a change requires re-authorization (for example, the provider URL or client ID changed), the deploy will warn you to run `authconnection authorize` again.

> \[!TIP]
> Once a connection has been deployed at least once, later deploys can pass `clientSecret: ""` (an empty string) without erasing the secret already stored on the platform — an empty value is simply left out of the update, so nothing about the secret changes. This lets a CI pipeline redeploy an existing connection (for example, to pick up a `providerUrl` change) without ever having access to the real secret. The very first deploy that creates the connection still needs the real secret at least once, from wherever that value is available.
>
> `clientSecret` is a required field, so it must resolve to an actual string — `undefined` fails config validation before deploy even runs. Use a fallback so an unset variable still resolves to a string:
>
> ```typescript
> clientSecret: process.env.GOOGLE_CLIENT_SECRET ?? "", // Falls back to "" when the var is unset, e.g. in CI
> ```
>
> With the `.env` file itself, an explicit empty assignment (`GOOGLE_CLIENT_SECRET=`) also works, since that sets the variable to `""` rather than leaving it unset.

#### 2. Authorize the Connection

```bash
tailor authconnection authorize --name google-connection \
  --scopes "openid,profile,email" \
  --port 8080
```

**Parameters:**

* `--name` (required): Name of the connection defined in `defineAuth()`
* `--scopes` (optional): OAuth2 scopes to request (default: `openid,profile,email`)
* `--port` (optional): Local callback server port (default: `8080`)
* `--no-browser` (optional): Don't open browser automatically

This command:

1. Starts a local HTTP server for the OAuth2 callback
2. Opens your browser to the provider's authorization page
3. Handles the callback after authorization
4. Exchanges the authorization code for tokens using the client secret from your config
5. Stores tokens securely on the server

Alternatively, run `tailor authconnection open` to authorize the connection from the Console instead of the local CLI flow — useful on a machine without browser access:

```bash
tailor authconnection open
```

Verify the connection is authorized:

```bash
tailor authconnection list
```

### Option B: Manage Entirely via the Console

No `tailor.config.ts` changes are needed — create, authorize, and manage the connection directly in the Tailor Platform Console:

```bash
tailor authconnection open
```

This opens the workspace's connections settings page, where you can:

1. **Create** a new connection — enter the type, provider URL, issuer URL, client ID, and client secret directly in the Console form
2. **Authorize** it — the Console walks you through the OAuth2 consent flow in the browser
3. View its status, re-authorize, revoke its tokens, or delete it later from the same page

This is a good fit for connections you don't want tracked in git — for example, ones that differ per developer, or that only ever target a single shared workspace and don't need to travel with the rest of your app's config.

### Choosing a Management Method

A connection name is owned by exactly one side at a time — the same connection cannot be managed by both the Console and your SDK config simultaneously:

* A connection created via the Console (Option B) carries no SDK ownership label. `tailor deploy` leaves it completely untouched as long as it isn't also declared in `connections`.
* If you later add a connection with the **same name** to `defineAuth()`'s `connections` and run `deploy`, the SDK finds it already exists without an ownership label and pauses to ask whether it should take it over ("Allow tailor to manage these resources?"). Confirming adopts it into config management — from that point on, every `deploy` overwrites its fields to match your config, and removing it from `connections` deletes the connection. (`--yes` confirms automatically, which is useful for CI but means this adoption happens without a prompt.)
* Until you confirm that handover, `deploy` refuses to proceed, so a Console-managed connection is never silently overwritten by config just because a connection with the same name appears in `tailor.config.ts`.

In short: use the Console (Option B) for connections you intend to manage by hand, and SDK config (Option A) for connections you want defined, reviewed, and deployed alongside the rest of your app. Don't mix the two for the same connection name.

## Provider Configuration Examples

### Google OAuth2

First, create OAuth2 credentials in [Google Cloud Console](https://console.cloud.google.com/):

1. Go to "APIs & Services" > "Credentials"
2. Create OAuth 2.0 Client ID
3. Configure authorized redirect URIs

```typescript
connections: {
  "google-oauth": {
    type: "oauth2",
    providerUrl: "https://accounts.google.com",
    issuerUrl: "https://accounts.google.com",
    clientId: process.env.GOOGLE_CLIENT_ID!,
    clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
  },
},
```

```bash
# 1. Deploy the connection
tailor deploy

# 2. Authorize and get tokens
tailor authconnection authorize --name google-oauth \
  --scopes "https://www.googleapis.com/auth/admin.directory.user.readonly"
```

**Common Google OAuth2 URLs:**

* Authorization endpoint: `https://accounts.google.com/o/oauth2/v2/auth`
* Token endpoint: `https://oauth2.googleapis.com/token`
* User info endpoint: `https://www.googleapis.com/oauth2/v2/userinfo`

### Microsoft 365 / Azure AD

First, register an application in [Azure Portal](https://portal.azure.com/):

1. Go to "Azure Active Directory" > "App registrations"
2. Create new registration
3. Configure redirect URIs under "Authentication"
4. Create client secret under "Certificates & secrets"

```typescript
connections: {
  "ms365-oauth": {
    type: "oauth2",
    providerUrl: "https://login.microsoftonline.com/YOUR_TENANT_ID",
    issuerUrl: "https://login.microsoftonline.com/YOUR_TENANT_ID/v2.0",
    clientId: process.env.AZURE_CLIENT_ID!,
    clientSecret: process.env.AZURE_CLIENT_SECRET!,
  },
},
```

```bash
# 1. Deploy the connection
tailor deploy

# 2. Authorize and get tokens
tailor authconnection authorize --name ms365-oauth \
  --scopes "https://graph.microsoft.com/.default"
```

Replace `YOUR_TENANT_ID` with your Azure AD tenant ID or use `common` for multi-tenant applications.

**Common Microsoft OAuth2 URLs:**

* Authorization endpoint: `https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize`
* Token endpoint: `https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token`
* User info endpoint: `https://graph.microsoft.com/v1.0/me`

### QuickBooks OAuth2

First, create an app in [Intuit Developer Portal](https://developer.intuit.com/):

1. Create a new app
2. Select OAuth 2.0 for authorization
3. Configure redirect URIs
4. Get your client ID and secret from "Keys & OAuth"

```typescript
connections: {
  "quickbooks-oauth": {
    type: "oauth2",
    providerUrl: "https://appcenter.intuit.com/connect/oauth2",
    issuerUrl: "https://oauth.platform.intuit.com/op/v1",
    clientId: process.env.QUICKBOOKS_CLIENT_ID!,
    clientSecret: process.env.QUICKBOOKS_CLIENT_SECRET!,
  },
},
```

```bash
tailor deploy
```

**Common QuickBooks OAuth2 URLs:**

* Authorization endpoint: `https://appcenter.intuit.com/connect/oauth2`
* Token endpoint: `https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer`
* User info endpoint: `https://accounts.platform.intuit.com/v1/openid_connect/userinfo`

**QuickBooks Scopes:**

* `com.intuit.quickbooks.accounting` - QuickBooks Online API
* `com.intuit.quickbooks.payment` - Payments API
* `openid` - OpenID Connect
* `profile` - User profile information
* `email` - User email address

## Function Runtime Integration

AuthConnection integrates seamlessly with the Function service, allowing your functions to access OAuth2 tokens and call external APIs.

### Basic Usage

Use `authconnection.getConnectionToken()` from `@tailor-platform/sdk/runtime` to retrieve the current access token by connection name. When `connections` is defined in `defineAuth()`, the connection name is type-checked and autocompleted against the defined keys:

```typescript
import { authconnection } from "@tailor-platform/sdk/runtime";

export default async () => {
  // Get access token for a connection
  const tokens = await authconnection.getConnectionToken("google-oauth");

  // Use the access token to call external APIs
  const response = await fetch("https://www.googleapis.com/oauth2/v2/userinfo", {
    headers: {
      Authorization: `Bearer ${tokens.access_token}`,
    },
  });

  if (!response.ok) {
    throw new Error(`Failed to fetch user info: ${response.statusText}`);
  }

  const userInfo = await response.json();
  return userInfo;
};
```

```typescript
// authconnection.getConnectionToken("unknown-connection"); // ❌ TypeScript error
```

Type narrowing is provided by the generated `tailor.d.ts` (the `ConnectionNameRegistry` interface). Run `tailor generate` (or `deploy`) after defining new connections to refresh it. Before the first generate, or when `connections` is not defined in `defineAuth()`, `getConnectionToken()` accepts any string.

### Advanced Usage with Error Handling

```typescript
import { authconnection } from "@tailor-platform/sdk/runtime";

export default async () => {
  try {
    // Get tokens for multiple connections
    const googleTokens = await authconnection.getConnectionToken("google-oauth");
    const msTokens = await authconnection.getConnectionToken("ms365-oauth");

    // Call Google API
    const googleResponse = await fetch("https://www.googleapis.com/oauth2/v2/userinfo", {
      headers: {
        Authorization: `Bearer ${googleTokens.access_token}`,
      },
    });

    // Call Microsoft Graph API
    const msResponse = await fetch("https://graph.microsoft.com/v1.0/me", {
      headers: {
        Authorization: `Bearer ${msTokens.access_token}`,
      },
    });

    const [googleData, msData] = await Promise.all([googleResponse.json(), msResponse.json()]);

    return {
      google: googleData,
      microsoft: msData,
    };
  } catch (error) {
    console.error("Failed to fetch user data:", error);
    throw error;
  }
};
```

### Token Properties

The `getConnectionToken()` method returns an object with the following property:

## Managing Connections via CLI

These commands work on any connection regardless of which option created it:

```bash
# Open the connections page in the Console
tailor authconnection open

# Authorize (opens browser for OAuth2 flow)
tailor authconnection authorize --name <connection-name>

# List all connections
tailor authconnection list

# Revoke a connection's tokens (keeps the connection; re-authorize later)
tailor authconnection revoke --name <connection-name>

# Delete a connection entirely
tailor authconnection delete --name <connection-name>
```

To delete a connection managed via SDK config (Option A), remove it from `connections` and redeploy instead of using `authconnection delete` directly — manage each connection through one method only, as described above.

For connections not defined in `defineAuth()`'s `connections`, `authconnection.getConnectionToken()` still accepts any string, so you can read tokens for Console-managed connections the same way — you just lose the type-checked autocompletion.

## Best Practices

### Security Considerations

1. **Client Secrets**: Treat OAuth2 client secrets as passwords. Rotate them regularly.
2. **HTTPS Only**: Always use HTTPS for redirect URIs in production.
3. **Scope Management**: Configure minimal required scopes for your application needs.
4. **Token Handling**: Never log or expose access tokens in your Function code.

### Naming Conventions

Use descriptive names that indicate the provider and environment:

* `google-oauth-prod`
* `ms365-oauth-dev`
* `quickbooks-oauth-staging`

### Environment-Specific Configurations

Since each environment is deployed to its own workspace from the same `tailor.config.ts`, keep a single connection definition and vary the value via a per-environment `.env` file — the same pattern used for any other environment-specific value (see [Multi-Environment Configuration](/sdk/multi-environment)):

```typescript
connections: {
  "google-oauth": {
    type: "oauth2",
    providerUrl: "https://accounts.google.com",
    issuerUrl: "https://accounts.google.com",
    clientId: process.env.GOOGLE_CLIENT_ID!,
    clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
  },
},
```

```bash
tailor deploy -w <production-workspace-id> --env-file .env.production
```

## Troubleshooting

### Common Issues

**Invalid Client Error**

* Verify client ID and secret are correct
* Check if the OAuth2 app is enabled/active in the provider's console

**Redirect URI Mismatch**

* Ensure the redirect URI configured in your provider matches exactly with your application

**Scope Errors**

* Verify requested scopes are enabled in your OAuth2 application
* Some providers require admin consent for certain scopes

**Token Expiration**

* Implement refresh token flow in your application
* Monitor token expiration times

**Re-authorization Required After Deploy**

* If `tailor deploy` warns that a connection needs re-authorization, run `tailor authconnection authorize --name <connection-name>` again
* This happens when identity-changing fields (`providerUrl`, `issuerUrl`, `clientId`, `type`) are modified

**Function Runtime Errors**

* Ensure the connection name exists and is authorized
* Check that the connection has valid, non-expired tokens
* Verify network connectivity to external APIs

## Next Steps

* [Setting up Auth Connections tutorial](/tutorials/setup-auth/setup-auth-connections) - Step-by-step SDK walkthrough
* [Auth Service SDK reference](/sdk/services/auth#auth-connections) - Full auth connections API reference
* [Runtime API](/sdk/runtime#namespaces) - `@tailor-platform/sdk/runtime` namespaces, including `authconnection`
* [Learn about Function service](/guides/function/overview) - Understand Function runtime capabilities
* [Secret Manager documentation](/guides/secretmanager) - Secure secret storage patterns
* [Auth service overview](/guides/auth/overview) - Complete authentication system
* [Function examples](/guides/function/examples) - More Function integration patterns

## Additional Resources

* [OAuth 2.0 RFC](https://tools.ietf.org/html/rfc6749)
* [OpenID Connect Specification](https://openid.net/specs/openid-connect-core-1_0.html)
* [Google Identity Platform](https://developers.google.com/identity)
* [Microsoft Identity Platform](https://docs.microsoft.com/en-us/azure/active-directory/develop/)
* [Intuit OAuth 2.0](https://developer.intuit.com/app/developer/qbo/docs/develop/authentication-and-authorization/oauth-2.0)

---

---
url: https://docs.tailor.tech/guides/auth/hook.md
---

# Auth Hooks

Auth Hooks allow you to run custom logic during authentication flows. By registering hook handlers, you can execute Functions at specific points in the login process — for example, to perform Just-In-Time (JIT) user provisioning or validate claims before a user is granted access.

Currently, the following hook is supported:

* **beforeLogin**: Runs after IdP authentication succeeds but before identity resolution

## Before Login Hook

The `beforeLogin` hook is invoked after the Identity Provider authenticates a user but before the Auth service resolves the user's identity. This gives you the opportunity to inspect the IdP claims and take action — such as creating a user record if one doesn't exist yet.

### Use Cases

* **JIT User Provisioning**: Automatically create user records in TailorDB when a user logs in for the first time
* **Claim Validation**: Verify that the authenticated user meets specific criteria before allowing login

## Execution Flow

```mermaid
sequenceDiagram
  participant User
  participant IdP as Identity Provider
  participant Auth as Auth Service
  participant Hook as Hook Function
  participant DB as TailorDB

  User->>+IdP: Authenticate
  IdP->>-Auth: Authentication success (claims)
  Auth->>+Hook: beforeLogin({ claims, idpConfigName, env })
  Hook->>DB: Custom logic (e.g., create user)
  DB->>Hook: Result
  Hook->>-Auth: Success / Error
  alt Hook succeeds
    Auth->>Auth: Resolve identity
    Auth->>User: Login success
  else Hook throws error
    Auth->>User: 403 Forbidden
  end
```

## Configuration

Configure the `beforeLogin` hook in `defineAuth` using the `hooks` property:

```typescript
import { defineAuth, idp, secrets } from "@tailor-platform/sdk";
import { user } from "./tailordb/user";

const auth = defineAuth("my-auth", {
  idProvider: idp.oidc("my-idp", {
    clientId: "<client-id>",
    clientSecret: secrets.value("default", "oidc-client-secret"),
    providerUrl: "<your_auth_provider_url>",
  }),
  userProfile: {
    type: user,
    usernameField: "email",
    attributes: { roles: true },
  },
  machineUsers: {
    "hook-invoker": {
      attributes: { role: "ADMIN" },
    },
  },
  hooks: {
    beforeLogin: {
      handler: async ({ claims, idpConfigName }) => {
        // Your custom logic here
      },
      invoker: "hook-invoker",
    },
  },
});
```

| Property              | Description                                                                                            |
| --------------------- | ------------------------------------------------------------------------------------------------------ |
| **hooks**             | Object containing hook configurations.                                                                 |
| **hooks.beforeLogin** | Configuration for the before-login hook.                                                               |
| - handler             | Reference to the Function that handles the hook **(required)**.                                        |
| - invoker             | Name of the machine user used to invoke the handler **(required)**. Must be defined in `machineUsers`. |

The `invoker` machine user is used by the Auth service to call the handler Function. Ensure this machine user has sufficient permissions to perform the operations needed inside the handler (e.g., creating user records in TailorDB).

## Handler Arguments

The hook handler receives the following arguments:

| Argument          | Type   | Description                                                                                                                                                           |
| ----------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **claims**        | object | The claims returned by the Identity Provider (e.g., email, name). For Built-in IdP federated logins, also carries [`federated_identity`](#federated-identity-claims). |
| **idpConfigName** | string | The name of the IdP configuration that authenticated the user.                                                                                                        |
| **env**           | object | Environment variables defined in `defineConfig({ env })` (the same values available via `context.env` in resolvers).                                                  |

## Federated Identity Claims

When a user signs in through a [Built-in IdP](/guides/auth/integration/built-in-idp) OAuth provider (Google or Microsoft), the upstream provider's profile is forwarded to the hook on `claims.federated_identity`. A common use is to populate the user record from the provider's profile during [JIT provisioning](#example-jit-user-provisioning).

`claims.federated_identity` is `undefined` for any non-federated login (for example, password logins or external IdP flows), so guard before reading it.

| Field        | Type                      | Description                                                                                                                                                                                            |
| ------------ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **provider** | `"google" \| "microsoft"` | The upstream OAuth provider that federated the login.                                                                                                                                                  |
| **claims**   | object                    | Profile claims from the provider's ID token. Commonly present claims (`name`, `given_name`, `family_name`, `picture`, `locale`) are available; any other claim the provider issues is forwarded as-is. |

Claim 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",
  },
}
```

:::tip
`claims.federated_identity` is a login-flow signal available only inside the `beforeLogin` hook. It is not part of the app-facing session token. Persist whatever your app needs into your own TailorDB type during the hook.
:::

## Example: JIT User Provisioning

The following example configures a `beforeLogin` hook inline in `defineAuth` that creates a user record in TailorDB when a user logs in for the first time:

```typescript
import { defineAuth, idp, secrets } from "@tailor-platform/sdk";
import { user } from "./tailordb/user";

const auth = defineAuth("my-auth", {
  idProvider: idp.oidc("my-idp", {
    clientId: "<client-id>",
    clientSecret: secrets.value("default", "oidc-client-secret"),
    providerUrl: "<your_auth_provider_url>",
  }),
  userProfile: {
    type: user,
    usernameField: "email",
    attributes: { roles: true },
  },
  machineUsers: {
    "hook-invoker": {
      attributes: { role: "ADMIN" },
    },
  },
  hooks: {
    beforeLogin: {
      handler: async ({ claims, idpConfigName }) => {
        const claimName = claims.name;
        if (!claimName) {
          throw new Error("name claim is required");
        }

        // JIT provisioning: create user record in TailorDB if not exists
        const client = new tailordb.Client({ namespace: "my-db" });
        await client.connect();
        await client.queryObject(
          `INSERT INTO User (email, name, role)
           VALUES ($1, $2, 'USER')
           ON CONFLICT (email) DO NOTHING`,
          [claimName, claimName],
        );
        await client.end();
      },
      invoker: "hook-invoker",
    },
  },
});
```

## Error Handling

| Scenario                     | Behavior                                                      |
| ---------------------------- | ------------------------------------------------------------- |
| Handler returns successfully | Login continues with normal identity resolution.              |
| Handler throws an error      | Login is aborted with a **403 Forbidden** response.           |
| No hook configured           | Hook is skipped; login proceeds normally.                     |
| Infrastructure failure       | Login is aborted with a **503 Service Unavailable** response. |

## Next Steps

* [Auth Service Overview](/guides/auth/overview) — Learn about the full Auth service capabilities
* [Functions Guide](/guides/function/overview) — Learn how to write and deploy Functions
* [Setting up Auth](/tutorials/setup-auth/overview) — Step-by-step tutorial for configuring authentication

---

---
url: https://docs.tailor.tech/guides/auth/scim.md
---

# SCIM Provisioning

SCIM (System for Cross-domain Identity Management) is an open standard that enables automatic user provisioning between your Identity Provider (IdP) and your Tailor Platform application. When configured, SCIM allows your IdP to automatically create, update, and deactivate user accounts in your application, eliminating the need for manual user management.

## What is SCIM?

SCIM provides a standardized way for identity providers like Okta, Microsoft Entra ID, and others to communicate user lifecycle events to your application. This includes creating new users when they join your organization, updating user information when it changes, and deactivating accounts when users leave.

The Tailor Platform implements SCIM 2.0, which uses a RESTful API with JSON payloads to manage user resources. When your IdP provisions a user, the SCIM endpoint receives the user data and automatically creates or updates the corresponding record in your TailorDB.

```mermaid
sequenceDiagram
  participant IdP as Identity Provider
  participant SCIM as Tailor SCIM Endpoint
  participant TailorDB as TailorDB
  IdP->>+SCIM: POST /scim/Users (Create User)
  SCIM->>+TailorDB: Create User Record
  TailorDB->>-SCIM: User Created
  SCIM->>-IdP: 201 Created
  Note over IdP,TailorDB: User attributes are mapped to TailorDB fields
```

## Configuration Overview

Setting up SCIM provisioning requires three main components:

1. **Machine User**: A service account that performs provisioning operations on behalf of the IdP
2. **SCIM Configuration**: Defines the authentication method for SCIM requests
3. **Resource Mapping**: Maps SCIM schema attributes to your TailorDB fields

## Machine User Configuration

SCIM provisioning requires a dedicated machine user with appropriate permissions to create, update, and delete user records in your TailorDB. This machine user acts as the service account that executes all provisioning operations.

**SDK Configuration:**

```typescript
import { defineAuth } from "@tailor-platform/sdk";
import { user } from "./tailordb/user";

export const authConfig = defineAuth("my-auth", {
  userProfile: {
    type: user,
    usernameField: "email",
    attributes: {
      attrs: true,
    },
  },
  machineUsers: {
    "scim-user": {
      attributes: {
        attrs: ["admin"],
      },
    },
  },
  scim: {
    machineUserName: "scim-user",
    authorization: {
      type: "oauth2",
    },
    resources: [
      // Resource definitions (see below)
    ],
  },
});
```

The machine user should have sufficient permissions to perform CRUD operations on the TailorDB types that will store provisioned users. Typically, this means assigning an admin role or creating a specific role with the necessary permissions.

## Authentication Methods

The SCIM endpoint supports two authentication methods:

### OAuth2 Authentication

OAuth2 authentication uses the machine user's client credentials to authenticate SCIM requests. This is the recommended approach as it provides secure, token-based authentication.

**SDK Configuration:**

```typescript
scim: {
  machineUserName: "scim-user",
  authorization: {
    type: "oauth2",
  },
  // ...
}
```

When using OAuth2, your IdP will need to obtain an access token using the machine user's client credentials before making SCIM requests. The token endpoint is:

```
POST https://{APP_DOMAIN}/oauth2/token
```

### Bearer Token Authentication

Bearer token authentication uses a static secret token stored in Secret Manager. While simpler to configure, OAuth2 is generally preferred for production environments.

> **Note:** For SDK-based configuration, define the secret in your secrets configuration and reference it in the authorization settings. Consult the [Secret Manager documentation](/guides/secretmanager) for details on managing secrets.

## Resource Mapping

Resource mapping defines how SCIM attributes are translated to your TailorDB fields. Each SCIM resource corresponds to a TailorDB type and includes a schema definition and field mappings.

### Schema Definition

The schema definition describes the SCIM attributes that your endpoint accepts. The Tailor Platform supports the standard SCIM 2.0 User schema (`urn:ietf:params:scim:schemas:core:2.0:User`).

**SDK Configuration:**

```typescript
scim: {
  machineUserName: "scim-user",
  authorization: {
    type: "oauth2",
  },
  resources: [
    {
      name: "Users",
      tailorDBNamespace: "tailordb",
      tailorDBType: "User",
      coreSchema: {
        name: "urn:ietf:params:scim:schemas:core:2.0:User",
        attributes: [
          {
            type: "string",
            name: "userName",
            required: true,
          },
          {
            type: "complex",
            name: "emails",
            required: true,
            multiValued: true,
            subAttributes: [
              {
                type: "string",
                name: "value",
              },
              {
                type: "boolean",
                name: "primary",
              },
            ],
          },
        ],
      },
      attributeMapping: [
        { tailorDBField: "name", scimPath: "userName" },
        { tailorDBField: "email", scimPath: "emails.#(primary==true).value" },
      ],
    },
  ],
}
```

### Supported Attribute Types

SCIM attributes can be one of the following types:

| Type       | Description                         |
| ---------- | ----------------------------------- |
| `string`   | Text values                         |
| `boolean`  | True/false values                   |
| `number`   | Numeric values                      |
| `datetime` | ISO 8601 formatted date-time values |
| `complex`  | Nested objects with sub-attributes  |

### Multi-Valued Attributes

Many SCIM attributes are multi-valued, meaning they contain arrays of values. The `emails` attribute is a common example, where a user may have multiple email addresses with one marked as primary.

To handle multi-valued attributes, you can use path expressions in your attribute mapping:

| Path Expression                      | Description                          |
| ------------------------------------ | ------------------------------------ |
| `emails.0.value`                     | First email's value                  |
| `emails.#(primary==true).value`      | Value of the email marked as primary |
| `phoneNumbers.#(type=="work").value` | Work phone number value              |

The `#(condition)` syntax allows you to filter multi-valued attributes based on a condition, making it easy to extract specific values like the primary email address.

### Attribute Mapping

Attribute mapping connects SCIM schema attributes to your TailorDB fields. Each mapping specifies:

* **tailorDBField**: The field name in your TailorDB type
* **scimPath**: The path to the SCIM attribute value

```typescript
attributeMapping: [
  { tailorDBField: "name", scimPath: "userName" },
  { tailorDBField: "email", scimPath: "emails.#(primary==true).value" },
  { tailorDBField: "firstName", scimPath: "name.givenName" },
  { tailorDBField: "lastName", scimPath: "name.familyName" },
];
```

## Complete Example

Here is a complete example showing SCIM configuration with the Tailor Platform SDK:

```typescript
import { defineAuth } from "@tailor-platform/sdk";
import { user } from "./tailordb/user";
import { createIdProviderConfig } from "./idp";

const AUTH_NAMESPACE = "my-auth";

export const authConfig = defineAuth(AUTH_NAMESPACE, {
  userProfile: {
    type: user,
    usernameField: "email",
    attributes: {
      attrs: true,
    },
  },
  idProvider: createIdProviderConfig(),
  oauth2Clients: {
    "oauth2-client": {
      redirectURIs: ["https://myapp.example.com/callback"],
      grantTypes: ["authorization_code", "refresh_token"],
      clientType: "browser",
    },
  },
  machineUsers: {
    "machine-user": {
      attributes: {
        attrs: ["admin"],
      },
    },
    "scim-user": {
      attributes: {
        attrs: ["admin"],
      },
    },
  },
  scim: {
    machineUserName: "scim-user",
    authorization: {
      type: "oauth2",
    },
    resources: [
      {
        name: "Users",
        tailorDBNamespace: "tailordb",
        tailorDBType: "User",
        coreSchema: {
          name: "urn:ietf:params:scim:schemas:core:2.0:User",
          attributes: [
            {
              type: "string",
              name: "userName",
              required: true,
            },
            {
              type: "complex",
              name: "emails",
              required: true,
              multiValued: true,
              subAttributes: [
                {
                  type: "string",
                  name: "value",
                },
                {
                  type: "boolean",
                  name: "primary",
                },
              ],
            },
          ],
        },
        attributeMapping: [
          { tailorDBField: "name", scimPath: "userName" },
          { tailorDBField: "email", scimPath: "emails.#(primary==true).value" },
        ],
      },
    ],
  },
});
```

## SCIM Endpoint

Once configured, your SCIM endpoint will be available at:

```
https://{APP_DOMAIN}/scim/{AUTH_NAMESPACE}/v2
```

The endpoint supports the following operations:

| Method | Endpoint      | Description         |
| ------ | ------------- | ------------------- |
| GET    | `/Users`      | List all users      |
| GET    | `/Users/{id}` | Get a specific user |
| POST   | `/Users`      | Create a new user   |
| PUT    | `/Users/{id}` | Replace a user      |
| PATCH  | `/Users/{id}` | Update a user       |
| DELETE | `/Users/{id}` | Delete a user       |

## IdP-Specific Considerations

Different Identity Providers may send SCIM data in slightly different formats. When configuring your attribute mappings, consult your IdP's SCIM documentation to understand the exact payload structure it sends. Always test your SCIM configuration with your specific IdP to ensure proper attribute mapping.

## Troubleshooting

Common issues when setting up SCIM provisioning:

**Authentication failures**: Verify that your machine user credentials are correct and that the IdP is using the proper authentication method (OAuth2 or Bearer token).

**Attribute mapping errors**: If user data is not being stored correctly, check that your `attributeMapping` paths correctly reference the SCIM attributes sent by your IdP. Use your IdP's SCIM testing tools to inspect the actual payload format and verify that paths like `emails.#(primary==true).value` match the structure of the incoming data.

**Permission errors**: Ensure the SCIM machine user has sufficient permissions to create, update, and delete records in the target TailorDB type.

**Schema definition errors**: If SCIM requests are rejected, verify that required attributes in your `coreSchema` definition match what your IdP sends, and that the attribute types (string, boolean, complex, etc.) are correctly specified.

---

---
url: https://docs.tailor.tech/guides/auth/spa-oauth2-client.md
---

# OAuth2 Client Selection for SPAs

When building Single Page Applications (SPAs) on the Tailor Platform, choosing the right OAuth2 client type is crucial for balancing security and browser compatibility. This guide explains the security considerations and trade-offs between using a Public client and a Browser client for SPA development.

## Client Type Options for SPAs

Tailor Platform supports two OAuth2 client types suitable for SPAs:

**Public Client** is designed for applications that cannot securely store client secrets, such as mobile apps and SPAs. When used for SPAs, additional security measures are required to protect against token theft and replay attacks.

**Browser Client** provides enhanced security through HTTP-only cookies, preventing JavaScript access to tokens. However, it has browser compatibility limitations due to third-party cookie restrictions.

## Public Client for SPAs

When using a Public client for SPA applications, you must enable additional security measures to protect tokens that are accessible to JavaScript.

### Required Security Configuration

To securely use a Public client in an SPA, the following configurations are **required**:

1. **Require DPoP (Demonstration of Proof-of-Possession)**: DPoP binds tokens to a specific client by requiring cryptographic proof of possession. This prevents stolen tokens from being used by attackers.

2. **Set a short access token lifetime**: Limiting the access token lifetime reduces the window of opportunity for token misuse if a token is compromised.

Combined with **refresh token rotation** (enabled by default), these measures ensure that even if tokens are intercepted, they cannot be easily reused by attackers.

### Configuration Example

**SDK Configuration:**

```typescript
import { defineAuth } from "@tailor-platform/sdk";

export const authConfig = defineAuth("my-auth", {
  oauth2Clients: {
    "spa-public-client": {
      description: "Public OAuth2 client for SPA with DPoP",
      clientType: "public",
      redirectURIs: [
        "http://localhost:3000/__oauth/callback",
        "https://myapp.example.com/__oauth/callback",
      ],
      grantTypes: ["authorization_code", "refresh_token"],

      // Required for SPA security
      requireDPoP: true,
      accessTokenLifetime: "15m",
      refreshTokenLifetime: "7d", // default
    },
  },
});
```

### Security Properties

| Property               | Description                                                                                                                                                                                                                |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `requireDPoP`          | When `true`, requires DPoP proof for all token requests. This binds tokens to the client's cryptographic key pair. DPoP is always available for clients to use; this setting controls whether the server enforces its use. |
| `accessTokenLifetime`  | Sets the access token expiration. Use short values like `"15m"` for SPAs. Maximum is 24 hours. Specified as a duration string (e.g., "15m", "1h").                                                                         |
| `refreshTokenLifetime` | Sets the refresh token expiration. Default is 7 days. On rotation, the new token's expiration does not extend beyond the original token's lifetime.                                                                        |

### Security Mechanisms

Tailor Platform uses three complementary mechanisms to secure Public clients in SPAs, as specified in [draft-ietf-oauth-browser-based-apps](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-browser-based-apps) (OAuth 2.0 for Browser-Based Applications):

1. **PKCE (Proof Key for Code Exchange)** - Protects the authorization code exchange by requiring a code verifier that only the legitimate client possesses. This is enabled by default for all Public clients.

2. **DPoP (Demonstration of Proof-of-Possession)** - Binds tokens to the client's cryptographic key pair, preventing stolen tokens from being used by attackers.

3. **DPoP-Nonce** - A server-provided nonce that must be included in DPoP proofs, preventing replay attacks by ensuring each proof is unique and tied to a specific server interaction.

Together, these mechanisms implement the Sender-Constrained Tokens pattern, providing robust protection for SPAs.

#### How It Works

1. The SPA generates a public/private key pair
2. When requesting tokens, the SPA creates a signed DPoP proof using the private key
3. The authorization server binds the issued tokens to the public key
4. When using the access token, the SPA must include a fresh DPoP proof with the server-provided nonce
5. If an attacker steals the token, they cannot use it without the private key

### Token Storage Considerations

> **Security Warning**: When using a Public client, tokens are stored in browser storage (such as localStorage or sessionStorage) which is accessible to JavaScript. If your application has an XSS vulnerability, malicious scripts could potentially access these tokens. While DPoP significantly mitigates this risk by making stolen tokens unusable without the private key, it cannot prevent malicious code running in the same context from obtaining new token sets. Always follow XSS prevention best practices and consider using a Browser client if Safari support is not required.

## Browser Client

Browser clients use HTTP-only cookies to store tokens, which provides stronger security by preventing JavaScript from accessing the tokens directly.

### Security Benefits

Browser clients offer enhanced protection against common web vulnerabilities:

* **XSS Protection**: Tokens stored in HTTP-only cookies cannot be accessed by malicious JavaScript, even if an XSS vulnerability exists
* **Automatic Token Handling**: The browser automatically includes cookies in requests, simplifying token management
* **CSRF Protection**: Tailor Platform requires a custom `X-Tailor-Nonce` header to defend against CSRF attacks

### Configuration Example

**SDK Configuration:**

```typescript
import { defineAuth } from "@tailor-platform/sdk";

export const authConfig = defineAuth("my-auth", {
  oauth2Clients: {
    "spa-browser-client": {
      description: "Browser OAuth2 client for SPA",
      clientType: "browser",
      redirectURIs: [
        "http://localhost:3000/__oauth/callback",
        "https://myapp.example.com/__oauth/callback",
      ],
      grantTypes: ["authorization_code", "refresh_token"],
    },
  },
});
```

### Browser Compatibility Limitation

> **Safari Limitation**: Browser clients do not work reliably in Safari due to its Intelligent Tracking Prevention (ITP) feature. ITP blocks third-party cookies, which prevents the HTTP-only cookies used by browser clients from being stored or sent correctly. If your application needs to support Safari users, use a Public client with DPoP and short token lifetime instead.

## Client Type Selection Guide

Use the following table to determine which client type best fits your requirements:

| Requirement                     | Recommended Client | Configuration Notes                                                    |
| ------------------------------- | ------------------ | ---------------------------------------------------------------------- |
| Safari support needed           | Public Client      | Require DPoP (`requireDPoP: true`) and set short access token lifetime |
| More secure (Safari not needed) | Browser Client     | Uses HTTP-only cookies for token storage                               |
| Shared codebase with mobile app | Public Client      | Same client type works across web and mobile platforms                 |

### Decision Flowchart

1. **Does your SPA need to support Safari?**
   * **Yes**: Use Public Client with DPoP and short token lifetime
   * **No**: Continue to step 2

2. **Do you want more secure token storage?**
   * **Yes**: Use Browser Client (HTTP-only cookies prevent JavaScript access)
   * **No**: Continue to step 3

3. **Do you share code with a mobile application?**
   * **Yes**: Use Public Client with DPoP (consistent across platforms)
   * **No**: Use Browser Client

## Summary

Both Public and Browser clients can be used securely for SPAs, but they have different trade-offs:

**Public Client with DPoP** requires additional configuration (DPoP required, short token lifetime) but provides cross-browser compatibility including Safari. The refresh token rotation enabled by default adds another layer of security.

**Browser Client** offers stronger built-in security through HTTP-only cookies but does not work in Safari due to ITP restrictions. Choose this option when Safari support is not required.

## Related Resources

* [Create an OAuth2 Client](/tutorials/setup-auth/login/create-oauth2-client) - Step-by-step tutorial for configuring OAuth2 clients
* [Log in to your app](/guides/auth/app-login) - Understanding OAuth2 client configuration and login flows
* [Auth Service Overview](/guides/auth/overview) - Comprehensive guide to the Auth service

---

---
url: https://docs.tailor.tech/guides/auth/integration/auth0.md
---

# Auth0 Integration

Auth0 is a flexible identity platform that provides authentication and authorization services for applications. This guide demonstrates how to integrate Auth0 with the Tailor Platform Auth service using OIDC, SAML, or ID Token authentication methods.

## Prerequisites

* An active Auth0 account
* A Tailor Platform workspace with Auth service enabled
* Basic understanding of authentication protocols

## Setting up Auth0 for OIDC

### Step 1: Create an Application

1. Log in to your Auth0 Dashboard
2. Navigate to **Applications** > **Applications**
3. Click **Create Application**
4. Choose **Regular Web Applications** as the application type
5. Click **Create**

### Step 2: Configure Application Settings

In your application settings, configure:

**Basic Information:**

* **Name**: Your application name
* **Description**: Brief description of your application

**Application URIs:**

* **Allowed Callback URLs**:
  ```
  https://{your-app-domain}/oauth2/callback
  ```
* **Allowed Logout URLs**:
  ```
  https://{your-app-domain}/logout
  ```
* **Allowed Web Origins**:
  ```
  https://{your-app-domain}
  ```

### Step 3: Get Application Credentials

From the application settings, note:

* **Domain**: Your Auth0 domain (e.g., `dev-12345.us.auth0.com`)
* **Client ID**: Your application's client ID
* **Client Secret**: Your application's client secret

## Setting up Auth0 for SAML

### Step 1: Enable SAML2 Web App Addon

1. In your Auth0 application, go to the **Addons** tab
2. Enable **SAML2 WEB APP**
3. Click on the addon to configure it

### Step 2: Configure SAML Settings

In the SAML2 addon settings:

**Application Callback URL:**

```
https://{your-app-domain}/oauth2/callback
```

**Settings (JSON):**

```json
{
  "audience": "https://api.tailor.tech/saml/{workspace_id}/{auth_namespace}/metadata.xml",
  "nameIdentifierFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
  "nameIdentifierProbes": ["http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"]
}
```

### Step 3: Download Metadata

After saving the settings, download the SAML metadata from:

```
https://{your-auth0-domain}/samlp/metadata/{client-id}
```

## Setting up Auth0 for ID Token

### Step 1: Configure Application

Follow the same steps as OIDC setup, but additionally:

1. Go to **Advanced Settings** > **Grant Types**
2. Enable **Password** grant type (for testing purposes)

### Step 2: Configure Tenant Settings

1. Navigate to **Settings** > **General**
2. In **API Authorization Settings**, set:
   * **Default Directory**: `Username-Password-Authentication`

## Configuring Auth Service

Configure your Tailor Platform Auth service to work with Auth0:

```typescript
import { defineAuth, defineIdp } from "@tailor-platform/sdk";
import { user } from "./tailordb/user";

// OIDC Configuration
export const auth0Oidc = defineIdp("auth0-oidc", {
  clientId: process.env.AUTH0_CLIENT_ID,
  clientSecret: process.env.AUTH0_CLIENT_SECRET,
  oidcConfiguration: {
    issuer: "https://{your-auth0-domain}",
  },
});

// SAML Configuration (alternative)
export const auth0Saml = defineIdp("auth0-saml", {
  clientId: "your-client-id",
  samlConfiguration: {
    metadataUrl: "https://{your-auth0-domain}/samlp/metadata/{client-id}",
  },
});

// ID Token Configuration (alternative)
export const auth0IdToken = defineIdp("auth0-id-token", {
  clientId: "your-client-id",
  idTokenConfiguration: {
    issuer: "https://{your-auth0-domain}",
  },
});

// Configure Auth service to use Auth0 (choose OIDC, SAML, or ID Token)
export const auth = defineAuth("main-auth", {
  userProfile: {
    type: user,
    usernameField: "email",
    attributes: {
      email: true,
      firstName: true,
      lastName: true,
    },
  },
  // Use one of the IdP configurations
  idProvider: auth0Oidc.provider("auth0-oidc-provider"),
  // idProvider: auth0Saml.provider("auth0-saml-provider"),
  // idProvider: auth0IdToken.provider("auth0-id-token-provider"),
});
```

## Testing with ID Token

For testing purposes, you can obtain an ID token directly from Auth0:

```bash
curl --request POST \
  --url 'https://{your-auth0-domain}/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=password \
  --data username={user-email} \
  --data password={user-password} \
  --data audience={api-identifier} \
  --data scope=openid \
  --data client_id={client-id} \
  --data client_secret={client-secret}
```

Then use the returned ID token with your Tailor Platform application.

## Troubleshooting

### Common Issues

**Invalid Grant Type**

* Ensure the correct grant types are enabled in your Auth0 application
* For production, disable Password grant and use Authorization Code flow

**CORS Errors**

* Add your application domain to Allowed Web Origins in Auth0
* Ensure HTTPS is used for production environments

Auth0 offers extensive customization options through Rules, Actions, and Hooks. Explore these features to tailor the authentication flow to your specific needs.

## Next Steps

* [Log in to your app](/guides/auth/app-login) - Guide for user creation and login
* [Configure user roles and permissions](/guides/tailordb/permission)
* [Set up machine users for API access](/guides/auth/overview#machineuser)
* [Learn about Auth as a subgraph](/guides/auth/overview#authasasubgraph)

---

---
url: https://docs.tailor.tech/guides/auth/integration/built-in-idp.md
---

# Built-in IdP&#x20;

Managing multiple identity providers can be a hassle. The Built-in IdP offers a native solution within the Tailor Platform, eliminating the need for external providers and seamlessly integrating with your Auth service. In this guide, you’ll learn how to set it up, configure it, and integrate it with your applications in just a few steps.

**Consistent User Experience**: The usability of authentication and authorization remains unchanged whether using Built-in IdP or external identity providers. Users will experience the same authentication flows and access controls regardless of your IdP choice.

## Prerequisites

Before setting up Built-in IdP, ensure you have:

* A Tailor Platform workspace
* Auth service configured in your application

## Configuration

Built-in IdP requires several resources working together to provide complete authentication functionality. The setup involves creating an IdP service, client configuration, secret management, and Auth service integration.

All Built-in IdP user management operations are denied by default. This applies to both GraphQL operations and access via [`tailor.idp.Client`](/guides/function/managing-idp-users) in Functions.

Access must be explicitly granted by defining per-operation permission policies in the `permission` block. This follows the same policy-based model as [TailorDB Permission](/guides/tailordb/permission), though the supported operators and operands differ between the two.

```typescript
// tailor.config.ts
import { defineConfig, defineIdp, defineAuth } from "@tailor-platform/sdk";
import { user } from "./tailordb/user"; // Your TailorDB user type

// 1. Define the IdP service with client and permission
const idp = defineIdp("builtin-idp", {
  clients: ["main-client"], // Automatically creates client credentials
  permission: {
    create: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    read: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    update: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    delete: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    sendPasswordResetEmail: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
  },
  userAuthPolicy: {
    useNonEmailIdentifier: false,
    allowSelfPasswordReset: true,
  },
  emailConfig: {
    fromName: "My App Support",
    passwordResetSubject: "Reset your My App password",
  },
});

// 2. Configure Auth service to use the Built-in IdP
const auth = defineAuth("my-auth", {
  userProfile: {
    type: user,
    usernameField: "email",
    attributes: { role: true },
  },
  // Connects Auth to IdP - secrets are managed automatically
  idProvider: idp.provider("builtin-idp-provider", "main-client"),
});

// 3. Export the complete configuration
export default defineConfig({
  idp: [idp],
  auth,
});
```

### Permission Configuration

The `permission` block controls who can perform each IdP user management operation. Each operation has an independent list of policies.

:::warning Important
If `permission` is not configured, all IdP user management operations (`create`, `read`, `update`, `delete`, `sendPasswordResetEmail`) will be denied. This includes both GraphQL operations and access via `tailor.idp.Client` in Functions. OIDC-based login is not affected by permission settings.
:::

:::tip
The role values used in permission conditions (e.g., `"ADMIN"`) are examples. Replace them with the actual values from your Auth service's AttributeMap. Comparisons are case-sensitive.
:::

#### Operations

| Operation                | Description                                 | Available operands                                 |
| ------------------------ | ------------------------------------------- | -------------------------------------------------- |
| `create`                 | Controls who can create IdP users           | `user`, `idpUser`, literal values                  |
| `read`                   | Controls who can read IdP users             | `user`, `idpUser`, literal values                  |
| `update`                 | Controls who can update IdP users           | `user`, `oldIdpUser`, `newIdpUser`, literal values |
| `delete`                 | Controls who can delete IdP users           | `user`, `idpUser`, literal values                  |
| `sendPasswordResetEmail` | Controls who can send password reset emails | `user`, `idpUser`, literal values                  |

#### Policy Evaluation

Policies are evaluated sequentially in array order:

1. If the policy list is empty (or `permission` is not configured for the operation), the operation is **denied** (implicit deny)
2. For each policy, all conditions are checked (AND). If all conditions are satisfied, the policy matches
3. If a matching policy has `permit: false`, the operation is **immediately denied** (short-circuit). No further policies are evaluated
4. If a matching policy has `permit: true`, it is recorded as allowed, but evaluation continues to check for subsequent deny policies
5. After all policies are evaluated, the operation is allowed only if at least one allow policy matched. Otherwise it is denied

Because deny short-circuits, **deny always takes precedence over allow regardless of order**.

#### Operands

* `{ user: "field" }` - Authenticated user's attribute from JWT claims (e.g., `"_id"`, `"_loggedIn"`, or custom attributes from Auth's AttributeMap)
* `{ idpUser: "field" }` - Target IdP user's field (for create/read/delete/sendPasswordResetEmail). Available fields: `"id"`, `"name"`, `"disabled"`
* `{ oldIdpUser: "field" }` - IdP user field before update (for update only). Available fields: `"id"`, `"name"`, `"disabled"`
* `{ newIdpUser: "field" }` - IdP user field after update (for update only). Available fields: `"id"`, `"name"`, `"disabled"`
* Literal values: `string`, `boolean`, `string[]`, `boolean[]`

#### Operators

`"="`, `"!="`, `"in"`, `"not in"`

#### Examples

**Role-based access control:**

```typescript
const idp = defineIdp("builtin-idp", {
  clients: ["main-client"],
  permission: {
    create: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    read: [{ conditions: [[{ user: "_loggedIn" }, "=", true]], permit: true }],
    update: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    delete: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    sendPasswordResetEmail: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
  },
});
```

**Self-record access with admin override:**

This example assumes that `usernameField` is `"email"` (i.e., the IdP user's `name` field contains an email address), and that `email` is mapped in the Auth service's `attributes` so that `{ user: "email" }` is available in permission conditions:

```typescript
const auth = defineAuth("my-auth", {
  userProfile: {
    type: user,
    usernameField: "email",
    attributes: { role: true, email: true }, // "email" must be included
  },
  idProvider: idp.provider("builtin-idp-provider", "main-client"),
});
```

```typescript
const idp = defineIdp("builtin-idp", {
  clients: ["main-client"],
  permission: {
    create: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    read: [
      // Admins can read all users
      { conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true },
      // Users can read their own record
      {
        conditions: [[{ user: "email" }, "=", { idpUser: "name" }]],
        permit: true,
      },
    ],
    update: [
      { conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true },
      {
        conditions: [
          [{ user: "email" }, "=", { oldIdpUser: "name" }],
          [{ user: "email" }, "=", { newIdpUser: "name" }],
        ],
        permit: true,
      },
    ],
    delete: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    sendPasswordResetEmail: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
  },
});
```

**Deny creating disabled users:**

```typescript
const idp = defineIdp("builtin-idp", {
  clients: ["main-client"],
  permission: {
    create: [
      // Deny takes precedence: prevent creating disabled users
      {
        conditions: [[{ idpUser: "disabled" }, "=", true]],
        permit: false,
      },
      // Allow admins to create users
      { conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true },
    ],
    // ... other operations
  },
});
```

### Architecture Overview

The Built-in IdP integration involves three main components working together:

1. **IdP Service**: Provides the identity provider functionality and user authentication
2. **Auth Service**: Handles authentication flows and user session management
3. **Application**: Orchestrates the services and exposes the unified GraphQL API

### Integration Flow

**Step 1: IdP Service Setup**
The `tailor_idp` resource creates the identity provider service that will handle user authentication. This service:

* Manages user credentials and authentication
* Provides OIDC endpoints for authentication flows
* Generates client credentials for secure communication

**Step 2: Auth Service Configuration**
The `tailor_auth_idp_config` resource connects your Auth service to the Built-in IdP:

* Configures OIDC settings to communicate with the IdP service
* Maps user claims to application user profiles
* Handles token validation and user session management

**Step 3: Application Integration**
When you register both IdP and Auth services as subgraphs in your application, they become part of your unified GraphQL schema:

* IdP subgraph provides user management operations (`_users`, `_createUser`, etc.)
* Auth subgraph provides authentication and authorization functionality
* Application orchestrates both services through a single GraphQL endpoint

### Service Communication

The services communicate through secure internal channels:

```
User Request → Application → Auth Service → IdP Service
                    ↓              ↓           ↓
              GraphQL API → Token Validation → User Authentication
```

**Authentication Flow:**

1. User attempts to authenticate through your application
2. Auth service redirects to Built-in IdP OIDC endpoints
3. IdP service validates credentials and issues tokens
4. Auth service validates tokens and creates user sessions
5. Application provides authenticated access to protected resources

### Authentication Policy Configuration

The `user_auth_policy` block allows you to configure how users authenticate with the Built-in IdP:

* **Email-only authentication** (default): When `use_non_email_identifier` is `false` or omitted, users can only authenticate using email addresses
* **Username-based authentication**: When `use_non_email_identifier` is `true`, users can authenticate using identifiers other than email addresses (such as usernames)
* **Self-service password reset**: When `allow_self_password_reset` is `true`, a "Forgot Password?" link is displayed on the sign-in screen, allowing users to reset their own password. This option is disabled by default.
* **Google OAuth**: When `allow_google_oauth` is `true`, a "Sign in with Google" button is displayed on the sign-in screen, allowing users to authenticate using their Google account. Requires `allowed_email_domains` to be set. See [Google OAuth](#google-oauth) for details.
* **Allowed email domains**: When `allowed_email_domains` is set, only users with email addresses from the specified domains can sign in or be created. See [Allowed Email Domains](#allowed-email-domains) for details.
* **Microsoft OAuth**: When `allow_microsoft_oauth` is `true`, a "Sign in with Microsoft" button is displayed on the sign-in screen, allowing users to authenticate using their Microsoft account. Requires `allowed_email_domains` and `disable_password_auth` to be set. See [Microsoft OAuth](#microsoft-oauth) for details.
* **Disable password authentication**: When `disable_password_auth` is `true`, password-based sign-in and password reset are disabled. Google OAuth or Microsoft OAuth becomes the sole authentication method. See [Disable Password Authentication](#disable-password-authentication) for details.

This flexibility allows you to choose the authentication method that best fits your application's requirements.

### Password Policy Configuration

The Built-in IdP allows you to enforce password requirements to enhance security. You can configure password policies within the `user_auth_policy` block to require specific character types and set length constraints.

**Available Password Policy Options:**

* **`password_require_uppercase`** (boolean) - Requires at least one uppercase letter (A-Z) in the password. Defaults to `false`.

* **`password_require_lowercase`** (boolean) - Requires at least one lowercase letter (a-z) in the password. Defaults to `false`.

* **`password_require_numeric`** (boolean) - Requires at least one numeric digit (0-9) in the password. Defaults to `false`.

* **`password_require_non_alphanumeric`** (boolean) - Requires at least one special character (e.g., !@#$%^&\*) in the password. Defaults to `false`.

* **`password_min_length`** (integer) - Minimum password length. Valid range is 6-30. Defaults to `6`.

* **`password_max_length`** (integer) - Maximum password length. Valid range is 6-4096. Defaults to `4096`.

**Example Configuration:**

```typescript
import { defineIdp } from "@tailor-platform/sdk";

export const builtinIdp = defineIdp("builtin-idp", {
  clients: ["main-client"],
  permission: {
    create: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    read: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    update: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    delete: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    sendPasswordResetEmail: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
  },
  userAuthPolicy: {
    useNonEmailIdentifier: false,
    allowSelfPasswordReset: true,
    // Password policy settings
    passwordRequireUppercase: true,
    passwordRequireLowercase: true,
    passwordRequireNumeric: true,
    passwordRequireNonAlphanumeric: true,
    passwordMinLength: 8,
    passwordMaxLength: 128,
  },
});
```

:::warning Important
When a password policy is updated, existing users whose passwords do not meet the new requirements will be unable to log in until they update their passwords. They will be prompted to reset their password upon their next sign-in attempt.
:::

### Google OAuth

The Built-in IdP supports "Sign in with Google", allowing users to authenticate using their Google accounts. When enabled, a Google Sign-In button is displayed on the sign-in screen alongside the standard email/password form.

**How it works:**

1. User clicks the "Sign in with Google" button on the sign-in screen
2. Google authenticates the user and returns a verified ID token
3. The Built-in IdP verifies the token and checks the user's email
4. If the user does not yet exist, a new IdP user is automatically created using the Google account's email address (without a password)
5. The user is signed in and redirected to the application

If you configure a [`beforeLogin` hook](/guides/auth/hook#federated-identity-claims), the Google account's profile (such as `picture`, `name`, `given_name`, `family_name`, and `locale`) is available to it on `claims.federated_identity`, so you can populate your user record from the provider's profile.

:::tip
Users created via Google OAuth do not have a password set. They can only sign in using Google. To enable password-based login for these users, use the `_sendPasswordResetEmail` mutation to set an initial password.
:::

:::warning
`allow_google_oauth`, `allow_microsoft_oauth`, `allowed_email_domains`, and `disable_password_auth` are only available via the Terraform provider. These settings are not currently supported in CUE configurations.
:::

To enable Google OAuth, set `allow_google_oauth` to `true` and specify `allowed_email_domains` in the `user_auth_policy` block:

```typescript
import { defineIdp } from "@tailor-platform/sdk";

export const builtinIdp = defineIdp("builtin-idp", {
  clients: ["main-client"],
  permission: {
    create: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    read: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    update: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    delete: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    sendPasswordResetEmail: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
  },
  userAuthPolicy: {
    allowGoogleOauth: true,
    allowedEmailDomains: ["example.com"],
  },
});
```

:::tip
`allow_google_oauth` requires `allowed_email_domains` to be set. This ensures that only users from specified email domains can authenticate via Google OAuth.
:::

:::warning
`allow_google_oauth` cannot be enabled when `use_non_email_identifier` is `true`. Google OAuth requires email-based identifiers because Google accounts are identified by email addresses.
:::

### Microsoft OAuth

The Built-in IdP supports "Sign in with Microsoft", allowing users to authenticate using their Microsoft accounts via Microsoft Entra ID. When enabled, a Microsoft Sign-In button is displayed on the sign-in screen.

**How it works:**

1. User clicks the "Sign in with Microsoft" button on the sign-in screen
2. Microsoft authenticates the user and returns a verified ID token
3. The Built-in IdP verifies the token and checks the user's identity
4. If the user does not yet exist, a new IdP user is automatically created using the Microsoft account's preferred username (UPN) (without a password)
5. The user is signed in and redirected to the application

If you configure a [`beforeLogin` hook](/guides/auth/hook#federated-identity-claims), the Microsoft account's profile (such as `name`, `given_name`, and `family_name`) is available to it on `claims.federated_identity`. Microsoft does not issue `picture`.

:::tip
Users created via Microsoft OAuth do not have a password set. They can only sign in using Microsoft.
:::

To enable Microsoft OAuth, set `allowMicrosoftOauth` to `true`, specify `allowedEmailDomains`, and set `disablePasswordAuth` to `true` in the `userAuthPolicy` block:

```typescript
import { defineIdp } from "@tailor-platform/sdk";

export const builtinIdp = defineIdp("builtin-idp", {
  clients: ["main-client"],
  permission: {
    create: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    read: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    update: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    delete: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    sendPasswordResetEmail: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
  },
  userAuthPolicy: {
    allowMicrosoftOauth: true,
    allowedEmailDomains: ["example.com"],
    disablePasswordAuth: true,
  },
});
```

:::tip
`allowMicrosoftOauth` requires both `allowedEmailDomains` and `disablePasswordAuth` to be set. This ensures that only users from specified email domains can authenticate, and that Microsoft OAuth is the sole authentication method.
:::

:::warning Why Microsoft OAuth cannot be combined with password authentication
Microsoft OAuth cannot be enabled together with password authentication in the Built-in IdP. When the Built-in IdP uses email addresses as user identifiers (`useNonEmailIdentifier: false`), this restriction is necessary because:

* The `email` claim from Microsoft Entra ID is not guaranteed to be unique within a tenant and may be empty, so it cannot be used reliably to identify and match users.
* The `preferred_username` claim (UPN) is used instead because it is unique within an Entra ID tenant. Although it has an email-address-like format, it is not necessarily a deliverable email address.

The Built-in IdP uses the user's identifier as the destination address for password reset emails sent by the Tailor Platform. Because a UPN is not necessarily a deliverable email address, these messages may be sent to addresses that cannot receive them. To maintain reliable email delivery from the Platform, Microsoft OAuth cannot be combined with password authentication. Google OAuth does not have this conflict because its `email` claim is suitable for user matching and password reset delivery.

For this reason, configure Microsoft OAuth as the sole authentication method by setting `disablePasswordAuth: true`, or use separate IdP namespaces when both Microsoft OAuth and password authentication are required.
:::

:::warning
`allowMicrosoftOauth` cannot be enabled when `useNonEmailIdentifier` is `true`. Microsoft OAuth requires email-based identifiers because Microsoft accounts are identified by their preferred username (UPN).
:::

### Allowed Email Domains

You can restrict which email domains are allowed to sign in or be created in the Built-in IdP by setting `allowed_email_domains`. When configured, only users whose email addresses belong to one of the specified domains can authenticate or be registered. This applies to both standard email/password sign-in and Google OAuth.

**Configuration:**

* `allowed_email_domains` (list of strings) - A list of allowed email domains (e.g., `["example.com", "corp.example.com"]`). An empty list (default) means all domains are allowed. Maximum 100 domains.

**Example Configuration:**

```typescript
import { defineIdp } from "@tailor-platform/sdk";

export const builtinIdp = defineIdp("builtin-idp", {
  clients: ["main-client"],
  permission: {
    create: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    read: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    update: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    delete: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    sendPasswordResetEmail: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
  },
  userAuthPolicy: {
    allowGoogleOauth: true,
    allowedEmailDomains: ["example.com", "corp.example.com"],
  },
});
```

:::warning
`allowed_email_domains` cannot be set when `use_non_email_identifier` is `true`, as email domain validation requires email-based identifiers.
:::

### Disable Password Authentication

You can disable password-based authentication entirely by setting `disable_password_auth` to `true`. When enabled, the sign-in screen displays only the OAuth sign-in buttons (Google and/or Microsoft), and all password-related operations are blocked.

**When `disable_password_auth` is enabled:**

* The email/password sign-in form is hidden from the sign-in screen
* The "Forgot Password?" link is removed
* Password-based sign-in attempts are rejected
* The `_sendPasswordResetEmail` GraphQL mutation is excluded from the schema
* OAuth (Google and/or Microsoft) becomes the sole authentication method

**Configuration:**

* `disable_password_auth` (boolean) - Disables password-based authentication for this namespace. Defaults to `false`.

**Requirements:**

* `allow_google_oauth` or `allow_microsoft_oauth` must be `true` (at least one authentication method must remain available)
* `allowed_email_domains` must be set (required by `allow_google_oauth`)
* `allow_self_password_reset` must be `false` (cannot enable password reset when password authentication is disabled)

**Example Configuration:**

```typescript
import { defineIdp } from "@tailor-platform/sdk";

export const builtinIdp = defineIdp("builtin-idp", {
  clients: ["main-client"],
  permission: {
    create: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    read: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    update: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    delete: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    sendPasswordResetEmail: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
  },
  userAuthPolicy: {
    allowGoogleOauth: true,
    allowedEmailDomains: ["example.com"],
    disablePasswordAuth: true,
  },
});
```

:::warning
When `disable_password_auth` is enabled, existing users who previously signed in with a password will need to use Google OAuth or Microsoft OAuth instead. Ensure that all users have accounts with the configured OAuth provider and email addresses in the allowed domains before enabling this setting.
:::

### Multi-Factor Authentication (TOTP)

The Built-in IdP supports time-based one-time password (TOTP) MFA. Once enabled, users can register an authenticator app (Google Authenticator, 1Password, Authy, etc.), and you can optionally require MFA for every password-based sign-in. The label shown next to the user account in the authenticator app is the value of `mfaIssuer`.

There are two distinct flows:

**Mandatory enrollment during sign-in (when `requireMfa: true`)**

The IdP sign-in page handles enrollment inline — no application code is needed.

1. The user enters their password on the IdP sign-in page as usual.
2. If the user has no enrolled factor, the page shows a QR code, the user scans it into their authenticator app, and verifies a TOTP code.
3. Once verified, the sign-in completes and the OIDC callback fires.
4. On subsequent sign-ins, the page prompts only for the TOTP code.

**Self-service management (any time `enableMfa: true`)**

`_requestMfaSettingsUrl` issues an MFA settings page URL for the calling user. The signed-in user opens that URL to manage their own factors — add a new authenticator, remove a lost one, or opt in to MFA when `requireMfa: false`.

1. Your application calls the `_requestMfaSettingsUrl` GraphQL query as the signed-in user, supplying a `returnTo` URL.
2. The IdP validates `returnTo` against `allowedReturnOrigins` and returns the URL.
3. The application redirects the user to that URL.
4. The user manages their factors (enroll a new device, remove an existing one) on the settings page.
5. The user is redirected back to `returnTo`.

**Configuration:**

```typescript
import { defineIdp, defineStaticWebSite } from "@tailor-platform/sdk";

const website = defineStaticWebSite("my-frontend", { description: "App frontend" });

const idp = defineIdp("builtin-idp", {
  clients: ["main-client"],
  userAuthPolicy: {
    enableMfa: true,
    requireMfa: false,
    allowedReturnOrigins: [website.url, "https://admin.example.com"],
    mfaIssuer: "My App",
  },
  permission: {
    create: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    read: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    update: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    delete: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    sendPasswordResetEmail: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    unenrollMfa: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
  },
});
```

**Configuration options (inside `userAuthPolicy`):**

* `enableMfa` (boolean) — Make TOTP MFA available for users in this namespace. Defaults to `false`. When `true`, the IdP exposes the MFA settings page and the `_requestMfaSettingsUrl` / `_unenrollMfa` GraphQL operations.
* `requireMfa` (boolean) — Force password-authenticated users to enroll and pass an MFA challenge on every sign-in. Defaults to `false`. Unenrolled users are enrolled inline on the IdP sign-in page (see the **Mandatory enrollment during sign-in** flow above); the application does not need to call `_requestMfaSettingsUrl` to bootstrap enrollment.
* `allowedReturnOrigins` (string\[]) — Origins the IdP self-service pages (such as `/mfa/settings`) are allowed to redirect back to. Each entry is either a literal origin (`https://app.example.com`, scheme + host + optional port, no path/query/fragment) or a static-website placeholder `<name>:url` (e.g. `website.url`) that the CLI resolves to the deployed website's URL at apply time. Required when `enableMfa` is `true`. Up to 50 entries.
* `mfaIssuer` (string, optional) — Label shown next to the user account in authenticator apps. Up to 64 characters. Falls back to `"Tailor Platform IdP"` when empty.

**Permission option:**

* `permission.unenrollMfa` — Controls who can remove an enrolled MFA factor from a user via the `_unenrollMfa` mutation. **Required when `enableMfa` is `true`.** Set `[{ conditions: [...], permit: true }]` to allow, or `[]` to deny all. Use the same operands and operators as the other permission categories. Typically restricted to administrators.

**Constraints:** the following combinations are rejected at parse time.

* `requireMfa: true` requires `enableMfa: true`.
* `enableMfa: true` requires at least one entry in `allowedReturnOrigins`.
* `enableMfa: true` requires `permission` to be defined and to include an explicit `unenrollMfa` policy.

**Sign-in behavior:**

* **`enableMfa: true`, `requireMfa: false`** — MFA is optional. Users opt in from their own MFA settings page (issued by `_requestMfaSettingsUrl`); once enrolled, they are challenged for TOTP on every subsequent sign-in.
* **`enableMfa: true`, `requireMfa: true`** — MFA is mandatory for password sign-in. The IdP sign-in page enrolls unenrolled users inline before completing the sign-in, so the application does not need to call `_requestMfaSettingsUrl` to bootstrap enrollment.
* **Social sign-in (Google / Microsoft OAuth)** — Not affected by `requireMfa`. MFA enforcement is the upstream provider's responsibility for these sessions.

:::warning
`enableMfa` cannot be combined with `disablePasswordAuth: true`. Without password authentication, the MFA settings page has no way to authenticate the user, so the IdP does not expose `_requestMfaSettingsUrl` or `_unenrollMfa` for OAuth-only namespaces.
:::

#### Issuing a per-user MFA settings page URL

`_requestMfaSettingsUrl` returns an MFA settings page URL bound to the calling user. Call it from your application (typically from a "Security" / "Account" page) as the signed-in user, then redirect the browser to the returned URL:

```graphql
query RequestMfaSettingsUrl($input: _RequestMfaSettingsUrlInput!) {
  _requestMfaSettingsUrl(input: $input) {
    url
  }
}
```

Variables:

```json
{
  "input": {
    "returnTo": "https://app.example.com/account/security"
  }
}
```

The `returnTo` URL must be an absolute URL whose origin matches one of the entries in `allowedReturnOrigins` (the comparison is case-insensitive and elides default ports). The IdP redirects the user back to `returnTo` after they finish enrolling or unenrolling factors.

#### Inspecting MFA enrollment state

The user record exposes two MFA fields. They are read live from Identity Platform on every request (never cached in TailorDB), so they always reflect the current enrollment state.

```graphql
query GetUserMfa($userId: ID!) {
  _user(id: $userId) {
    id
    name
    mfaEnrolled
    mfaFactorIds
  }
}
```

* `mfaEnrolled` (Boolean!) — `true` when the user has at least one MFA factor enrolled.
* `mfaFactorIds` (\[String!]!) — Identity Platform-issued IDs of the user's enrolled factors. Pass one of these to `_unenrollMfa` to remove a single factor.

#### Removing a user's MFA factor (admin)

Use `_unenrollMfa` to remove a single factor on behalf of a user (for example when a user has lost their authenticator device). The mutation is subject to the `unenrollMfa` permission policy and requires read access to the target user.

```graphql
mutation UnenrollMfa($input: _UnenrollMfaInput!) {
  _unenrollMfa(input: $input)
}
```

Variables:

```json
{
  "input": {
    "userId": "user-id-here",
    "mfaFactorId": "factor-id-from-mfaFactorIds"
  }
}
```

If `requireMfa: true` and the unenrolled user has no remaining factors, that user must enroll again before their next sign-in.

### Email Configuration

The Built-in IdP allows you to customize the sender name and subject line for emails sent by the IdP (such as password reset emails). You can configure namespace-level defaults using the `emailConfig` option, and optionally override them per request.

**Priority chain** (highest to lowest):

1. **Per-request parameter** — `fromName` / `subject` passed in `_sendPasswordResetEmail` or `tailor.idp.sendPasswordResetEmail`
2. **Namespace default** — configured in `emailConfig`
3. **Hardcoded default** — `"Tailor Platform IdP"` for sender name, localized default for subject

**Configuration:**

* `fromName` (string, optional) — Default sender display name for emails. Max 200 characters. When omitted, falls back to `"Tailor Platform IdP"`.
* `passwordResetSubject` (string, optional) — Default subject line for password reset emails. Max 200 characters. When omitted, falls back to the localized default subject.

**Example Configuration:**

```typescript
import { defineIdp } from "@tailor-platform/sdk";

export const builtinIdp = defineIdp("builtin-idp", {
  clients: ["main-client"],
  permission: {
    create: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    read: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    update: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    delete: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    sendPasswordResetEmail: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
  },
  emailConfig: {
    fromName: "My App Support",
    passwordResetSubject: "Reset your My App password",
  },
});
```

With this configuration, password reset emails will be sent as `My App Support <no-reply@idp.erp.dev>` with the subject "Reset your My App password", unless overridden per request.

### Why Use the Built-In IdP

* **Unified API with Automatic Schema Generation**: When registered as subgraphs, both services automatically contribute their schemas to your application's GraphQL API, making all authentication and user management operations available through a single GraphQL endpoint and simplifying client integration.

* **Centralized Configuration**: All authentication settings are managed through your application configuration, providing a single source of truth.

* **Flexible Authentication**: Support for both email and username-based authentication through the `user_auth_policy` configuration, with optional Google OAuth and Microsoft OAuth integration for streamlined sign-in.

For detailed configuration parameters for each resource, refer to the [Terraform provider documentation](https://registry.terraform.io/providers/tailor-platform/tailor/latest/docs/resources/idp).

## User Management

When you register a Built-in IdP service in your application's subgraph, it automatically adds a GraphQL schema for user management. This enables you to manage IdP users directly through GraphQL operations, providing a programmatic interface for user administration.

### Registering IdP as a Subgraph

To enable GraphQL user management, include the IdP service in your application's subgraphs configuration:

```typescript
import { defineIdp } from "@tailor-platform/sdk";

export const builtinIdp = defineIdp("builtin-idp", {
  clientId: "your-client-id",
  oidcConfiguration: {
    issuer: "https://your-builtin-idp-provider-url",
  },
});
```

### Available GraphQL Operations

Once registered, the IdP subgraph provides the following GraphQL operations for user management:

**Query Operations:**

* `_users` - List IdP users with pagination and filtering
* `_user` - Get a specific IdP user by ID
* `_userBy` - Get a specific IdP user by ID or name
* `_requestMfaSettingsUrl` - Request a one-time URL to the IdP-hosted MFA settings page. Available when `enableMfa` is `true`. See [Multi-Factor Authentication (TOTP)](#multi-factor-authentication-totp).

**Mutation Operations:**

* `_createUser` - Create a new IdP user
* `_updateUser` - Update an existing IdP user
* `_deleteUser` - Delete an IdP user
* `_sendPasswordResetEmail` - Send a password reset email to an IdP user
* `_unenrollMfa` - Remove a single MFA factor from a user. Available when `enableMfa` is `true`. See [Multi-Factor Authentication (TOTP)](#multi-factor-authentication-totp).

### GraphQL Examples

Here are practical examples of user management operations:

**Query all IdP users:**

```graphql
query GetUsers {
  _users(first: 10) {
    edges {
      node {
        id
        name
        createdAt
        disabled
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    totalCount
  }
}
```

**Query IdP users with filtering:**

```graphql
query GetUsersByName {
  _users(first: 5, query: { names: ["john.doe", "jane.smith"] }) {
    edges {
      node {
        id
        name
        disabled
      }
    }
  }
}
```

**Get a specific IdP user:**

```graphql
query GetUser($userId: ID!) {
  _user(id: $userId) {
    id
    name
    createdAt
    disabled
  }
}
```

**Get an IdP user by ID or name:**

The `_userBy` query allows you to fetch a single user by exactly one of `id` or `name`. Exactly one argument must be provided — specifying both or neither returns an error.

```graphql
# By ID
query GetUserById {
  _userBy(id: "user-uuid") {
    id
    name
    createdAt
    disabled
  }
}

# By name
query GetUserByName {
  _userBy(name: "foo@example.com") {
    id
    name
    createdAt
    disabled
  }
}
```

**Create a new IdP user:**

```graphql
mutation CreateUser($input: _CreateUserInput!) {
  _createUser(input: $input) {
    id
    name
    createdAt
    disabled
  }
}
```

Variables:

```json
{
  "input": {
    "name": "john.doe",
    "password": "secure-password-123",
    "disabled": false
  }
}
```

**Update an IdP user:**

```graphql
mutation UpdateUser($input: _UpdateUserInput!) {
  _updateUser(input: $input) {
    id
    name
    disabled
  }
}
```

Variables:

```json
{
  "input": {
    "id": "user-id-here",
    "name": "john.doe.updated",
    "disabled": true
  }
}
```

**Delete an IdP user:**

```graphql
mutation DeleteUser($userId: ID!) {
  _deleteUser(id: $userId)
}
```

**Send a password reset email:**

This mutation sends a password reset email to an IdP user. It can be used both for resetting existing IdP users' passwords and for setting initial passwords for newly created IdP users.

```graphql
mutation SendPasswordResetEmail($input: _SendPasswordResetEmailInput!) {
  _sendPasswordResetEmail(input: $input)
}
```

Variables:

```json
{
  "input": {
    "userId": "user-id-here",
    "redirectUri": "https://your-app.com/reset-password-complete",
    "fromName": "My App Support",
    "subject": "Password Reset for Your My App Account"
  }
}
```

**Input fields:**

* `userId` (ID!, required) — The ID of the user to send the password reset email to.
* `redirectUri` (String!, required) — The URL to redirect the user to after they reset their password. Must be a valid absolute URL with `http` or `https` scheme.
* `fromName` (String, optional) — Overrides the sender display name for this email. When omitted, falls back to the namespace-level `emailConfig.fromName`, then to `"Tailor Platform IdP"`.
* `subject` (String, optional) — Overrides the email subject line for this email. When omitted, falls back to the namespace-level `emailConfig.passwordResetSubject`, then to the localized default.

Password reset emails are sent from `no-reply@idp.erp.dev`. This operation is only available when `use_non_email_identifier` is set to `false` (the default), as it requires users to have email addresses.

User management operations are available only when the IdP service is registered as a subgraph in your application configuration. The GraphQL schema is automatically generated based on the IdP service specification.

## Next Steps

* [Configure user roles and permissions](/guides/tailordb/permission)
* [Set up machine users for API access](/guides/auth/overview#machineuser)
* [Learn about Auth as a subgraph](/guides/auth/overview#authasasubgraph)

---

---
url: https://docs.tailor.tech/guides/auth/integration/entra-id.md
---

# Microsoft Entra ID Integration

Microsoft Entra ID (formerly Azure Active Directory) is Microsoft's cloud-based identity and access management service. This guide walks you through setting up Microsoft Entra ID as your Identity Provider with the Tailor Platform Auth service using OIDC.

## Prerequisites

* An active Microsoft Entra ID tenant with admin privileges
* A Tailor Platform workspace with Auth service enabled
* Basic understanding of OIDC protocols

## Setting up Microsoft Entra ID for OIDC

### Step 1: Register an Application in Entra ID

1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com/)
2. Navigate to **App registrations**
3. Click **New registration**
4. Configure your application:
   * **Name**: Your application name (e.g., "Tailor Platform App")
   * **Supported account types**: Choose based on your requirements
     * **Accounts in this organizational directory only** (Single tenant)
     * **Accounts in any organizational directory** (Multi-tenant)
   * **Redirect URI**: Select **Web** and add:
     ```
     https://{your-app-domain}/oauth2/callback
     ```
5. Click **Register**

### Step 2: Configure Application Settings

After registration, configure the following settings:

**Authentication:**

1. Go to **Authentication** in the left menu
2. Under **Redirect URIs**, ensure your callback URL is correctly configured
3. Select **Settings** tab, for **Implicit grant and hybrid flows**, enable:
   * **ID tokens** (used for sign-in)
4. Click **Save**

**Certificates & secrets:**

1. Go to **Certificates & secrets** in the left menu
2. Click **New client secret**
3. Add a description and choose expiration period
4. Click **Add** and copy the secret value immediately

### Step 3: Get Application Information

Note down the following information from the **Overview** page:

* **Application (client) ID**: Your client ID
* **Directory (tenant) ID**: Your tenant ID
* **Client secret**: The secret value you created

### Step 4: Configure API Permissions (Optional)

If you need additional user information:

1. Go to **API permissions**
2. Click **Add a permission**
3. Select **Microsoft Graph**
4. Choose **Delegated permissions**
5. Add permissions like:
   * `User.Read` (to read user profile)
   * `email` (to access email address)
   * `profile` (to access basic profile information)
6. Click **Grant admin consent** if required

## Configuring Auth Service

Once your Entra ID application is set up, configure the Auth service in your Tailor Platform application:

```typescript
import { defineAuth, defineIdp } from "@tailor-platform/sdk";
import { user } from "./tailordb/user";

// Define the Entra ID OIDC IdP
export const entraIdOidc = defineIdp("entra-id-oidc", {
  clientId: process.env.ENTRA_ID_CLIENT_ID,
  clientSecret: process.env.ENTRA_ID_CLIENT_SECRET,
  oidcConfiguration: {
    issuer: "https://login.microsoftonline.com/{tenant-id}/v2.0",
  },
});

// Configure Auth service to use Entra ID
export const auth = defineAuth("main-auth", {
  userProfile: {
    type: user,
    usernameField: "email",
    attributes: {
      email: true,
      firstName: true,
      lastName: true,
    },
  },
  idProvider: entraIdOidc.provider("entra-id-oidc-provider"),
});
```

## Testing the Integration

After configuring both Entra ID and the Auth service:

1. Deploy your Tailor Platform application
2. Create users in Entra ID and add them to the Tailor platform
3. Login to your application using the Tailor CLI
4. You should be redirected to Microsoft Entra ID for authentication
5. After successful authentication, you'll be redirected back to your application

## Troubleshooting

### Common Issues

**Invalid Redirect URI**

* Ensure the redirect URI in Entra ID matches exactly what's configured in your Auth service
* Check for trailing slashes and protocol mismatches (http vs https)

**Invalid Client Credentials**

* Verify your client ID and client secret are correct
* Ensure the client secret hasn't expired
* Check that the secret is properly stored in your secret manager

**Tenant Configuration Issues**

* Verify the tenant ID in your provider URL is correct
* For multi-tenant apps, ensure you're using the correct tenant endpoint
* Check that the application is properly registered in the correct tenant

**User Profile Not Created**

* Check that your TailorDB User type has the correct username field configured
* Verify that the email claim is being passed from Entra ID
* Ensure the user has the necessary permissions in Entra ID

**Token Validation Errors**

* Verify the audience claim in the token matches your application
* Check that the issuer claim matches the expected Entra ID issuer
* Ensure your application's clock is synchronized

For production deployments, ensure you're using HTTPS URLs and have proper SSL certificates configured. Also, consider implementing proper token caching and refresh mechanisms.

## Next Steps

* [Log in to your app](/guides/auth/app-login) - Guide for user creation and login
* [Configure user roles and permissions](/guides/tailordb/permission)
* [Set up machine users for API access](/guides/auth/overview#machineuser)
* [Learn about Auth as a subgraph](/guides/auth/overview#authasasubgraph)

---

---
url: https://docs.tailor.tech/guides/auth/integration/google-workspace.md
---

# Google Workspace Integration&#x20;

Google Workspace (formerly G Suite) is Google's cloud-based productivity and collaboration platform. This guide shows how to integrate Google Workspace with the Tailor Platform Auth service for enterprise SSO using SAML.

## Prerequisites

* Google Workspace admin account
* A Tailor Platform workspace with Auth service enabled
* Basic understanding of SAML protocols

## Setting up Google Workspace for SAML

### Step 1: Access Admin Console

1. Sign in to the [Google Admin Console](https://admin.google.com/)
2. Navigate to **Apps** > **Web and mobile apps**
3. Click **Add app** > **Add custom SAML app**

### Step 2: Configure SAML Application

**App details:**

* **App name**: Your application name
* **Description**: Brief description
* **App icon**: Upload your application logo (optional)

**Google Identity Provider details:**

* Download the metadata XML file from Google (you'll need this for the Auth service configuration)

**Service Provider details:**

* **ACS URL**:
  ```
  https://{your-app-domain}/oauth2/callback
  ```
* **Entity ID**:
  ```
  https://api.tailor.tech/saml/{workspace_id}/{auth_namespace}/metadata.xml
  ```
* **Name ID format**: EMAIL
* **Name ID**: Basic Information > Primary email

### Step 3: Configure Attribute Mapping

Map Google Workspace attributes to your application:

| Google Directory attributes | App attributes |
| --------------------------- | -------------- |
| Primary email               | email          |
| First name                  | firstName      |
| Last name                   | lastName       |

## Configuring Auth Service

To configure the Auth service, you’ll need to download the Google Workspace IdP metadata XML. You can either:

* **Use the metadata URL**: Google provides a metadata URL that can be used directly in the configuration
* **Use the raw XML metadata**: Download the XML and provide it as an environment variable (e.g., `process.env.GOOGLE_SAML_METADATA`)

### Configuration

```typescript
import { defineAuth, defineIdp } from "@tailor-platform/sdk";
import { user } from "./tailordb/user";

// Define the Google Workspace SAML IdP
export const googleSaml = defineIdp("google-saml", {
  clientId: "your-client-id",
  samlConfiguration: {
    metadataUrl: "https://accounts.google.com/o/saml2?idpid={your-idp-id}",
    // Or provide the XML metadata directly:
    // rawMetadata: process.env.GOOGLE_SAML_METADATA,
  },
});

// Configure Auth service to use Google SAML
export const auth = defineAuth("main-auth", {
  userProfile: {
    type: user,
    usernameField: "email",
    attributes: {
      email: true,
      firstName: true,
      lastName: true,
    },
  },
  idProvider: googleSaml.provider("google-saml-provider"),
});
```

## Domain Verification

For Google Workspace SAML integration, you may need to verify domain ownership:

1. In Google Admin Console, go to **Security** > **Set up single sign-on (SSO)**
2. Add your application domain to the verified domains list
3. Follow Google's domain verification process

## Troubleshooting

### Common Issues

**Domain Not Verified**

* Complete Google's domain verification process
* Ensure DNS records are properly configured

**SAML Assertion Errors**

* Verify Entity ID matches exactly
* Ensure user has access to the application

## Next Steps

* [Log in to your app](/guides/auth/app-login) - Guide for user creation and login
* [Configure user roles and permissions](/guides/tailordb/permission)
* [Set up machine users for API access](/guides/auth/overview#machineuser)
* [Learn about Auth as a subgraph](/guides/auth/overview#authasasubgraph)

---

---
url: https://docs.tailor.tech/guides/auth/integration/okta.md
---

# Okta Integration

Okta is an enterprise-grade identity and access management platform that provides secure authentication and authorization services. This guide walks you through setting up Okta as your Identity Provider with the Tailor Platform Auth service.

## Prerequisites

* An active Okta account with admin privileges
* A Tailor Platform workspace with Auth service enabled
* Basic understanding of OIDC or SAML protocols

## Setting up Okta for OIDC

### Step 1: Create an Application in Okta

1. Log in to your Okta Admin Console
2. Navigate to **Applications** > **Applications**
3. Click **Create App Integration**
4. Select **OIDC - OpenID Connect** as the sign-in method
5. Choose **Web Application** as the application type
6. Click **Next**

### Step 2: Configure Application Settings

Configure your application with the following settings:

* **App integration name**: Your application name (e.g., "Tailor Platform App")
* **Grant type**: Select **Authorization Code**
* **Sign-in redirect URIs**: Add your callback URL
  ```
  https://{your-app-domain}/oauth2/callback
  ```
* **Sign-out redirect URIs**: Add your logout URL (optional)
* **Assignments**: Choose who can access this application

### Step 3: Get Application Credentials

After creating the application, note down:

* **Client ID**: Found in the application's General tab
* **Client Secret**: Found in the application's General tab
* **Okta Domain**: Your Okta organization URL (e.g., `https://dev-12345.okta.com`)

## Setting up Okta for SAML

### Step 1: Create a SAML Application

1. In Okta Admin Console, go to **Applications** > **Applications**
2. Click **Create App Integration**
3. Select **SAML 2.0** as the sign-in method
4. Click **Next**

### Step 2: Configure SAML Settings

**General Settings:**

* **App name**: Your application name
* **App logo**: Upload your application logo (optional)

**SAML Settings:**

* **Single sign on URL**:
  ```
  https://{your-app-domain}/oauth2/callback
  ```
* **Audience URI (SP Entity ID)**:
  ```
  https://api.tailor.tech/saml/{workspace_id}/{auth_namespace}/metadata.xml
  ```
* **Name ID format**: EmailAddress
* **Application username**: Email

### Step 3: Configure Attribute Statements

Add attribute statements to map Okta user attributes to your application:

| Name      | Name format | Value          |
| --------- | ----------- | -------------- |
| email     | Basic       | user.email     |
| firstName | Basic       | user.firstName |
| lastName  | Basic       | user.lastName  |

## Configuring Auth Service

Once your Okta application is set up, configure the Auth service in your Tailor Platform application:

```typescript
import { defineAuth, defineIdp } from "@tailor-platform/sdk";
import { user } from "./tailordb/user";

// OIDC Configuration
export const oktaOidc = defineIdp("okta-oidc", {
  clientId: process.env.OKTA_CLIENT_ID,
  clientSecret: process.env.OKTA_CLIENT_SECRET,
  oidcConfiguration: {
    issuer: "https://{your-okta-domain}",
  },
});

// SAML Configuration (alternative)
export const oktaSaml = defineIdp("okta-saml", {
  clientId: "your-client-id",
  samlConfiguration: {
    metadataUrl: "https://{your-okta-domain}/app/{app_id}/sso/saml/metadata",
  },
});

// Configure Auth service to use Okta (choose OIDC or SAML)
export const auth = defineAuth("main-auth", {
  userProfile: {
    type: user,
    usernameField: "email",
    attributes: {
      email: true,
      firstName: true,
      lastName: true,
    },
  },
  // Use either OIDC or SAML IdP
  idProvider: oktaOidc.provider("okta-oidc-provider"),
  // idProvider: oktaSaml.provider("okta-saml-provider"),
});
```

## Testing the Integration

After configuring both Okta and the Auth service:

1. Deploy your Tailor Platform application
2. Login to your application using the Tailor CLI
3. You should be redirected to Okta for authentication
4. After successful authentication, you'll be redirected back to your application

## Troubleshooting

### Common Issues

**Invalid Redirect URI**

* Ensure the redirect URI in Okta matches exactly what's configured in your Auth service
* Check for trailing slashes and protocol mismatches

**Metadata URL Not Found**

* Verify your Okta domain and application ID in the metadata URL
* Ensure the SAML application is active and properly configured

**User Profile Not Created**

* Check that your TailorDB User type has the correct username field configured
* Verify that the email attribute is being passed from Okta

For production deployments, ensure you're using HTTPS URLs and have proper SSL certificates configured.

## Next Steps

* [Log in to your app](/guides/auth/app-login) - Guide for user creation and login
* [Configure user roles and permissions](/guides/tailordb/permission)
* [Set up machine users for API access](/guides/auth/overview#machineuser)
* [Learn about Auth as a subgraph](/guides/auth/overview#authasasubgraph)

---

---
url: https://docs.tailor.tech/guides/integration/overview.md
---

# Integration Guides for Tailor Platform

Tailor Platform seamlessly connects with leading business applications to automate your inventory, accounting, shipping, and returns management.

Using [triggers](/guides/executor/overview#trigger), data flows automatically between systems – ensuring your inventory, orders, and financial data stay synchronized across all connected applications.

This automated synchronization eliminates manual data entry and reduces errors, letting you focus on growing your business.

## What you'll learn

In this guide, you'll learn how to integrate Tailor Platform with Shopify, QuickBooks, ShipStation, Loop, Claude, and Claude Code.

* [Shopify using third-party integration tools](/guides/integration/pipedream-shopify) like [Zapier](https://zapier.com/) or [Pipedream](https://pipedream.com/)
* [Shopify through direct integration](/guides/integration/shopify) using triggers
* [QuickBooks](/guides/integration/quickbooks)
* [ShipStation](/guides/integration/shipstation)
* [Loop](/guides/integration/loopreturns)
* [Claude and Claude Code](/guides/integration/claude) via a remote MCP server

---

---
url: https://docs.tailor.tech/guides/integration/claude.md
---

# Integrate Claude and Claude Code with Tailor Platform&#x20;

## Overview

Claude supports [custom connectors using remote MCP](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp), and [Claude Code](https://docs.claude.com/en/docs/claude-code) supports remote [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) servers via `claude mcp add`.

Tailor Platform exposes a remote MCP server for each application (currently in preview), allowing Claude and Claude Code to execute GraphQL queries and mutations against your application's Dataplane on behalf of an authenticated user.

By registering your Tailor PF app as a remote MCP server in Claude or Claude Code, you can let them read and write your application data through the same OAuth2-authenticated GraphQL API used by your other clients.

## Prerequisites

* A deployed Tailor PF application reachable at `https://{YOUR_APP_SUBDOMAIN}.erp.dev`
* For Claude: a Claude account that can add a custom connector. On Team and Enterprise plans, only an **Owner** or **Primary Owner** can add custom connectors to the organization. On Pro and Max plans, the individual user adds connectors from **Customize > Connectors**.
* For Claude Code: the `claude` CLI installed locally

## 1. Create an OAuth2 Client

Both Claude and Claude Code initiate an OAuth2 authorization code flow against your Tailor PF app, so you need to register an OAuth2 client dedicated to them in your Auth configuration. The two products use different redirect URIs, so you can register them on a single client to support both.

Use the following settings:

| Setting        | Value                                                                                                                                                       |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clientType`   | `public` (Claude and Claude Code are public clients and cannot securely store a client secret)                                                              |
| `requireDPoP`  | `false` (Claude's and Claude Code's MCP clients do not support DPoP)                                                                                        |
| `redirectURIs` | `https://claude.ai/api/mcp/auth_callback` for Claude, and `http://localhost:3000/oauth/callback` for Claude Code (the port matches `--callback-port` below) |
| `grantTypes`   | `authorization_code`, `refresh_token`                                                                                                                       |

Add the client to your `defineAuth` configuration:

```typescript
import { defineAuth } from "@tailor-platform/sdk";

export const authConfig = defineAuth("my-auth", {
  oauth2Clients: {
    "claude-connector": {
      description: "OAuth2 client for Claude and Claude Code",
      clientType: "public",
      requireDPoP: false,
      redirectURIs: [
        // For Claude (custom connector)
        "https://claude.ai/api/mcp/auth_callback",
        // For Claude Code (`claude mcp add ... --callback-port 3000`)
        "http://localhost:3000/oauth/callback",
      ],
      grantTypes: ["authorization_code", "refresh_token"],
    },
  },
});
```

Deploy the configuration:

```bash
npm run deploy -- --workspace-id <your-workspace-id>
```

After deployment, look up the issued `CLIENT_ID` with the SDK CLI:

```bash
tailor oauth2client list
```

```bash
+---------------+-----------------------------------------------------+
| NAME          | claude-connector                                    |
| DESCRIPTION   | OAuth2 client for Claude and Claude Code            |
| GRANT_TYPES   | authorization_code,refresh_token                    |
| REDIRECT_URIS | https://claude.ai/api/mcp/auth_callback,            |
|               | http://localhost:3000/oauth/callback                |
| CLIENT_ID     | <client_id>                                         |
+---------------+-----------------------------------------------------+
```

Keep the `CLIENT_ID` value for the next step.

## 2. Register the Remote MCP Server

Pick the section that matches the product you want to use.

### 2a. Claude (custom connector)

Following [Get started with custom connectors using remote MCP](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp):

1. Open the connectors page in Claude.
   * **Team and Enterprise plans**: an Owner or Primary Owner navigates to **Organization settings > Connectors**.
   * **Pro and Max plans**: navigate to **Customize > Connectors**.
2. Click **+**, then **Add custom connector**.
3. Enter the **remote MCP server URL**: `https://{YOUR_APP_SUBDOMAIN}.erp.dev/mcp` (replace `{YOUR_APP_SUBDOMAIN}` with the subdomain of your deployed Tailor PF application).
4. Click **Advanced settings** and set the **OAuth Client ID** to the `CLIENT_ID` issued for the `claude-connector` OAuth2 client in the previous step. Leave **OAuth Client Secret** empty (the OAuth2 client is a public client and has no secret).
5. Save the connector.

Claude uses the `https://claude.ai/api/mcp/auth_callback` redirect URI registered on the OAuth2 client.

### 2b. Claude Code (`claude mcp add`)

Run the following command to add the remote MCP server to Claude Code:

```bash
claude mcp add --transport http <mcp-name> https://{YOUR_APP_SUBDOMAIN}.erp.dev/mcp \
  --client-id <CLIENT_ID> \
  --callback-port 3000
```

* `<mcp-name>` is a local name for the server (e.g., `my-app`).
* `<CLIENT_ID>` is the `CLIENT_ID` issued for the `claude-connector` OAuth2 client.
* `--callback-port 3000` makes Claude Code use `http://localhost:3000/oauth/callback` as the redirect URI, which must match one of the redirect URIs registered on the OAuth2 client.

## 3. Use the Remote MCP Server

The first time Claude or Claude Code calls a tool on the server, it triggers an OAuth2 authorization code flow against your Tailor PF app. After you sign in and grant access, the client receives an access token and can call MCP tools backed by your application's GraphQL endpoint to run queries and mutations on your behalf.

Because the connection uses the authenticated user's access token, all existing TailorDB type permissions and authorization rules apply to operations executed by Claude or Claude Code.

---

---
url: https://docs.tailor.tech/guides/integration/loopreturns.md
---

# Integrate Loop with Tailor Platform

## Overview

[Loop](https://docs.loopreturns.com/welcome) is a leading platform designed to simplify returns and exchanges, helping merchants streamline the post-purchase experience while reducing the operational burden of managing returns.

The integration of the Tailor Platform with Loop enables businesses to synchronize orders and product catalogs for efficient return processing.
It also allows automation of key tasks such as return approvals, shipping label generation, and restocking, significantly saving time for merchants.

## Tailor Platform Triggers

You can integrate Loop with Tailor Platform using triggers. Refer to [executor service guide](/guides/executor/overview) to learn about different types of triggers.

## Connect Loop

This integration guide will walk you through the steps to set up a connection between Tailor PF and Loop.

### 1. Get the API key

Before you can begin integrating the Tailor Platform with Loop, you'll need to get an API key.

To get your API key, follow the below steps:

1. Create an account with Loop

This is a prerequisite to access the Loop admin portal.

2. Connect your store (e.g., your Shopify store)

Integrating your store is essential for managing returns through Loop.

3. Set Up Return Portal URL

This URL is essential for directing customers to the correct page for processing returns.

4. Navigate to `Returns management` and select `Tools & integrations`.

5. Within `Tools & integrations`, select `Developer tools`.

In the Developer tools section, you can generate and manage your API keys. To generate a new API key, click on `Generate API Key`.

![Integration Guide – Loop API](../assets/loopreturns/loop-api-key-gen.png)

6. Select the desired scopes

Select the scope and then click `Generate`.

![Integration Guide – Loop API](../assets/loopreturns/loop-api-key.png)

### 2. Store Loop Credentials

Store your Loop API key as a secret in the Tailor PF using one of the following methods:

#### Using the Tailor CLI

1. Create a vault to store the API key

Run the following commands to create a vault named loop-vault and to store the secret key.

```bash
tailor secret vault create loop-vault
tailor secret create --vault-name loop-vault --name loop-key --value {$api_key}
```

#### Through the Console

1. Navigate to your workspace where the app is deployed and select `settings` tab to add the secret

![Integration Guide – Add Secret](../assets/loopreturns/console-loop-add-secret.png)

2. Create a new vault and add the API key

![Integration Guide – Create Vault](../assets/loopreturns/console-loop-create-vault.png)

### 3. Making API requests to loop API

You can call the [Loop APIs](https://docs.loopreturns.com/api-reference/latest/return-actions/process-return) using triggers.

---

---
url: https://docs.tailor.tech/guides/integration/pipedream-shopify.md
---

# Integration Guides for Tailor Platform

If you already have a SaaS application and want to integrate it with Tailor Platform, you can use integration tools
like [Zapier](https://zapier.com/) or [Pipedream](https://pipedream.com/).
In this guide, we will explain how to integrate Tailor Platform with Shopify as an example of a SaaS application.

## Overview of Integration

When using integration tools, you need to create a trigger and an action. Triggers are events that occur in other SaaS applications, and actions are the subsequent steps, such as parsing data from triggers and sending API requests.

Assuming you have a Shopify store and you want to integrate it with Tailor Platform, a typical scenario would be to create a trigger when a new order is created in Shopify and forward this order data to Tailor Platform to manage orders or inventory.

Here's our integration demo with Shopify based on the scenario above:

## Details of Integration Settings

To integrate with Tailor Platform, you need to execute a login mutation to obtain an access token and use it for subsequent requests.\
Major integration tools like Zapier and Pipedream have features to execute JavaScript code in actions, so you can create a login mutation code in the action.

Pipedream is a bit more developer-friendly than Zapier, as executing JavaScript code is included in the free plan, and you can import npm packages.

Here's a video explaining the details of integration settings when using Pipedream:

---

---
url: https://docs.tailor.tech/guides/integration/quickbooks.md
---

# Integrate QuickBooks with Tailor Platform

## Overview

QuickBooks is an accounting software that provides comprehensive financial management tools, including invoicing, expense tracking, payroll processing, and financial reporting.
Integrate the [QuickBooks API](https://developer.intuit.com/app/developer/qbo/docs/get-started) into your applications to automate workflows and streamline financial management processes.

In this guide, we will explain how to integrate QuickBooks with Tailor Platform by leveraging the platform's powerful triggers.

## Tailor Platform Triggers

You can integrate QuickBooks with Tailor Platform using triggers. Refer to [executor service guide](/guides/executor/overview) to learn about different types of triggers.

## Connect QuickBooks

This integration guide will walk you through the steps to set up a connection between Tailor PF and QuickBooks.

### Prerequisites

Before you begin integrating with the QuickBooks API, you'll need to:

1. Create an [Intuit Developer account](https://developer.intuit.com/app/developer/homepage)

2. Create a workspace

3. Create a new app

* Choose an app name
* Add required permissions (e.g., `com.intuit.quickbooks.accounting`)

### 1. Getting Your Access Token

QuickBooks uses OAuth 2.0 for API authentication. Follow these steps to get your access token:

1. Log in to your QuickBooks account

2. Select `My Hub` from the option menu and click `Playground` to access the authentication testing environment

![QuickBooks Integration Guide – Select Playground](../assets/quickbooks/select-playground.png)

The `Playground` is a testing environment that helps you understand the OAuth 2.0 flow and obtain your access token.

Follow these steps in the `Playground` to generate your authentication credentials.

1. Get Authorization Code

* Select your workspace

* Select your app

* The Client ID and Client Secret will be automatically loaded

* Configure OAuth settings:
  * Select the scope com.intuit.quickbooks.accounting

* Click the `Get authorization code` button

2. Get OAth 2.0 token from auth code

* In this section the authorization code and Realm ID will be pre-loaded automatically

* Click the `Get tokens` button

![QuickBooks Integration Guide – Get Token](../assets/quickbooks/console-quickbooks-get-token.png)

### 2. Store QuickBooks Credentials

Store your QuickBooks access token as a secret in the Tailor PF using one of the following methods:

#### Using the Tailor CLI

1. Create a vault to store the API key

Run the following commands to create a vault named quickbooks-vault and to store the secret key.

```bash
tailor secret vault create quickbooks-vault
tailor secret create --vault-name quickbooks-vault --name quickbooks-key --value {$access_token}
```

#### Through the Console

1. Navigate to your workspace where the app is deployed and select `settings` tab to add the secret

![QuickBooks Integration Guide – Add Secret](../assets/quickbooks/console-quickbooks-add-secret.png)

2. Create a new vault and add the access token

![QuickBooks Integration Guide – Create Vault](../assets/quickbooks/console-quickbooks-create-vault.png)

### 3. Making API Requests to QuickBooks

You can call the [QuickBooks APIs](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/account) using triggers.

#### Base URL

All API requests should be made to the following base URL:

* Production: `https://quickbooks.api.intuit.com/v3/company/<realmId>`

* Sandbox: `https://sandbox-quickbooks.api.intuit.com/v3/company/<realmId>`

---

---
url: https://docs.tailor.tech/guides/integration/shipstation.md
---

# Integrate ShipStation with Tailor Platform

## Overview

[ShipStation](https://www.shipstation.com/docs/api/) is a powerful shipping software solution designed to simplify and optimize order fulfillment for e-commerce businesses of all sizes.

The integration of Tailor Platform and ShipStation enables businesses to synchronize inventory, automate order processing, and streamline shipping workflows, ensuring real-time data exchange while reducing manual effort.

## Tailor Platform Triggers

You can integrate ShipStation with Tailor Platform using triggers. Refer to [executor service guide](/guides/executor/overview) to learn about different types of triggers.

## Connect ShipStation

This integration guide will walk you through the steps to set up a connection between Tailor PF and ShipStation.

### 1. Get the API key

Before you can begin integrating the Tailor Platform with ShipStation, you'll need to get an API key.

1. Log in to your ShipStation account.

2. From the top navigation bar, select `Add-Ons`.

3. Enable the `Shipping API` to generate the API keys.

![Integration Guide – ShipStation API Add-on](../assets/shipstation/shipstation-api-addon.png)

4. Navigate to `Account` and select `API Settings`.

Choose the `API version` and click `Generate API Key`.

![Integration Guide – ShipStation API](../assets/shipstation/shipstation-api-key.png)

Production API Key: Actions performed using a production API key may result in charges. Therefore, it is not advisable to use these keys for development or testing purposes.

Sandbox API Key: These keys are intended for development and testing. Sandbox keys are easily identifiable as they always begin with TEST\_. However, please note that the ShipStation API v2 sandbox environment is not currently available.

### 2. Store ShipStation Credentials

Store your ShipStation API key as a secret in the Tailor PF using one of the following methods:

#### Using the Tailor CLI

1. Create a vault to store the API key

Run the following commands to create a vault named shipstation-vault and to store the secret key.

```bash
tailor secret vault create shipstation-vault
tailor secret create --vault-name shipstation-vault --name shipstation-key --value {$api_key}
```

#### Through the Console

1. Navigate to your workspace where the app is deployed and select `settings` tab to add the secret

![Integration Guide – Add Secret](../assets/shipstation/console-shipstation-add-secret.png)

2. Create a new vault and add the API key

![Integration Guide – Create Vault](../assets/shipstation/console-shipstation-create-vault.png)

### 3. Making API requests to ShipStation API

You can call the [ShipStation APIs](https://docs.shipstation.com/openapi) using triggers.

---

---
url: https://docs.tailor.tech/guides/integration/shopify.md
---

# Integrate Shopify with Tailor Platform

In this guide, we will explain how to integrate Shopify with Tailor Platform by leveraging the platform's powerful triggers.

## Tailor Platform Triggers

You can integrate Shopify with Tailor Platform using triggers. Refer to [executor service guide](/guides/executor/overview) to learn about different types of triggers.

## Automatically push new products to your Shopify store

When you create a new product in the TailorDB, you may want to seamlessly sync that data with your Shopify store.
This integration guide will walk you through the steps to set up a connection between Tailor PF and Shopify, ensuring that every time a new product is added to the TailorDB, it's automatically pushed to your Shopify storefront.

### 1. Get the API key

Before you can begin integrating the Tailor Platform with Shopify, you'll need to obtain an API key. This unique key serves as an authentication credential, enabling the Tailor Platform to securely communicate with your Shopify store.

To get your API key, follow the below steps:

1. Login to your Shopify store and select `Settings`.

![Guide – Log in to Shopify](../assets/shopify/shopify-admin-page.png)

2. In the `Settings` page, select `Apps and sales channels` and click on `Develop apps`.

![Guide – Shopify settings](../assets/shopify/shopify-develop-apps.png)

3. Click `Create an app`, enter the app name and create app.

![Guide – Shopify settings](../assets/shopify/shopify-create-app.png)

4. After creating the app, configure the Admin API integration.

Check all the necessary items; at a minimum, ensure that Products R/W is checked. After making all the selections, click `Save`.

![Guide – Shopify Admin API configuration](../assets/shopify/shopify-app-admin-API-configuration.png)

5. Install the created app

Click the "Install app" button and follow any additional prompts to complete the installation.

![Guide – Shopify install app](../assets/shopify/shopify-install-app.png)

6. Click on "Reveal Token Once" to save your access token

![Guide – Shopify API key](../assets/shopify/shopify-api-key.png)

Treat your API key as a sensitive data and never share it publicly or commit it to version control systems. The API key grants access to your Shopify store data, so it's essential to keep it secure.

### 2. Create a trigger to push the product to your Shopify Store

Follow the below steps to create an event based trigger.

1. Enable `PublishRecordEvents` settings in the `Products` table

To enable event publishing for Product records, add the `publishRecordEvents` feature to your Product type:

```typescript {{ title: 'tailordb/product.ts' }}
import { db } from "@tailor-platform/sdk";

export const product = db
  .table("Product", "Product data schema", {
    name: db.string().description("Product name"),
    description: db.string().description("Product description"),
    // ... other fields
  })
  .features({
    publishRecordEvents: true,
  });
```

2. Create a vault to store the API key

Run the following commands to create a vault named `shopify-vault` and to store the secret key.

```bash
tailor secret vault create shopify-vault
tailor secret create --vault-name shopify-vault --name shopify-key --value {$your_API_key}
```

3. Add the trigger

Below is an example of the trigger that will push new product to Shopify store when a product is added to the TailorDB.

```typescript {{ title: 'executors/shopify-sync.ts' }}
import { createExecutor, recordCreatedTrigger } from "@tailor-platform/sdk";
import { product } from "../tailordb/product";

export default createExecutor({
  name: "shopify-product-sync",
  description: "Push new products to Shopify when created in TailorDB",
  trigger: recordCreatedTrigger({
    type: product,
    condition: ({ newRecord }) => !!newRecord.name && !!newRecord.description,
  }),
  operation: {
    kind: "webhook",
    url: "https://YOUR_STORE.myshopify.com/admin/api/2024-01/products.json",
    method: "POST",
    headers: {
      "X-Shopify-Access-Token": "{{secret.shopify-vault.shopify-key}}",
      "Content-Type": "application/json",
    },
    body: (context) => ({
      product: {
        title: context.event.newRecord.name,
        body_html: context.event.newRecord.description,
        vendor: "Your Store",
        product_type: "General",
      },
    }),
  },
});
```

4. Deploy the changes

Run the following command to deploy your executor:

```bash
npx tailor deploy
```

5. Verify the trigger

Run the following query to create a new product.

```
mutation {
  createProduct(input: { description: "Comfortable antibacterial shirt", name: "Linen shirt 1"}) {
    id
  }
}
```

After running the above mutation, you can see that the product is automatically pushed to your Shopify store.

![Guide – Shopify verify new product](../assets/shopify/shopify-verify-trigger.png)

See [Event based triggers](/tutorials/setup-executor/event-based-trigger) to learn more.

## Get notification from Shopify on new Product creation

To get notifications about particular events in the store, you can use incoming webhook trigger in the Tailor Platform.

Here's a step-by-step guide on how to set up an incoming webhook trigger in the Tailor Platform to receive notifications.

### 1. Create an Incoming Webhook Trigger

Follow the steps below to create an incoming webhook trigger

1. Add an incoming webhook trigger in the executor configuration

```typescript {{ title: 'executors/shopify-webhook.ts' }}
import { createExecutor, incomingWebhookTrigger } from "@tailor-platform/sdk";

export default createExecutor({
  name: "shopify-webhook-handler",
  description: "Handle Shopify product creation webhook",
  trigger: incomingWebhookTrigger(),
  operation: {
    kind: "tailorGraphql",
    query: `
      mutation createProduct($input: createProductInput!) {
        createProduct(input: $input) {
          id
          name
        }
      }
    `,
    variables: (context) => ({
      input: {
        name: context.body.product.title,
        description: context.body.product.body_html,
      },
    }),
  },
});
```

2. Deploy the executor

```bash
npx tailor deploy
```

3. Get the webhook URL

After deployment, get your webhook URL:

```bash
tailor executor list
```

You will see the webhook URL in the output which you'll use to configure Shopify.

### 2. Configure Shopify to Send Notifications

Run the command below to get the endpoint for configuring Shopify.

```bash
tailor executor webhook list
```

You will receive the following URL in response.

```bash
NAME | incomingwebhook-executor
URL  | {WEBHOOK_URL}
```

Next, to configure Shopify, follow the steps below.

1. Login to your Shopify store and select `Settings`. In the `Settings` page, select `Notifications` and click on `Webhooks`.

![Guide – Shopify notifications](../assets/shopify/shopify-notification-webhook.png)

2. Create Webhook

Choose `Product creation` event from the dropdown, paste the url constructed in step 2 and click `Save` to create the webhook.

![Guide – Shopify notifications](../assets/shopify/shopify-webhook.png)

You have now successfully created the webhook to receive notifications in the Tailor platform from the Shopify store for the Product creation event.

### 3. Verify the trigger

You can open the GraphQL playground to verify the product created in Shopify is added to TailorDB.

```bash
# Open the GraphQL playground in the browser
tailor open
```

Run the following query to view all the products.

```graphql
query {
  products {
    edges {
      node {
        id
        name
      }
    }
  }
}
```

---

---
url: https://docs.tailor.tech/guides/workflow/creating-workflows.md
---

# Creating Workflows

Workflows are defined using the Tailor Platform SDK with TypeScript. This approach provides type safety, version control, and seamless integration with other platform services.

## Directory Structure

```
  src/
  ├── workflows/
  │   ├── order-processing.ts    # Workflow definition
  │   └── steps/
  │       ├── validate-order.ts
  │       ├── check-inventory.ts
  │       └── process-payment.ts
  └── index.ts
```

## Defining Workflow Steps

In the SDK, workflow steps are defined as TypeScript functions. Each step contains its logic and is composable:

```typescript {{ title: 'workflows/steps/validate-order.ts' }}
import { WorkflowStep } from "@tailor-platform/sdk";

export const validateOrderStep: WorkflowStep = {
  name: "validate-order",
  handler: async (args) => {
    if (!args.orderId) {
      throw new Error("orderId is required");
    }
    // Validation logic
    return { validated: true, orderId: args.orderId };
  },
};
```

```typescript {{ title: 'workflows/steps/check-inventory.ts' }}
import { WorkflowStep } from "@tailor-platform/sdk";

export const checkInventoryStep: WorkflowStep = {
  name: "check-inventory",
  handler: async (args) => {
    // Inventory check logic
    return { inStock: true, orderId: args.orderId };
  },
};
```

```typescript {{ title: 'workflows/steps/process-payment.ts' }}
import { WorkflowStep } from "@tailor-platform/sdk";

export const processPaymentStep: WorkflowStep = {
  name: "process-payment",
  handler: async (args) => {
    // Payment processing logic
    return { paymentId: "pay_123", status: "completed" };
  },
};
```

## Defining Workflows

Create a workflow that composes multiple steps:

```typescript {{ title: 'workflows/order-processing.ts' }}
import { createWorkflow } from "@tailor-platform/sdk";
import { validateOrderStep } from "./steps/validate-order";
import { checkInventoryStep } from "./steps/check-inventory";
import { processPaymentStep } from "./steps/process-payment";

export const orderProcessingWorkflow = createWorkflow({
  name: "order-processing",
  steps: [validateOrderStep, checkInventoryStep, processPaymentStep],
});
```

**Properties:**

* `name` (String, Required) - Workflow name (unique within workspace)
* `steps` (Array, Required) - Array of workflow steps to execute

## Versioning

Job functions are automatically versioned:

* When a job function's script changes, a new version is created
* Unchanged scripts reuse the existing version
* Workflows can reference specific versions or always use the latest

## Managing Workflows

**List workflows:**

```bash
npx tailor workflow list
```

**Get workflow details:**

```bash
npx tailor workflow get <workflow-name>
```

**Start a workflow execution:**

```bash
npx tailor workflow start <workflow-name> --args '{"orderId": "123"}'
```

## Writing Step Functions

Workflow steps are TypeScript functions that form the building blocks of your workflow. Each step function receives input arguments and returns output:

```typescript
export const myStep: WorkflowStep = {
  name: "my-step",
  handler: async (args) => {
    // Your code here
    return { result: "success" };
  },
};
```

**Function signature:**

* **Input**: `args` object with type safety
* **Output**: JSON-serializable object
* **Async/await**: Supported for asynchronous operations

### Composing Steps

In SDK workflows, steps are executed sequentially by the workflow engine. Data flows from one step to the next:

```typescript
import { createWorkflow } from "@tailor-platform/sdk";

export const myWorkflow = createWorkflow({
  name: "my-workflow",
  steps: [
    {
      name: "step1",
      handler: async (args) => {
        return { data: "from step 1" };
      },
    },
    {
      name: "step2",
      handler: async (args) => {
        // Access output from previous step
        console.log(args.data); // "from step 1"
        return { result: "complete" };
      },
    },
  ],
});
```

### Example: Multi-step workflow

Here's a complete example showing how to compose multiple job functions:

```javascript {{ title: 'main.js' }}
export function main(args) {
  console.log("Starting workflow with orderId:", args.orderId);

  // Step 1: Fetch order data
  const order = tailor.workflow.execJobFunction("fetchOrder", {
    orderId: args.orderId,
  });

  // Step 2: Validate order
  const validated = tailor.workflow.execJobFunction("validateOrder", order);

  // Step 3: Process payment
  const payment = tailor.workflow.execJobFunction("processPayment", {
    orderId: validated.id,
    amount: validated.total,
  });

  // Step 4: Send confirmation
  tailor.workflow.execJobFunction("sendConfirmation", {
    orderId: validated.id,
    email: validated.customerEmail,
    paymentId: payment.id,
  });

  return {
    orderId: validated.id,
    paymentId: payment.id,
  };
}
```

```javascript {{ title: 'deps/fetchOrder.js' }}
export function main(args) {
  console.log("Fetching order:", args.orderId);

  // Simulate fetching from API
  return {
    id: args.orderId,
    customerEmail: "customer@example.com",
    items: [{ name: "Product A", price: 100 }],
    total: 100,
  };
}
```

```javascript {{ title: 'deps/validateOrder.js' }}
export function main(args) {
  console.log("Validating order:", args.id);

  if (!args.items || args.items.length === 0) {
    throw new Error("Order has no items");
  }

  if (!args.customerEmail) {
    throw new Error("Customer email is required");
  }

  return args; // Return validated order
}
```

### Error Handling

Throw errors to mark a job function as failed:

```javascript
export function main(args) {
  if (!args.requiredField) {
    throw new Error("requiredField is missing");
  }

  try {
    // Risky operation
    const result = performOperation();
    return { result };
  } catch (error) {
    throw new Error(`Operation failed: ${error.message}`);
  }
}
```

When an error occurs:

* The workflow execution is marked as `failed`
* The error message and stack trace are saved
* The workflow can be resumed using the `resume` command

### Logging

Use `console.log()` for logging:

```javascript
export function main(args) {
  console.log("Processing started");
  console.log("Input:", JSON.stringify(args));

  // Your code

  console.log("Processing completed");
  return { status: "done" };
}
```

---

---
url: https://docs.tailor.tech/guides/workflow/monitoring-executions.md
---

# Monitoring Executions

## Check Execution Status

Use the `tailor workflow executions` command to check the status of a workflow execution:

```bash
tailor workflow executions <execution-id>
```

**With logs:**

```bash
tailor workflow executions <execution-id> --logs
```

**Usage:**

```bash
tailor workflow executions [options] [executionId]
```

**Arguments:**

* `[executionId]`: Execution ID (optional). If provided, shows execution details. If omitted, lists all executions.

**Options:**

* `--logs`: Display job execution logs (detail mode only)
* `--wait` (`-W`): Wait for execution to complete
* `--interval <INTERVAL>` (`-i`): Polling interval when using --wait (e.g., '3s', '500ms', '1m', default: '3s')
* `--workflow-name <WORKFLOW_NAME>` (`-n`): Filter by workflow name (list mode only)
* `--status <STATUS>` (`-s`): Filter by status (list mode only)
* `--json` (`-j`): Output as JSON

**Output:**

```
Execution ID: yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy
Workflow ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Status: success
Started At: 2025-01-15T10:30:00Z
Finished At: 2025-01-15T10:30:45Z

Job Executions:
  1. main (success)
     Started: 2025-01-15T10:30:00Z
     Finished: 2025-01-15T10:30:45Z
     Stacked Task: main

  2. fetchData (success)
     Started: 2025-01-15T10:30:05Z
     Finished: 2025-01-15T10:30:15Z
     Stacked Task: main/fetchData

  3. processData (success)
     Started: 2025-01-15T10:30:20Z
     Finished: 2025-01-15T10:30:40Z
     Stacked Task: main/processData

Result: {
  "success": true,
  "processed": {...}
}
```

## List All Executions

List all workflow executions in your workspace:

```bash
tailor workflow executions
```

**Filter by workflow name:**

```bash
tailor workflow executions --workflow-name my-workflow
```

**Filter by status:**

```bash
tailor workflow executions --status RUNNING
```

**Combine filters:**

```bash
tailor workflow executions --workflow-name my-workflow --status FAILED
```

## Execution Status

A workflow execution can have the following statuses:

* **pending**: Waiting to be picked up by the scheduler
* **pending\_resume**: Waiting to be resumed after a failure or resolve
* **running**: Currently executing
* **waiting**: Paused by `wait()`, waiting for an external `resolve()` signal (see [Wait / Resolve](/guides/workflow/wait-resolve))
* **success**: Completed successfully
* **failed**: Execution failed (can be resumed)

## Follow Execution Progress

You can follow an execution in real-time using the `--wait` flag:

```bash
tailor workflow executions <execution-id> --wait
```

This will poll for updates until the execution completes.

**Customize polling interval:**

```bash
tailor workflow executions <execution-id> --wait --interval 5s
```

**Wait and show logs:**

```bash
tailor workflow executions <execution-id> --wait --logs
```

The `start` command returns an execution ID that you can use with `workflow executions` to monitor progress.

## Execution Events

Besides polling, a workflow can publish its execution lifecycle as platform events, so that an executor reacts to each state transition as it happens. Refer to [Workflow events](/guides/events#workflow) for the event catalog and payloads.

Publishing is controlled per resource by `publishEvents`, and you normally do not have to set it. When an executor subscribes to a workflow's execution events, `deploy` enables publishing automatically on the resources that produce them:

* A `workflowExecution*` trigger enables it on the workflow it names, which publishes the `workflow.workflow_execution.*` events.
* A `workflowJobExecution*` trigger enables it on every job the named workflow runs, which publishes the `workflow.workflow_execution.job_execution.*` events.

Set `publishEvents` explicitly to override that. Use `true` to publish workflow-level events without a subscribing executor:

```typescript {{ title: 'workflows/order-processing.ts' }}
import { createWorkflow } from "@tailor-platform/sdk";
import { processOrder } from "./jobs/process-order";

export default createWorkflow({
  name: "order-processing",
  mainJob: processOrder,
  publishEvents: true,
});
```

A job takes the same field for its own execution events:

```typescript {{ title: 'workflows/jobs/process-order.ts' }}
import { createWorkflowJob } from "@tailor-platform/sdk";

export const processOrder = createWorkflowJob({
  name: "process-order",
  publishEvents: true,
  body: async () => ({ processed: true }),
});
```

Use `false` to keep publishing off. `deploy` fails if an executor subscribes to events that the value opts out of, so a subscription cannot silently go unfulfilled.

To consume these events, configure an executor with a workflow execution trigger. See [Event-based Trigger](/guides/executor/event-based-trigger#workflow-execution-events).

## Monitoring in Tailor Console

You can also monitor workflow executions through the [Tailor Console](https://console.tailor.tech) web interface.

The console provides:

* Visual execution timeline
* Job function execution details
* Error messages and logs
* Execution history for all workflow runs

## Resume and Retry

### Resuming Failed Workflows

If a workflow execution fails, you can resume it from the point of failure using the `resume` command:

```bash
tailor workflow resume <execution-id>
```

**Usage:**

```bash
tailor workflow resume [options] <executionId>
```

**Arguments:**

* `<executionId>`: Failed execution ID (required)

**Options:**

* `--wait` (`-W`): Wait for execution to complete
* `--interval <INTERVAL>` (`-i`): Polling interval when using --wait (e.g., '3s', '500ms', '1m', default: '3s')
* `--logs` (`-l`): Display job execution logs after completion (requires --wait)
* `--json` (`-j`): Output as JSON

**Resume and wait for completion:**

```bash
tailor workflow resume <execution-id> --wait
```

**Resume and show logs:**

```bash
tailor workflow resume <execution-id> --wait --logs
```

**What happens during resume:**

1. The system retrieves all successful job function results from the previous run
2. The workflow restarts from the main function
3. Successful job functions are skipped (their cached results are used)
4. Failed or not-yet-executed job functions are executed

**Example:**

Original execution:

```
fetchData    → Success ✓
processData  → Success ✓
saveToDb     → Failed ✗
```

After resume:

```
fetchData    → Skipped (cached)
processData  → Skipped (cached)
saveToDb     → Executed again
```

### Resuming from Code

You can also resume a failed or pending-retry execution from your own code (a workflow job function, an executor, or a resolver) using `tailor.workflow.resumeWorkflowExecution()`. This lets you build self-healing flows that recover from transient failures automatically, without an operator running `tailor workflow resume` or using the Tailor Console.

**Example:**

```javascript
export async function main(args) {
  const resumedId = await tailor.workflow.resumeWorkflowExecution(args.executionId);
  console.log("Resumed execution:", resumedId);
  return { resumedExecutionId: resumedId };
}
```

**API Reference:**

* **First argument**: Execution ID of a failed or pending-retry execution (string)

**Return value:**

* Execution ID of the resumed execution (string)

`resumeWorkflowExecution()` behaves like the `resume` command described above. The workflow restarts from the main function and reuses the cached results of successful job functions, so only failed or not-yet-executed jobs run again. It rejects with an error describing why the execution cannot be resumed when it isn't in a resumable state. Let that error propagate to fail the calling execution, and add a `try`/`catch` only when you need to control the error or its message.

### When to Use Resume

Resume is useful when:

* External API calls fail temporarily
* Database connections time out
* Rate limits are hit
* Any transient error occurs

**Important:** Only resume when the failure is transient. If the failure is due to invalid data or logic errors, fix the issue and create a new execution instead.

### Idempotency Best Practices

Design your job functions to be idempotent (safe to execute multiple times):

**Good - Idempotent:**

```javascript
export async function main(args) {
  // Check if record already exists
  const existing = await checkRecord(args.id);
  if (existing) {
    console.log("Record already exists, skipping");
    return existing;
  }

  // Create only if not exists
  return await createRecord(args);
}
```

**Avoid - Not Idempotent:**

```javascript
export function main(args) {
  // This will create duplicate records on retry
  return createRecord(args);
}
```

**Tips for idempotency:**

* Check for existing records before creating
* Use unique identifiers (UUIDs, order IDs, etc.)
* Design operations to be repeatable
* Use database constraints to prevent duplicates

## Testing and Development

### Creating Workflows with SDK

Workflows are created and managed using the Tailor Platform SDK. Define workflows in your code using `createWorkflow`:

```typescript
import { createWorkflow } from "@tailor-platform/sdk";

export const myWorkflow = createWorkflow({
  name: "my-workflow",
  steps: [
    // Define your workflow steps
  ],
});
```

After defining your workflow, deploy it using:

```bash
tailor deploy
```

---

---
url: https://docs.tailor.tech/guides/workflow/triggering-workflow.md
---

# Triggering Workflow

Workflows can be triggered in production environments using two primary methods:

1. **Job Functions** - Trigger workflows programmatically from within another workflow's job function
2. **Executor** - Trigger workflows automatically based on events, webhooks, or schedules

## Job Functions (Programmatic)

You can start another workflow from within a job function using `tailor.workflow.startWorkflow()`. This is useful for workflow composition, parallel execution, and implementing multi-stage processes.

**Example:**

```javascript
export async function main(args) {
  // Start another workflow asynchronously
  const executionId = await tailor.workflow.startWorkflow(
    "notification-workflow",
    { orderId: args.orderId, email: args.customerEmail },
    {
      authInvoker: {
        namespace: "my-auth-namespace",
        machineUserName: "notification-bot",
      },
    },
  );

  console.log("Notification workflow started:", executionId);

  return {
    notificationExecutionId: executionId,
  };
}
```

**API Reference:**

* **First argument**: Name of the workflow to trigger
* **Second argument**: JSON string of input arguments
* **Third argument** (optional): Options object
  * `authInvoker` - Authentication context for the workflow
    * `namespace` - Auth namespace
    * `machineUserName` - Machine user name

**Return value:**

* Execution ID of the started workflow (string)

**Use cases:**

* Triggering notification workflows after main processing
* Starting parallel sub-workflows for different tasks
* Implementing workflow composition patterns

`startWorkflow()` starts a workflow asynchronously and returns immediately with an execution ID. It does not wait for the workflow to complete. Use this for fire-and-forget or parallel execution patterns.

## Executor (Event-Driven Automation)

Workflows can be triggered automatically from Executor service in response to events, webhooks, or schedules. This is the recommended approach for production automation.

**Event-Based Trigger**

Start a workflow when a database record is created:

```typescript {{ title: 'executor.ts' }}
import { createWorkflow, createExecutor, recordCreatedTrigger } from "@tailor-platform/sdk";
import { order } from "./types";

const processOrderWorkflow = createWorkflow({
  name: "process-order",
  steps: [/* ... */],
});

createExecutor({
  name: "order-created-workflow",
  description: "Process order when created",
  trigger: recordCreatedTrigger({ type: order }),
  operation: {
    kind: "workflow",
    workflow: processOrderWorkflow,
    args: ({ newRecord }) => ({
      orderId: newRecord.id,
    }),
  },
});
```

**Webhook Trigger**

Start a workflow from an incoming webhook:

```typescript {{ title: 'executor.ts' }}
import { createWorkflow, createExecutor, webhookTrigger } from "@tailor-platform/sdk";

const processWebhookWorkflow = createWorkflow({
  name: "process-webhook",
  steps: [/* ... */],
});

createExecutor({
  name: "webhook-workflow",
  description: "Process webhook data",
  trigger: webhookTrigger(),
  operation: {
    kind: "workflow",
    workflow: processWebhookWorkflow,
    args: ({ body }) => body,
  },
});
```

**Schedule-Based Trigger**

Start a workflow on a schedule:

```typescript {{ title: 'executor.ts' }}
import { createWorkflow, createExecutor, scheduleTrigger } from "@tailor-platform/sdk";

const dailySyncWorkflow = createWorkflow({
  name: "daily-sync",
  steps: [/* ... */],
});

createExecutor({
  name: "daily-sync-workflow",
  description: "Daily data synchronization",
  trigger: scheduleTrigger({ cron: "0 2 * * *" }), // Every day at 2 AM
  operation: {
    kind: "workflow",
    workflow: dailySyncWorkflow,
    args: () => ({
      date: new Date().toISOString(),
    }),
  },
});
```

**Event-Based Trigger**

Start a workflow when a database record is created:

```ts {{ title: 'executor_workflow.tf' }}
resource "tailor_executor" "order_created_workflow" {
  workspace_id = tailor_workspace.main.id
  name         = "order-created-workflow"
  description  = "Process order when created"

  trigger = {
    event = {
      namespace = "tailordb"
      type      = "record.created"
      model     = "orders"
    }
  }

  operation = {
    workflow = {
      workflow_name = tailor_workflow.process_order.name
      invoker = {
        machine_user = {
          auth_namespace = tailor_auth.main_auth.namespace
          name           = tailor_auth_machine_user.workflow_bot.name
        }
      }
      variables = <<EOF
        ({ orderId: context.event.data.id })
      EOF
    }
  }
}
```

**Webhook Trigger**

Start a workflow from an incoming webhook:

```ts {{ title: 'executor_workflow.tf' }}
resource "tailor_executor" "webhook_workflow" {
  workspace_id = tailor_workspace.main.id
  name         = "webhook-workflow"
  description  = "Process webhook data"

  trigger = {
    webhook = {}
  }

  operation = {
    workflow = {
      workflow_name = tailor_workflow.process_webhook.name
      invoker = {
        machine_user = {
          auth_namespace = tailor_auth.main_auth.namespace
          name           = tailor_auth_machine_user.workflow_bot.name
        }
      }
      variables = <<EOF
        JSON.stringify(args.body)
      EOF
    }
  }
}
```

**Schedule-Based Trigger**

Start a workflow on a schedule:

```ts {{ title: 'executor_workflow.tf' }}
resource "tailor_executor" "daily_sync_workflow" {
  workspace_id = tailor_workspace.main.id
  name         = "daily-sync-workflow"
  description  = "Daily data synchronization"

  trigger = {
    schedule = {
      cron = "0 2 * * *"  # Every day at 2 AM
    }
  }

  operation = {
    workflow = {
      workflow_name = tailor_workflow.daily_sync.name
      invoker = {
        machine_user = {
          auth_namespace = tailor_auth.main_auth.namespace
          name           = tailor_auth_machine_user.workflow_bot.name
        }
      }
      variables = <<EOF
        ({ date: (new Date()).toISOString() })
      EOF
    }
  }
}
```

**Event-Based Trigger**

Start a workflow when a database record is created:

**Webhook Trigger**

Start a workflow from an incoming webhook:

**Schedule-Based Trigger**

Start a workflow on a schedule:

## Comparison and Use Cases

| Method            | Trigger Source  | Best For                                 | Authentication                    | Example Use Case                              |
| ----------------- | --------------- | ---------------------------------------- | --------------------------------- | --------------------------------------------- |
| **Job Functions** | Within workflow | Workflow composition, parallel execution | Configurable via `authInvoker`    | Main order processing → notification workflow |
| **Executor**      | External events | Automation, reactive systems             | Configured in executor definition | Database record created → process workflow    |

**When to use each method:**

**Job Functions:**

* You need to trigger a workflow as part of another workflow's logic
* Conditional triggering based on workflow results
* Parallel or sequential workflow orchestration
* Fire-and-forget notification patterns

**Executor:**

* Automated response to database events (create, update, delete)
* Processing incoming webhooks from external services
* Scheduled/periodic workflow execution (cron jobs)
* Event-driven microservices architecture

## Authentication

Both triggering methods support authentication through Machine Users:

**In Job Functions:**

```javascript
const executionId = await tailor.workflow.startWorkflow(
  "my-workflow",
  { data: "value" },
  {
    authInvoker: {
      namespace: "my-namespace",
      machineUserName: "workflow-bot",
    },
  },
);
```

**In Executor:**

```typescript
createExecutor({
  name: "my-executor",
  trigger: recordCreatedTrigger({ type: myType }),
  operation: {
    kind: "workflow",
    workflow: myWorkflow,
    args: ({ newRecord }) => ({
      data: newRecord.value,
    }),
  },
});
```

Note: In the SDK, authentication is handled through the `authInvoker` configuration in job functions or automatically through the executor configuration. The machine user must have appropriate permissions to execute the workflow and access any resources it requires.

## Starting Workflows

Start a workflow execution using the `tailor workflow start` command:

```bash
tailor workflow start my-workflow \
  --machineuser admin-machine-user \
  --arg '{"orderId": "12345"}'
```

The workflow name is specified as a positional argument (the first argument after `start`).

**Usage:**

```bash
tailor workflow start [options] <name>
```

**Arguments:**

* `<name>`: Workflow name (required)

**Options:**

* `--machineuser <MACHINEUSER>` (`-m`): Machine user name (required)
* `--arg <ARG>` (`-a`): Workflow argument as JSON string (optional)
* `--wait` (`-W`): Wait for execution to complete (optional)
* `--interval <INTERVAL>` (`-i`): Polling interval when using --wait (e.g., '3s', '500ms', '1m') (optional, default: '3s')
* `--logs` (`-l`): Display job execution logs after completion (requires --wait) (optional)

**Output:**

```
Execution ID: yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy
Status: pending
```

### Passing Arguments

Pass input data to your workflow using the `--arg` option:

```bash
tailor workflow start my-workflow \
  --machineuser admin-machine-user \
  --arg '{"orderId": "12345", "priority": "high"}'
```

The argument is available in the main function as `args`:

```javascript
export function main(args) {
  console.log("Order ID:", args.orderId);
  console.log("Priority:", args.priority);
  // ...
}
```

### Authentication

Workflows execute with machine user authentication context.

**Machine User Authentication:**

```bash
tailor workflow start my-workflow \
  --machineuser my-machine-user \
  --arg '{"data": "value"}'
```

The workflow will execute with the permissions of the specified machine user, allowing access to protected resources. The `--machineuser` option is required when starting workflows.

## Further Information

* **Timeouts and Limits** - See [Data Retention](/administration/data-retention) for information about workflow execution timeouts and limits
* **Command Reference** - See [SDK Workflow Commands](/sdk/cli/workflow) for complete command documentation

---

---
url: https://docs.tailor.tech/guides/workflow/wait-resolve.md
---

# Wait / Resolve

## Overview

The Wait / Resolve API enables **human-in-the-loop** patterns in workflows. A workflow can pause execution at any point and wait for an external signal before resuming, without consuming resources while waiting.

This is useful for scenarios where a workflow needs to wait for:

* Manual approval (e.g., order approval, content review)
* External system completion (e.g., payment confirmation)
* User input or decision before proceeding

## How It Works

The Wait / Resolve flow consists of three phases:

1. **Start** — A workflow is started and begins executing
2. **Wait** — The workflow job calls a wait point's `.wait()` method, which suspends execution and parks it in the database
3. **Resolve** — Another script calls the same wait point's `.resolve()` method with the execution ID, which resumes the workflow

```mermaid
sequenceDiagram
    participant Trigger as Trigger (Resolver / Executor)
    participant Workflow as Workflow
    participant DB as TailorDB
    participant Resolver as Resolver (Resolver Function)

    Trigger->>Workflow: startWorkflow()
    Trigger->>DB: Save executionId
    Workflow->>Workflow: approval.wait(payload)
    Note over Workflow: Execution paused (status: waiting)

    Resolver->>DB: Read executionId
    Resolver->>Workflow: approval.resolve(executionId, callback)
    Note over Workflow: Execution resumed (status: running)
    Workflow->>Workflow: Continues with resolve result
```

While waiting, the workflow runner exits and no resources are consumed. The execution is parked in the database until `.resolve()` is called.

## API Reference

Wait points are declared with `createWaitPoint` (single) or `createWaitPoints` (multiple, via a builder callback) from `@tailor-platform/sdk`. Each returns an object with `.wait()` and `.resolve()` methods, typed by a `Payload` (sent to `.wait()`) and a `Result` (returned from `.wait()`, produced by the `.resolve()` callback) — both must be JSON-serializable values.

```typescript {{ title: 'workflows/approval.ts' }}
import { createWaitPoint } from "@tailor-platform/sdk";

export const approval = createWaitPoint<
  { orderId: string; amount: number; requestedBy: string },
  { approved: boolean }
>("approval");
```

### `wait(payload)`

Suspends the current workflow job and waits for an external signal.

**Arguments:**

* **`payload`** (optional) — JSON-serializable data to persist while waiting. This data is available to the `.resolve()` callback. Omit if the wait point's `Payload` type is `undefined`.

**Return value:**

* The result returned by the `.resolve()` callback when the workflow resumes.

**Example:**

```typescript {{ title: 'workflows/jobs/process-order.ts' }}
import { createWorkflowJob } from "@tailor-platform/sdk";
import { approval } from "../approval";

export const processOrder = createWorkflowJob({
  name: "process-order",
  body: async (input: { orderId: string; totalAmount: number; userId: string }) => {
    const order = { id: input.orderId };

    // Pause and wait for approval
    const result = await approval.wait({
      orderId: order.id,
      amount: input.totalAmount,
      requestedBy: input.userId,
    });

    if (!result.approved) {
      return { orderId: order.id, status: "rejected" as const };
    }
    return { orderId: order.id, status: "approved" as const };
  },
});
```

### `resolve(executionId, callback)`

Resolves a waiting workflow, causing it to resume execution.

**Arguments:**

* **`executionId`** (string, required) — The execution ID of the waiting workflow.
* **`callback`** (function, required) — A function that receives the payload passed to `.wait()` and returns the `Result`. The returned value is passed back to the `.wait()` caller when the workflow resumes.

**Return value:**

* None. The callback result is delivered to the waiting workflow asynchronously.

**Example:**

```typescript {{ title: 'resolvers/resolveApproval.ts' }}
import { createResolver, t } from "@tailor-platform/sdk";
import { approval } from "../workflows/approval";

export default createResolver({
  name: "resolveApproval",
  operation: "mutation",
  input: {
    executionId: t.string(),
    approved: t.bool(),
  },
  body: async ({ input }) => {
    await approval.resolve(input.executionId, (payload) => {
      // payload contains the data passed to wait()
      // e.g., { orderId: "...", amount: 1000, requestedBy: "..." }
      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).

## Typical Pattern

A common implementation pattern involves three components:

1. **A workflow** that starts processing and pauses on a wait point's `.wait()`
2. **A TailorDB record** that stores the execution ID for later retrieval
3. **A resolver function** that calls the wait point's `.resolve()` when the human decision is made

### Step 1: Start the workflow and save the execution ID

```javascript
// Resolver or executor function
export async function main(args) {
  const executionId = await tailor.workflow.startWorkflow("order-approval-workflow", {
    orderId: args.orderId,
  });

  // Save executionId to TailorDB for later retrieval
  await gql.mutation({
    updateOrder: {
      __args: {
        id: args.orderId,
        input: { workflowExecutionId: executionId },
      },
      id: true,
    },
  });

  return { executionId };
}
```

### Step 2: Workflow pauses on `approval.wait()`

```typescript {{ title: 'workflows/jobs/prepare-order.ts' }}
import { createWorkflowJob } from "@tailor-platform/sdk";
import { approval } from "../approval";

export const prepareOrder = createWorkflowJob({
  name: "prepare-order",
  body: async (input: { orderId: string; items: unknown[]; total: number }) => {
    // Pause and wait for human approval
    const decision = await approval.wait({
      orderId: input.orderId,
      items: input.items,
      total: input.total,
    });

    return { status: decision.approved ? "completed" : "rejected" };
  },
});
```

### Step 3: Resolve from a resolver function

```typescript {{ title: 'resolvers/resolveApproval.ts' }}
import { createResolver, t } from "@tailor-platform/sdk";
import { getDB } from "../generated/tailordb";
import { approval } from "../workflows/approval";

export default createResolver({
  name: "resolveApproval",
  operation: "mutation",
  input: {
    orderId: t.uuid(),
    approved: t.bool(),
  },
  body: async ({ input }) => {
    // Retrieve the execution ID from TailorDB
    const db = getDB("tailordb");
    const order = await db
      .selectFrom("Order")
      .select("workflowExecutionId")
      .where("id", "=", input.orderId)
      .executeTakeFirstOrThrow();

    // Resolve the waiting workflow
    await approval.resolve(order.workflowExecutionId, (payload) => {
      return { approved: input.approved };
    });

    return { resolved: true };
  },
  output: t.object({ resolved: t.bool() }),
});
```

## Execution Status

When a workflow calls `wait()`, the execution status transitions to **waiting**:

```mermaid
stateDiagram-v2
    [*] --> pending
    pending --> running : scheduler picks up

    running --> success : all jobs complete
    running --> waiting : wait() called
    running --> failed : job fails

    waiting --> pending_resume : resolve() called

    failed --> pending_resume : manual resume

    pending_resume --> running : scheduler picks up

    success --> [*]
```

You can check the waiting status using the CLI:

```bash
tailor workflow executions --status WAITING
```

## Key Behaviors

* **No resource consumption while waiting** — The workflow runner exits when `wait()` is called. The execution is parked in the database.
* **Durable state** — The wait payload and all previous job function results are preserved across the wait/resume cycle.
* **Key matching** — Each wait point has its own key (the string passed to `createWaitPoint`, or the property name under `createWaitPoints`). Resolving requires importing and calling `.resolve()` on that same wait point value — you can't resolve a suspended execution against a different wait point.
* **Single resolve** — Each wait point can only be resolved once. Concurrent resolve attempts for the same execution and key are safely rejected.
* **Cache-aware** — Wait results are integrated into the durable execution cache. If a resumed workflow is later retried, the cached wait result is reused without requiring another `resolve()`.

---

---
url: https://docs.tailor.tech/reference.md
---
# Reference

Technical references, API documentation, and platform specifications.

## API

API documentation and scripting references for building on Tailor Platform.

* [API References](/reference/api/api-references) - GraphQL API documentation and endpoints
* [CEL Scripting](/reference/api/cel-scripting) - Common Expression Language reference for expressions
* [JavaScript Scripting](/reference/api/js-scripting) - JavaScript runtime and API references

## Platform

Platform specifications, limits, and operational policies.

* [Platform Limits](/reference/platform/platform-limits) - Service quotas, rate limits, and constraints
* [Timeouts](/reference/platform/timeouts) - Request timeout configurations and limits
* [Outgoing IP Addresses](/reference/platform/outgoing-ip-addresses) - Platform IP addresses for allowlisting
* [Service Lifecycle Policy](/reference/platform/service-lifecycle-policy) - Service versioning and deprecation

## Concepts

Core concepts and technical fundamentals of the platform.

* [Terminology & Concepts](/reference/concepts/terminology_concepts) - Platform terminology and key concepts
* [Tailor Resource Names (TRN)](/reference/concepts/trn) - Resource naming conventions and structure

## Infrastructure

Infrastructure as Code and deployment tools.

* [Terraform Import](/reference/infrastructure/terraform-import) - Importing existing resources into Terraform

---

---
url: https://docs.tailor.tech/reference/character-encodings.md
---
# Character Encodings

This page documents the character encodings supported by the `tailor.iconv` API in the Function service. Understanding these encodings is essential for handling text data conversion between different character sets, especially when working with Japanese, Chinese, and Korean text.

## Overview

The Function service provides comprehensive character encoding conversion capabilities through the `tailor.iconv` API. This includes support for over 100 character encodings, with special focus on Japanese business systems and enterprise environments.

## Unicode

| Encoding Name | Aliases | Description                    | Character Types                                          |
| ------------- | ------- | ------------------------------ | -------------------------------------------------------- |
| UTF-8         | UTF8    | Unicode (UTF-8)                | Full-width/half-width alphanumeric, kana, kanji, symbols |
| UTF-16        | UTF16   | Unicode (UTF-16)               | Full-width/half-width alphanumeric, kana, kanji, symbols |
| UTF-16BE      | -       | Unicode (UTF-16 Big Endian)    | Full-width/half-width alphanumeric, kana, kanji, symbols |
| UTF-16LE      | -       | Unicode (UTF-16 Little Endian) | Full-width/half-width alphanumeric, kana, kanji, symbols |

## Japanese Character Encodings

### Shift\_JIS Family Encodings

| Encoding Name | Aliases            | Description                  | Character Types                                                                                                                       |
| ------------- | ------------------ | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Shift\_JIS     | SHIFT\_JIS, SJIS    | Shift JIS code               | Half-width alphanumeric, half-width katakana, full-width kana, JIS Level 1 & 2 kanji                                                  |
| SJIS          | -                  | Shift\_JIS alias              | Half-width alphanumeric, half-width katakana, full-width kana, JIS Level 1 & 2 kanji                                                  |
| CP932         | Windows-31J, MS932 | Microsoft extended Shift\_JIS | Half-width alphanumeric, half-width katakana, full-width kana, JIS Level 1 & 2 kanji, NEC special characters, IBM extended characters |

### EUC-JP Family Encodings

| Encoding Name | Aliases      | Description               | Character Types                                                                                                  |
| ------------- | ------------ | ------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| EUC-JP        | EUCJP, eucJP | Japanese EUC code         | Half-width alphanumeric, full-width kana, JIS Level 1 & 2 kanji                                                  |
| EUC-JP-MS     | eucJP-ms     | Microsoft extended EUC-JP | Half-width alphanumeric, full-width kana, JIS Level 1 & 2 kanji, NEC special characters, IBM extended characters |

### ISO-2022 Family Encodings

| Encoding Name | Aliases        | Description      | Character Types                                              |
| ------------- | -------------- | ---------------- | ------------------------------------------------------------ |
| ISO-2022-JP   | ISO2022JP, JIS | JIS code (7-bit) | ASCII, JIS Roman, half-width katakana, JIS Level 1 & 2 kanji |

## Enterprise System Encodings

### IBM EBCDIC Japanese Encodings

| Encoding Name  | Aliases               | Description                           | Character Types                                                                      |
| -------------- | --------------------- | ------------------------------------- | ------------------------------------------------------------------------------------ |
| IBM037         | EBCDIC-CP-US, CP037   | EBCDIC US/Canada                      | Alphanumeric                                                                         |
| IBM290         | EBCDIC-JP-KANA, CP290 | Japanese EBCDIC katakana              | Alphanumeric, katakana                                                               |
| IBM930         | CP930                 | Japanese EBCDIC (kanji)               | Alphanumeric, katakana, hiragana, JIS Level 1 & 2 kanji                              |
| IBM939         | CP939                 | Japanese EBCDIC extended              | Alphanumeric, katakana, hiragana, JIS Level 1 & 2 kanji, extended characters         |
| IBM943         | CP943                 | Japanese PC code                      | Half-width alphanumeric, half-width katakana, full-width kana, JIS Level 1 & 2 kanji |
| EBCDIC-JP-E    | -                     | Japanese EBCDIC alphanumeric katakana | Alphanumeric, katakana                                                               |
| EBCDIC-JP-KANA | -                     | Japanese EBCDIC katakana              | Alphanumeric, katakana                                                               |

### Enterprise System Aliases

| Alias Name    | Actual Encoding | Description               | Character Types        |
| ------------- | --------------- | ------------------------- | ---------------------- |
| HitachiKEIS83 | IBM290          | Hitachi KEIS83 compatible | Alphanumeric, katakana |
| HitachiKEIS90 | IBM290          | Hitachi KEIS90 compatible | Alphanumeric, katakana |
| NECJIPS       | IBM290          | NEC JIPS compatible       | Alphanumeric, katakana |
| NECJIS        | IBM290          | NEC JIS compatible        | Alphanumeric, katakana |

Suffix characters are ignored in enterprise system aliases.

## Chinese Encodings

| Encoding Name | Aliases    | Description                            | Character Types                                             |
| ------------- | ---------- | -------------------------------------- | ----------------------------------------------------------- |
| GB2312        | EUC-CN     | Simplified Chinese (basic)             | ASCII, simplified Chinese                                   |
| GBK           | CP936      | Simplified Chinese (extended)          | ASCII, simplified Chinese (extended)                        |
| GB18030       | -          | Simplified Chinese (complete)          | ASCII, simplified Chinese (all characters)                  |
| Big5          | BIG5       | Traditional Chinese                    | ASCII, traditional Chinese                                  |
| BIG5HKSCS     | Big5-HKSCS | Hong Kong extended traditional Chinese | ASCII, traditional Chinese, Hong Kong additional characters |

## Korean Encodings

| Encoding Name | Aliases   | Description          | Character Types               |
| ------------- | --------- | -------------------- | ----------------------------- |
| EUC-KR        | EUCKR     | Korean EUC           | ASCII, Korean                 |
| UHC           | CP949     | Unified Hangul Code  | ASCII, Korean (extended)      |
| JOHAB         | -         | Combinatorial Hangul | ASCII, Korean (combinatorial) |
| ISO-2022-KR   | ISO2022KR | Korean ISO-2022      | ASCII, Korean characters      |

## Other Languages

| Encoding Name | Aliases  | Description            | Character Types                    |
| ------------- | -------- | ---------------------- | ---------------------------------- |
| ISO-8859-1    | Latin-1  | Western European       | ASCII, Western European characters |
| ASCII         | US-ASCII | American Standard Code | Basic ASCII characters (0-127)     |

## API Usage Examples

### Basic Conversion

```javascript
// UTF-8 to Shift_JIS conversion
const sjisData = tailor.iconv.convert("日本語テキスト", "UTF-8", "Shift_JIS");

// EUC-JP to UTF-8 conversion
const utf8Text = tailor.iconv.convert(eucjpData, "EUC-JP", "UTF-8");
```

### Using Enterprise Aliases

```javascript
// HitachiKEIS83 (actually IBM290) conversion
const keisData = tailor.iconv.convert("カタカナ", "UTF-8", "HitachiKEIS83");
```

### Custom Replacement Characters

```javascript
// Replace unconvertible characters with asterisk
const asciiText = tailor.iconv.convert("Hello 世界!", "UTF-8", "ASCII//TRANSLIT:*");
// Result: "Hello **!"

// Custom string replacement
const asciiText2 = tailor.iconv.convert("Test 日本語", "UTF-8", "ASCII//TRANSLIT:[?]");
// Result: "Test [?][?][?]"

// Underscore replacement
const asciiText3 = tailor.iconv.convert("abc世界xyz", "UTF-8", "ASCII//TRANSLIT:_");
// Result: "abc__xyz"
```

### TRANSLIT with Special Characters

```javascript
// Convert special characters using TRANSLIT
const specialText = "abc ß α € àḃç";

// Default TRANSLIT (uses ? for unconvertible characters)
const result1 = tailor.iconv.convert(specialText, "UTF-8", "ASCII//TRANSLIT");
// Result: "abc ? ? ? ???"

// Custom replacement with asterisk
const result2 = tailor.iconv.convert(specialText, "UTF-8", "ASCII//TRANSLIT:*");
// Result: "abc * * * ***"

// Custom replacement with underscore
const result3 = tailor.iconv.convert(specialText, "UTF-8", "ASCII//TRANSLIT:_");
// Result: "abc _ _ _ ___"
```

### Checking Available Encodings

```javascript
// Get all Japanese-related encodings
const allEncodings = tailor.iconv.encodings();
const jpEncodings = allEncodings.filter((enc) =>
  enc.match(/JP|JIS|Shift|KEIS|93[029]|94[39]|EBCDIC.*JP/i),
);
```

## Error Handling

The `tailor.iconv` API supports special flags for handling characters that cannot be converted:

* **//IGNORE**: Silently ignores characters that cannot be converted
* **//TRANSLIT**: Attempts to transliterate characters to similar ones in target encoding (default replacement: `?`)
* **//TRANSLIT:char**: Custom replacement character extension
  * Example: `ASCII//TRANSLIT:*` replaces unconvertible characters with `*`
  * Example: `ASCII//TRANSLIT:[?]` replaces unconvertible characters with `[?]`

## Best Practices

1. **Encoding Selection**
   * For text with kanji: Use UTF-8, Shift\_JIS, EUC-JP, or IBM930/939
   * For katakana-only text: IBM290 is also available
   * For email transmission: ISO-2022-JP is recommended

2. **Preventing Character Corruption**
   * Use the same encoding for both sender and receiver
   * Specify the source encoding accurately

3. **Error Handling**
   * Use `//IGNORE` to skip unconvertible characters
   * Use `//TRANSLIT` for character substitution
   * Use custom replacement characters for specific requirements

## Related Resources

* [Unicode Consortium](https://www.unicode.org/)
* [IBM Code Pages](https://www.ibm.com/docs/en/aix/7.1?topic=reference-code-page-names-numbers)
* [IANA Character Sets](https://www.iana.org/assignments/character-sets/character-sets.xhtml)
* [Function Service Examples](/guides/function/examples)

---

---
url: https://docs.tailor.tech/reference/security.md
description: Tailor Platform Security
---

# Security at Tailor Technologies. inc

As a provider of platform solutions to enterprise customers, Tailor is committed to ensuring platform security through both Enterprise and Product security approaches.

## Enterprise security

Tailor's enterprise security approach involves securing our infrastructure, protecting customer data, and maintaining strict access controls ([RBAC](#role-based-access-control-rbac)). To achieve this, we use network segmentation, firewalls, and intrusion detection systems ([Endpoint protection](#endpoint-protection)), as well as conducting third-party security assessments ([Vendor Security](#vendor-security)). We also provide regular security education and training to our employees to stay up-to-date on best practices and safeguard against potential threats ([Security education](#security-education)).

### Role-based access control (RBAC)

Tailor employees are granted access to applications based on their role, and automatically deprovisioned upon termination of their employment. Further access must be approved according to the policies set for each application.

### Endpoint protection

All corporate devices are centrally managed and are equipped with mobile device management software and anti-malware protection. Endpoint security alerts are monitored with 24/7/365 coverage. We use MDM software to enforce secure configuration of endpoints, such as disk encryption, screen lock configuration, and software updates.

### Vendor Security

Tailor assesses the security risk of vendors based on factors such as their access to customer and corporate data and their integration with production environments. We use this information to determine the inherent risk rating of the vendor. Finally, we evaluate the vendor's security to determine the residual risk rating and decide whether to approve the vendor.

### Security education

Tailor provides comprehensive security training to all employees upon onboarding and annually through educational modules. Tailor's security team shares threat briefings with employees to inform them of important security and safety-related updates that require special attention or action.

***

## Product Security

Tailor's product security approach includes the protection of customer data through encryption ([Data Encryption](#data-encryption)) and vulnerability assessments ([Vulnerability](#vulnerability)). These measures help ensure that customer data is protected from unauthorized access and potential security risks are identified and addressed in a timely manner.

### Data Encryption

At Tailor, the security of customer data is a top priority. To ensure its protection from unauthorized access, we use AES-256 encryption to encrypt all customer data at rest, and TLS encryption during transit. These industry-standard encryption protocols are designed to keep customer data secure at all times.

### Vulnerability

To proactively identify and address potential security risks, Tailor performs regular vulnerability assessments. Any vulnerabilities that directly affect our systems and services are promptly patched or remediated based on the severity of the issue and the availability of a patch or remediation instructions.

### Status Page

For the product status page, we use [Statuspage](https://tailortech.statuspage.io/), a third-party service that provides a public status page for Tailor.

### Release Notes

For Release Notes, please see [here](https://updates.tailor.tech/).

## SOC 2

Tailor complies with SOC2, which is a compliance framework by the American Institute of Certified Public Accountants' (AICPA).

Potential customers can reach out to us for more information.

---

---
url: https://docs.tailor.tech/reference/changelog.md
description: Latest updates and releases for Tailor Platform
---

# Changelog

---

---
url: https://docs.tailor.tech/reference/api/api-references.md
---

# API References

The Tailor Platform exposes its functionality through APIs defined using Protocol Buffers. Using ConnectRPC, we support both gRPC and HTTP protocols. This guide shows you how to interact with these APIs using different approaches.

## Overview

All platform services are exposed through the `OperatorService`, a unified gRPC API for managing workspaces, applications, and platform components. The .proto files defining these services are available in our [GitHub repository](https://github.com/tailor-inc/proto).

## Using the APIs

:::tabs api-usage
:::

## Authentication

All API calls require authentication using Bearer tokens. Use tailor to authenticate:

```bash
# Login to Tailor Platform
tailor login

# Create a personal access token for API authentication
tailor user pat create <token-name>
```

See the [Auth Guide](/guides/auth/overview) for detailed authentication setup.

## Common Operations

### Workspace Management

* `CreateWorkspace` - Create a new workspace
* `GetWorkspace` - Retrieve workspace details
* `ListWorkspaces` - List all accessible workspaces
* `UpdateWorkspace` - Modify workspace settings
* `DeleteWorkspace` - Remove a workspace

### Application Services

* `CreateApplication` - Deploy a new application
* `CreateTailorDBService` - Set up database services
* `CreatePipelineService` - Configure data processing
* `CreateAuthService` - Enable authentication
* `CreateExecutorService` - Set up job execution

## Error Handling

All APIs return standard gRPC status codes. Common error responses include:

* `UNAUTHENTICATED` (16) - Invalid or missing authentication
* `PERMISSION_DENIED` (7) - Insufficient permissions
* `NOT_FOUND` (5) - Resource does not exist
* `ALREADY_EXISTS` (6) - Resource already exists
* `INVALID_ARGUMENT` (3) - Invalid request parameters

## Related Documentation

For implementation details and usage examples, refer to:

* [TailorDB Guide](/guides/tailordb/overview)
* [Resolver Guide](/guides/resolver)
* [Auth Guide](/guides/auth/overview)
* [Executor Guide](/guides/executor/overview)
* [Function Guide](/guides/function/overview)

---

---
url: https://docs.tailor.tech/reference/api/cel-scripting.md
---
# CEL scripting

[CEL Script](https://github.com/google/cel-spec) is used to perform data transformation and run validations in the Tailor Platform.

Here are some places you can utilize CEL:

* `authorization`, `preScript`, `postScript`, `preValidation`, `postValidation` blocks on [resolvers](/guides/resolver)
* `create_expr`, `update_expr` hooks in [TailorDB Hooks](/guides/tailordb/hooks)&#x20;
* `expr` validation in [TailorDB Validations](/guides/tailordb/validations) &#x20;

[Standard operators and functions](https://github.com/google/cel-spec/blob/master/doc/langdef.md#list-of-standard-definitions) as well as [String extensions](https://github.com/google/cel-go/tree/master/ext#strings) can be used.

**Example**:

```go
// filter and extract the IDs of a list
preScript: """
  {
    "objectIDs": args.edges.filter(r, r.node.lang.contains("en-US")).map(r, r.node.id)
  }
""""
```

## Tailor Platform extensions

In addition, the Tailor platform provides useful extensions and supports optional types.

### `compact`

Accepts a map and returns a new one that excludes the entries that have null values.

```javascript
compact({ a: 1, b: null });
// → { "a": 1 }
```

### `get`

Provides [safe navigation](https://en.wikipedia.org/wiki/Safe_navigation_operator).
Accepts an object/array, a path, and fallback value.

```javascript
// args is { "input": { "query": { "some": "thing" } } }
get(args.input.query.date);
// → null

// args is { "input": { "query": { "date": "2023-01-01" } } }
get(args.input.query.date);
// → "2023-01-01"

// args is { "input": { "query": { "some": "thing" } } }
get(args.input.query.date, "1996-10-03");
// → "1996-10-03"
```

### `intersect`

Accepts two arrays and returns an array which contains the elements found in both.
Drops `null` values.

```javascript
intersect([1, 2, 3, null], [null, 3, 4, 5]);
// → [3]

intersect(["a", "b", "c"], ["c", "z", "b"]);
// → ["b", "c"]
```

### `makeMap`

Accepts an array and generates a map from it.

```javascript
makeMap(["a", 1, "b", 2]);
// → { "a": 1, "b": 2 }
```

### `uuidgen`

Generates a UUID v4 string.

```javascript
uuidgen();
// → 4f88b002-859f-4f59-b6fd-521c75041b13
```

### `ifThen`

Returns a specific value based on evaluation.

Accepts a condition, a true value and false value. If the condition evaluates to true, the true value is returned. Otherwise, the false value is returned.

```javascript
// args is 'x = 5, y = 7'
ifThen(x < y, x, y);
// → 5

// args is 'x = 5, y = 7'
ifThen(x > y, x, y);
// → 7

// args is 'x = 5, y = 7'
ifThen(x > y, x);
// → null
```

### `isNull`

Evaluates whether input is null and returns true or false.

```javascript
// args is { "input": { "query": { "some": "thing" } } }
isNull(args.input.query.some);
// → false

// args is { "input": { "query": { "some": null } } }
isNull(args.input.query.some);
// → true
```

### Optional types

With optional types, you can safely handle missing values in your scripts. This is especially useful for scenarios like:

* Checking if a value exists before performing an operation
* Providing default values for missing data
* Writing cleaner and more predictable expressions

```javascript
// args is { "field": { "array_field": ["value1", "value2"] } }
args.?field.?array_field[?0].orValue("default_value")
// → "value1"
```

---

---
url: https://docs.tailor.tech/reference/api/js-scripting.md
---

# JavaScript

Using JavaScript, implement robust validation logic, manipulate data structures, and perform efficient data transformations in resolvers, Triggers and TailorDB.

Here are some examples of where you can utilize JavaScript:

* `PreHook`, `PostHook` blocks in [resolvers](/guides/resolver)
* `Condition`, `URL`, `Body`, `Variables` blocks in [Triggers and Targets](/guides/executor/overview)
* `Validate` and `Hooks` blocks in [TailorDB](/guides/tailordb/overview)
* `create`, `update` hooks in [TailorDB Hooks](/guides/tailordb/hooks)
* `script` validation in [TailorDB Validations](/guides/tailordb/validations)

## Resolver

You can use `PostHook` field in the resolver to return the object that can be used in the later steps.

Throwing an `Error` in a resolver step halts the execution. The API returns the error in the format `<name>: <message>` (e.g., `Error: No heroes found`).

**Example**:

:::tabs resolver-example
:::

## Triggers and Targets

You can write Javascript to check the condition for event based triggers.

:::tabs trigger-condition
:::

In the target type `#TargetTailorGraphql`, you can pass the input variables to the Graphql query as shown below.

:::tabs trigger-variables
:::

You can write custom logic using JavaScript in the `URL` and `Body` fields in the target type `#TargetWebhook`.

:::tabs webhook-url
:::

:::tabs webhook-body
:::

## TailorDB

The example below demonstrates how to use JavaScript in `Hooks` to set a default value for the field. You can add custom logic to validate the input data and set default values.

:::tabs tailordb-hooks
:::

Here's an example on how you can leverage the built-in support for console messages in JavaScript to debug and troubleshoot your code.

:::tabs tailordb-validate
:::

Run the Tailor platform in your local environment to debug the application and view console messages in the log. Contact us if you need more information about running the platform locally.

The `Action` will be evaluated when the `Expr` returns true.

The `_value` and `_data` arguments to the function represent the `description` field and the input data object for the new record.

Additionally, you can access user object which contains information about the user who created or updated the record.

The user object has the following fields:

| Field          | Description                                                                         |
| -------------- | ----------------------------------------------------------------------------------- |
| `id`           | ID of the user.                                                                     |
| `type`         | Type of the user, e.g., `machine_user`.                                             |
| `workspace_id` | Current workspace ID.                                                               |
| `attributes`   | List of IDs; e.g., if the current user has admin rights, the admin ID will be here. |
| `tenant_id`    | Tenant ID.                                                                          |

---

---
url: https://docs.tailor.tech/reference/platform/outgoing-ip-addresses.md
---
# Outgoing IP Addresses

This page lists the outgoing IP addresses used by the Tailor Platform. If your infrastructure requires IP whitelisting for incoming connections from Tailor services, you can use these addresses to configure your firewall or security rules.

## Overview

The Tailor Platform operates across multiple regions to provide low-latency access and high availability. Each region has a set of dedicated outgoing IP addresses that are used when the platform makes external requests, such as webhook calls, API integrations, or other outbound connections.

## IP Addresses by Region

### Asia-Northeast

The following IP addresses are used for outgoing connections from the Asia-Northeast region:

| IP Address    |
| ------------- |
| 34.84.184.32  |
| 34.146.182.34 |
| 34.84.246.225 |
| 34.146.1.96   |
| 34.146.215.65 |

### US-West

The following IP addresses are used for outgoing connections from the US-West region:

| IP Address    |
| ------------- |
| 34.127.79.202 |
| 34.168.21.128 |
| 34.82.25.72   |

## When to Use These IPs

You may need to whitelist these IP addresses in the following scenarios:

* **Webhook endpoints**: If your application receives webhooks from Tailor Platform executors or event triggers, whitelist the IPs for the region where your workspace is hosted.
* **External API integrations**: When Tailor Platform functions or resolvers make requests to your external services that have IP-based access controls.
* **Database connections**: If you're using external databases that require IP whitelisting for incoming connections from Tailor services.

## Best Practices

When configuring IP whitelisting, consider the following recommendations:

1. **Whitelist all IPs for your region**: To ensure uninterrupted service, whitelist all IP addresses for the region where your Tailor workspace is deployed.

2. **Monitor for updates**: IP addresses may change over time. Check this documentation periodically or subscribe to platform updates to stay informed of any changes.

3. **Use region-specific whitelisting**: If your security policies allow, you can whitelist only the IPs for the specific region your workspace uses rather than all regions.

---

---
url: https://docs.tailor.tech/reference/platform/platform-limits.md
---
# Platform Limits

This page documents the various limits and constraints in the Tailor Platform services. Understanding these limits is essential for building robust applications that operate within platform boundaries.

## Overview

Platform limits are enforced across different services in the Tailor Platform to ensure system stability, resource management, and prevent excessive resource consumption. Each service has specific limits based on its intended use case and operational requirements.

## Service Limits

| Service              | Limit Type                                   | Limit Value    | Description                                                                                                                                               | Impact                                                                                                 |
| -------------------- | -------------------------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| Recursive Call Limit | Call Depth                                   | 10 levels      | Max depth for nested platform-to-platform requests (resolvers, functions, etc.)                                                                           | Request rejected with BadRequest error if depth exceeds 10 levels                                      |
| Workflow             | Workspace Concurrent Executions              | 50 executions  | Max concurrent workflow executions per workspace                                                                                                          | Pending executions remain in `PENDING` status until running executions drop below the cap              |
| Workflow             | Per-Workflow Concurrent Executions           | 20 executions  | Max concurrent executions of a single workflow                                                                                                            | Pending executions remain in `PENDING` status until running executions drop below the cap              |
| Workflow             | Workspace Concurrent Job Functions           | 100 dispatches | Max concurrent job function dispatches per workspace (regardless of `executionPolicyKey`)                                                                 | Dispatch is suspended and workflow moves to `PENDING_RESUME` until dispatches drop below the cap       |
| Workflow             | Per-Key Concurrent Job Functions (fallback)  | 50 dispatches  | Platform fallback per `executionPolicyKey`, applied only when a matching execution policy has no user-defined `concurrencyPolicy.maxConcurrentExecutions` | Dispatch is suspended and workflow moves to `PENDING_RESUME` until dispatches drop below the cap       |
| Executor             | Workspace Concurrent Job Function Operations | 100 executions | Max concurrently running job function operations per workspace                                                                                            | Excess executions remain pending and start automatically, oldest first, as running executions complete |
| Executor             | Incoming Webhook Request Rate                | 100 req/sec    | Max incoming webhook requests per second per workspace                                                                                                    | Excess requests are rejected with `429 Too Many Requests` and never reach the executor                 |
| Function             | Memory                                       | 32 MB          | Max memory available to a Function execution                                                                                                              | Execution terminated with `Memory limit exceeded` error if usage exceeds 32 MB                         |
| JobFunction          | Memory                                       | 256 MB         | Max memory available to a JobFunction execution                                                                                                           | Execution terminated with `Memory limit exceeded` error if usage exceeds 256 MB                        |
| Function             | TailorDB Select Result Size                  | 128 MB         | Max size of data returned from a TailorDB select query                                                                                                    | Query fails if the result set exceeds 128 MB                                                           |
| Function             | Fetch Response Body Size                     | 10 MB          | Max size of a response body when using buffered methods like `.text()` or `.json()`                                                                       | Request fails if the response body exceeds 10 MB                                                       |

## Recursive Call Detection

The Tailor Platform implements recursive call detection to prevent infinite loops and excessive resource consumption when services call each other. This safety mechanism tracks the depth of nested platform-to-platform requests and enforces a maximum depth limit.

### Affected Operations

Recursive call detection applies to:

* **Resolvers** calling other resolvers
* **Function service** operations that trigger other platform services
* **Executor service** operations that invoke GraphQL mutations or other services
* **Event-driven workflows** where one service triggers events that cause other services to execute

### Common Scenarios

This limit prevents issues in scenarios such as:

* Resolver A calls Resolver B, which calls Resolver C, and so on beyond 10 levels
* Function operations that recursively trigger other functions through events
* Executor workflows that create cascading service calls
* Event loops where service operations trigger events that cause the same operations to execute again

## Workflow Concurrency Limits

The Tailor Platform enforces concurrency limits on workflow executions at the scheduler level to prevent resource exhaustion and ensure fair scheduling across workspaces.

### How It Works

Two independent limits control the number of concurrent workflow executions:

* **Workspace-wide limit (50)**: Caps the total number of concurrently running workflow executions within a single workspace. This prevents any one workspace from monopolizing platform resources.
* **Per-workflow limit (20)**: Caps the number of concurrently running executions of the same workflow definition. This prevents a single high-volume workflow from starving other workflows in the workspace.

When either limit is reached, new executions are not rejected. Instead, they remain in `PENDING` status and are re-evaluated on the next scheduler polling tick. Once running executions complete and slots become available, pending executions are transitioned to `RUNNING` automatically.

### Behavior

* Both limits are enforced independently. An execution must satisfy both limits to start running.
* If the workspace-wide limit is reached, no new executions start in that workspace regardless of per-workflow counts.
* If the per-workflow limit is reached for a specific workflow, other workflows in the same workspace can still start new executions (as long as the workspace-wide limit is not reached).

## Workflow Job Function Concurrency Limits

Separately from the scheduler-level workflow caps above, the workflow runner enforces platform hard limits on individual job function dispatches. These apply on top of any [user-declared execution policies](/guides/workflow/#job-function-execution-policies) and cannot be raised by workflow authors.

### How It Works

Two platform hard limits guard job function dispatches:

* **Workspace-wide limit (100)**: Caps the total number of concurrently running job function dispatches within a single workspace. Applies to every dispatch regardless of whether `executionPolicyKey` is set.
* **Per-key fallback limit (50)**: A safety net that only kicks in when a dispatch supplies an `executionPolicyKey` and the matching execution policy does not declare a user-defined `concurrencyPolicy.maxConcurrentExecutions`. Once a policy sets its own cap, that user cap replaces this fallback and the platform per-key limit is no longer consulted.

When a dispatch hits any of these caps (or a user-declared execution policy cap), the workflow is suspended to `PENDING_RESUME` and retried after a short delay (default 5s).

### Behavior

* Both platform limits and user-declared execution policies are enforced independently. A dispatch must satisfy all applicable caps to run.
* The workspace-wide job function limit is independent of the workflow-execution caps above — a workflow that is already `RUNNING` can still have its dispatches suspended when the workspace hits the 100-dispatch ceiling.
* The per-key fallback protects operators from accidentally leaving a key unbounded when they only declare the policy to register a valid key without a user-defined cap.

## Executor Job Function Concurrency Limit

The Tailor Platform limits the number of concurrently running Executor [job function operations](/guides/executor/job-function-operation) to **100 per workspace**. This ensures fair scheduling across workspaces: a sudden spike of executions in one workspace does not delay job executions in other workspaces.

### How It Works

The limit applies to job function operations only, regardless of how they were triggered (schedule, event, or incoming webhook). Other operation kinds are not counted against this limit; in particular, workflow operations are governed by the [Workflow concurrency limits](#workflow-concurrency-limits) described above.

When the limit is reached, new executions are not rejected and never fail because of the limit. Instead, they remain pending and are started automatically, oldest first, as running executions complete.

### Behavior

* Executions above the limit are queued, not dropped — every execution eventually runs.
* Queued executions start in creation order, so ordering within a workspace is preserved.
* During a large burst, the delay before an execution starts is roughly `(queued executions ÷ 100) × average execution duration`. For example, a burst of 10,000 executions that each run for 30 seconds drains in about 50 minutes.
* Executions triggered by different workspaces are isolated from each other: another workspace's burst does not affect your executions.

## Incoming Webhook Rate Limit

Requests to Executor [incoming webhook](/guides/executor/incoming-webhook-trigger) endpoints are rate limited to **100 requests per second per workspace**. The limit protects the platform from traffic bursts sent by external webhook providers and keeps one workspace's inbound traffic from affecting others.

### How It Works

The limit is applied at the API gateway, before the request reaches the Executor service. It is counted per workspace across all incoming webhook endpoints in that workspace, not per executor and not per source IP address. Requests are counted in fixed one-second windows.

Unlike the concurrency limits above, rate-limited requests are **rejected, not queued**. When the limit is exceeded, the gateway responds with `429 Too Many Requests` and the executor is never invoked — there is no automatic retry on the platform side.

Every response to an incoming webhook endpoint carries standard rate limit headers you can use to monitor headroom:

| Header                | Description                              |
| --------------------- | ---------------------------------------- |
| `RateLimit-Limit`     | The limit applied to the current window  |
| `RateLimit-Remaining` | Requests remaining in the current window |
| `RateLimit-Reset`     | Seconds until the current window resets  |

### Behavior

* The limit is per workspace, so multiple executors in the same workspace share the same 100 req/sec budget.
* Because windows are fixed rather than sliding, sustained traffic at exactly 100 req/sec can still see a small percentage of `429` responses at window boundaries. Target a rate comfortably below the limit rather than right at it.

### Handling `429` Responses

Most webhook providers retry automatically on `429`. Where you control the sender, retry with exponential backoff and jitter rather than immediately. If your integration legitimately needs to sustain more than 100 req/sec, batch multiple events into a single request or contact support to discuss the workload.

## Memory Limits

The Tailor Platform enforces fixed memory limits on function executions to prevent resource exhaustion. These limits are not configurable.

* **Function**: 32 MB per execution
* **JobFunction**: 256 MB per execution

When an execution exceeds its memory limit, it is terminated and returns a `Memory limit exceeded` error indicating the memory used and the limit (for example, `used 50 MB of 32 MB limit`).

## TailorDB Select Result Size Limit

When a Function or JobFunction queries TailorDB data using `select`, the total size of the result set is limited to 128 MB. If the result exceeds this limit, the query fails with an error. Use pagination, column filtering, or query filters to keep result sizes within the limit.

## Fetch Response Body Size Limit

When a Function or JobFunction uses `fetch()`, buffered methods such as `response.text()` and `response.json()` are limited to 10 MB. If the response body exceeds this limit, the method fails with an error.

This limit does not apply to streaming methods (`response.body.getReader()`, `response.body.pipeTo()`, `response.body.pipeThrough()`). Use these to handle responses larger than 10 MB.

## Best Practices

When working within platform limits, consider the following best practices:

1. **Avoid deep service nesting**: Design workflows to minimize the depth of service-to-service calls. Consider flattening complex nested operations or using alternative patterns like event-driven architectures with proper safeguards.

2. **Monitor call patterns**: Track service interaction patterns to detect potential recursive scenarios early.

3. **Design for limits**: Anticipate depth limits and handle them gracefully in your application logic.

4. **Use alternative patterns**: Consider using event-driven architectures, queuing systems, or batch processing for complex workflows that might exceed depth limits.

5. **Design for workflow concurrency**: If your application triggers many workflow executions simultaneously, be aware that excess executions will queue as `PENDING`. Design your application to handle this gracefully rather than assuming immediate execution.

6. **Design for job function concurrency**: Bulk operations that fan out into many job function executions (for example, a data import where each record triggers downstream executors) will be smoothed to 100 concurrent executions. Do not build integrations that depend on a fixed completion time for such bursts — chain downstream steps on completion events instead of fixed schedules.

7. **Design for memory limits**: Process large datasets in batches or stream them rather than loading everything into memory at once.

8. **Choose JobFunction for memory-intensive workloads**: If your workload exceeds the 32 MB Function limit, use JobFunction (256 MB) instead.

9. **Paginate large TailorDB queries**: When querying large datasets from TailorDB, use pagination and column filtering to keep result sizes within the 128 MB limit.

10. **Use streaming for large HTTP responses**: When fetching large external resources, use `response.body.getReader()` instead of `.text()` or `.json()` to avoid the 10 MB buffered response body limit.

---

---
url: https://docs.tailor.tech/reference/platform/service-lifecycle-policy.md
---
# Service Lifecycle Policy

Understand the full lifecycle of our services and how each stage affects your application.
These services form the core of your app's functionality, making their stability and evolution critical to building a reliable, scalable solution.

Each stage has a defined purpose, expected stability level, and specific implications for your integrations.
Our reference table provides clear tags and actionable guidance to help you plan ahead, avoid disruptions, and keep your application running smoothly as services progress.

## Definitions

### Preview

An early stage intended for rapid iteration and feedback collection. Features may change frequently, and reliability is not guaranteed.

### General Availability (GA)

The service is considered stable and production-ready, with published documentation.

### Maintenance

The service remains available but is no longer actively developed. Only critical bug fixes and security patches are applied.

### Deprecated

The service is scheduled for removal. Deprecation notices and migration options are provided, and the End-of-Support (EOS) timeline begins.

### End-of-Support (EOS)

The service is no longer supported but remains operational until the scheduled retirement date.

### Retired / Out-of-Service

The service is permanently shut down and its endpoints are disabled. Data is archived according to policy.

## Guidance

Each service is tagged to show its current lifecycle phase. These tags help you understand what to expect and how to engage with the service, as detailed in the table below. For the latest announcements and updates, check the [release notes](https://www.tailor.tech/resources?filter=release-notes).

| Stage                     | Tag                                 | What you need to do                                                |
| ------------------------- | ----------------------------------- | ------------------------------------------------------------------ |
| Preview                   | Preview  | Use only in non-production environments                            |
| General Availability (GA) |                                     | Use in production environments                                     |
| Maintenance               | Maintenance | Plan for migration if new functionality is needed in the future    |
| Deprecated                | Deprecated | Stop onboarding new systems and start migrating existing workloads |
| End-of-Support (EOS)      | EOS         | To maintain compliance, complete the migration before the EOS date |

## Current Service and Feature Status

The following table shows the current lifecycle stage for Tailor Platform services and features:

| Service/Feature                                                | Stage                               | Notes                                                      |
| -------------------------------------------------------------- | ----------------------------------- | ---------------------------------------------------------- |
| **[AI Gateway](/guides/ai-gateway)**                           | Preview  | Unified OpenAI-compatible endpoint for accessing LLMs      |
| **[Built-in IdP](/guides/auth/integration/built-in-idp)**      | Preview  | Identity provider functionality for authentication         |
| **tailorctl manifest**                                         | Maintenance | CUE-based manifest configuration for tailorctl             |
| **TailorDB Draft**                                             | Deprecated | Draft record functionality - use separate tables instead   |
| **[TailorDB Validate/hook using CEL](/guides/tailordb/hooks)** | Deprecated | CEL-based validation and hooks - migrate to JavaScript     |
| **TailorDB Type/Record Permissions (Legacy)**                  | Deprecated | Legacy permission system - use new permission model        |
| **StateFlow service**                                          | Deprecated | State management service - use built-in permissions or CDC |

---

---
url: https://docs.tailor.tech/reference/platform/timeouts.md
---
# Timeouts

This page documents the various timeout limits in the Tailor Platform services. Understanding these timeouts is essential for building robust applications that can handle potential delays or failures gracefully.

## Overview

Timeouts are enforced across different services in the Tailor Platform to ensure system stability, resource management, and prevent indefinite blocking of resources.
Each service has specific timeout values based on its intended use case and operational requirements.

## Service Timeouts

| Service          | Timeout Value | Description                                                                   | Impact                                                                 |
| ---------------- | ------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| Gateway Timeout  | 60 seconds    | Max time for API gateway request processing                                   | Request terminated if it exceeds 60s                                   |
| Resolver Service | 60 seconds    | Max time for resolver execution                                               | Resolver operation terminated if it exceeds 60s                        |
| Executor Service | 60 seconds    | Max time for `TargetTailorGraphql` and `TargetWebhook` operations to complete | Failure triggers retry (up to 10 attempts) if it exceeds 60s           |
| TailorDB Hooks   | 2 seconds     | Max time for TailorDB's `PreHook` and `PostHook` operations                   | Hook is terminated and returns an error if it exceeds 2s               |
| Resolver Hooks   | 2 seconds     | Max time for a resolver's `PreHook` and `PostHook` operations                 | Hook is terminated and returns an error if it exceeds 2s               |
| Function Service | 60 seconds    | Max time for a Function service operation                                     | Execution is terminated and returns an error if it exceeds 60s         |
| JobFunction      | 24 hours      | Max time for a JobFunction to complete its execution                          | Job function is terminated and returns an error if it exceeds 24 hours |

## Best Practices

When working with services that have timeout constraints, consider the following best practices:

1. **Design for timeouts**: Anticipate timeouts and handle them gracefully.

2. **Implement retry mechanisms**: For operations that might occasionally exceed timeout limits, implement appropriate retry logic with exponential backoff.

3. **Simplify operations**: Break down long tasks into smaller steps to avoid timeouts.

4. **Choose suitable services**: Use services like JobFunction for long-running tasks.

5. **Monitor performance**: Track operation performance to detect timeout risks early.

6. **Optimize queries**: Ensure database queries complete within timeout limits, especially for hooks that have stricter timeout constraints.

7. **Cache frequently accessed data**: Cache frequently accessed data to reduce processing time.

---

---
url: https://docs.tailor.tech/reference/concepts/terminology_concepts.md
---
# Tailor Platform terminology and concepts chart

Testing if we can maintain this page.

| Terms/Concepts | Description                                                                                                                 |
| -------------- | --------------------------------------------------------------------------------------------------------------------------- |
| services       | Tailor Platform is a set of various services, such as TailorDB, Resolver, StateFlow. See Core Concepts for more information |
| workspace      | The root node of the Tailor Platform for your organization.                                                                 |
| organization   | Represents a real life entity, such as a company, and is always associated with a single workspace.                         |
| type           | Corresponding to "table" in SQL term.                                                                                       |
| data type      | Data type such as string, number. Here is supported data types in TailorDB.                                                 |

---

---
url: https://docs.tailor.tech/reference/concepts/trn.md
---
# Tailor Resource Name (TRN)

This page documents the Tailor Resource Name (TRN) format, which uniquely identifies resources within a Workspace in the Tailor Platform.

## Overview

A TRN (Tailor Resource Name) is a standardized identifier format used to uniquely reference resources across the Tailor Platform. TRNs provide a consistent way to identify and reference various platform resources such as TailorDB instances, Pipeline resolvers, Auth configurations, and more.

## TRN Format

The TRN format follows a hierarchical structure with colon-separated components:

```
trn:v1:workspace:<workspace_id>:<resource_type>:<resource_name>[:<sub_resource_type>:<sub_resource_name>]...
```

### Components

| Component             | Description                                                     |
| --------------------- | --------------------------------------------------------------- |
| `trn`                 | Fixed prefix indicating this is a Tailor Resource Name          |
| `v1`                  | Version identifier for the TRN format                           |
| `workspace`           | Fixed identifier indicating the resource belongs to a workspace |
| `<workspace_id>`      | UUID of the workspace containing the resource                   |
| `<resource_type>`     | Type of the resource (e.g., `tailordb`, `pipeline`, `auth`)     |
| `<resource_name>`     | Name or identifier of the specific resource                     |
| `<sub_resource_type>` | Optional sub-resource type for nested resources                 |
| `<sub_resource_name>` | Optional name of the sub-resource                               |

## Supported Resource Types

The following table lists all supported resource types and their TRN formats:

### Workspace

| Resource Type | TRN Format                        | Description          |
| ------------- | --------------------------------- | -------------------- |
| Workspace     | `trn:v1:workspace:<workspace_id>` | The workspace itself |

### Application

| Resource Type | TRN Format                                               | Description                         |
| ------------- | -------------------------------------------------------- | ----------------------------------- |
| Application   | `trn:v1:workspace:<workspace_id>:application:<app_name>` | An application within the workspace |

### TailorDB

| Resource Type           | TRN Format                                                                             | Description                                 |
| ----------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------- |
| TailorDB                | `trn:v1:workspace:<workspace_id>:tailordb:<namespace>`                                 | A TailorDB namespace                        |
| TailorDB Type           | `trn:v1:workspace:<workspace_id>:tailordb:<namespace>:type:<type_name>`                | A Type within a TailorDB namespace          |
| TailorDB GQL Permission | `trn:v1:workspace:<workspace_id>:tailordb:<namespace>:type:<type_name>:gql_permission` | GraphQL permission configuration for a Type |

### Pipeline

| Resource Type     | TRN Format                                                                          | Description                  |
| ----------------- | ----------------------------------------------------------------------------------- | ---------------------------- |
| Pipeline          | `trn:v1:workspace:<workspace_id>:pipeline:<pipeline_name>`                          | A Pipeline service instance  |
| Pipeline Resolver | `trn:v1:workspace:<workspace_id>:pipeline:<pipeline_name>:resolver:<resolver_name>` | A resolver within a Pipeline |

### Auth

| Resource Type | TRN Format                                                                       | Description                                          |
| ------------- | -------------------------------------------------------------------------------- | ---------------------------------------------------- |
| Auth          | `trn:v1:workspace:<workspace_id>:auth:<auth_name>`                               | An Auth service instance                             |
| Machine User  | `trn:v1:workspace:<workspace_id>:auth:<auth_name>:machine_user:<user_name>`      | A machine user for service-to-service authentication |
| OAuth2 Client | `trn:v1:workspace:<workspace_id>:auth:<auth_name>:oauth2_client:<client_name>`   | An OAuth2 client configuration                       |
| SCIM Config   | `trn:v1:workspace:<workspace_id>:auth:<auth_name>:scim_config`                   | SCIM provisioning configuration                      |
| SCIM Resource | `trn:v1:workspace:<workspace_id>:auth:<auth_name>:scim_resource:<resource_name>` | A SCIM resource                                      |
| User Profile  | `trn:v1:workspace:<workspace_id>:auth:<auth_name>:user_profile`                  | User profile configuration                           |
| IdP Config    | `trn:v1:workspace:<workspace_id>:auth:<auth_name>:idp_config:<config_name>`      | Identity Provider configuration                      |

### IdP

| Resource Type | TRN Format                                                            | Description                           |
| ------------- | --------------------------------------------------------------------- | ------------------------------------- |
| IdP           | `trn:v1:workspace:<workspace_id>:idp:<idp_name>`                      | A Built-in Identity Provider instance |
| IdP Client    | `trn:v1:workspace:<workspace_id>:idp:<idp_name>:client:<client_name>` | A client within the Built-in IdP      |

### Vault

| Resource Type | TRN Format                                                                | Description                       |
| ------------- | ------------------------------------------------------------------------- | --------------------------------- |
| Vault         | `trn:v1:workspace:<workspace_id>:vault:<vault_name>`                      | A Vault (Secret Manager) instance |
| Vault Secret  | `trn:v1:workspace:<workspace_id>:vault:<vault_name>:secret:<secret_name>` | A secret within a Vault           |

### Executor

| Resource Type | TRN Format                                                 | Description                  |
| ------------- | ---------------------------------------------------------- | ---------------------------- |
| Executor      | `trn:v1:workspace:<workspace_id>:executor:<executor_name>` | An Executor service instance |

### Workflow

| Resource Type         | TRN Format                                                              | Description                      |
| --------------------- | ----------------------------------------------------------------------- | -------------------------------- |
| Workflow              | `trn:v1:workspace:<workspace_id>:workflow:<workflow_name>`              | A Workflow definition            |
| Workflow Job Function | `trn:v1:workspace:<workspace_id>:workflow_job_function:<function_name>` | A job function used in workflows |

### StateFlow

| Resource Type | TRN Format                                                   | Description                         |
| ------------- | ------------------------------------------------------------ | ----------------------------------- |
| StateFlow     | `trn:v1:workspace:<workspace_id>:stateflow:<stateflow_name>` | A StateFlow definition (deprecated) |

### Static Website

| Resource Type  | TRN Format                                                                            | Description                            |
| -------------- | ------------------------------------------------------------------------------------- | -------------------------------------- |
| Static Website | `trn:v1:workspace:<workspace_id>:staticwebsite:<website_name>`                        | A static website hosting configuration |
| Custom Domain  | `trn:v1:workspace:<workspace_id>:staticwebsite:<website_name>:custom_domain:<domain>` | A custom domain for a static website   |

## Examples

### TailorDB TRN

```
trn:v1:workspace:17838a28-8563-4b79-8305-7df3ba730af6:tailordb:my-namespace
```

This TRN identifies a TailorDB namespace called `my-namespace` in the workspace with ID `17838a28-8563-4b79-8305-7df3ba730af6`.

### TailorDB Type TRN

```
trn:v1:workspace:17838a28-8563-4b79-8305-7df3ba730af6:tailordb:my-namespace:type:User
```

This TRN identifies a Type called `User` within the `my-namespace` TailorDB namespace.

### Pipeline Resolver TRN

```
trn:v1:workspace:17838a28-8563-4b79-8305-7df3ba730af6:pipeline:my-pipeline:resolver:createUser
```

This TRN identifies a resolver called `createUser` within the `my-pipeline` Pipeline.

### Vault Secret TRN

```
trn:v1:workspace:6085f287-9d47-4671-a530-d03c423c32bf:vault:my-vault:secret:api-key
```

This TRN identifies a secret called `api-key` within the `my-vault` Vault.

### OAuth2 Client TRN

```
trn:v1:workspace:17838a28-8563-4b79-8305-7df3ba730af6:auth:my-auth:oauth2_client:web-app
```

This TRN identifies an OAuth2 client called `web-app` within the `my-auth` Auth service.

### Workflow TRN

```
trn:v1:workspace:17838a28-8563-4b79-8305-7df3ba730af6:workflow:order-processing
```

This TRN identifies a Workflow called `order-processing`.

---

---
url: https://docs.tailor.tech/reference/infrastructure/terraform-import.md
---
# Terraform Import

The Tailor Platform Terraform provider supports importing existing resources into your Terraform configuration, allowing you to bring resources that were created through the console or CLI.

## Importing a single resource

You can import a single existing resource by adding a resource configuration block to your Terraform files and then running the `terraform import` command.

### Example

Let's import an existing TailorDB Namespace into your Terraform configuration:

```hcl {{label: "tailordb_example.tf"}}
  resource "tailor_tailordb" "example" {
    id = "trn:v1:workspace:<workspace_id>:tailordb:<namespace>"
  }
```

Then run:

```bash
terraform import tailor_tailordb.example trn:v1:workspace:<workspace_id>:tailordb:<namespace>
```

After importing, run `terraform plan` to verify and adjust the configuration to match the imported state.

## Bulk Import existing workspace resources

You can also import all resources in a workspace by following these steps:

1. Export existing resources:

```bash
tailorctl workspace export --output {OUTPUT_DIRECTORY}
```

2. Create `{OUTPUT_DIRECTORY}/provider.tf`:

```hcl {{ label: "provider.tf"}}
terraform {
  required_providers {
    tailor = {
      source  = "tailor-platform/tailor"
      version = ">= 1.1.1"
    }
  }
}

provider "tailor" {}
```

3. Run `terraform plan` to generate and validate the imported resource configurations:

```bash
terraform plan -generate-config-out=imported_resources.tf
```

Review `imported_resources.tf` to ensure all resources are correctly imported.

## Incremental Importing

Incremental importing allows you to gradually bring resources to your workspace comparing and importing only the resources not already tracked in your current state.

1. Export current state to JSON:

```bash
terraform show -json > existing.json
```

2. Export only resources not in the existing state:

```bash
tailorctl workspace export --output {OUTPUT_DIRECTORY} --state existing.json
```

This will export the resources that are not in the `existing.json` file. Import the new resources using the Terraform import process.

---

---
url: https://docs.tailor.tech/sdk.md
---
# SDK

Learn how to build apps with the Tailor Platform SDK.

## Quick Links

### Documentation

* [Quickstart](quickstart) - Get started with the Tailor Platform SDK quickly
* [Configuration](configuration) - SDK configuration options and settings
* [Testing](testing) - Testing strategies and best practices
* [CLI Reference](cli-reference) - Complete CLI command reference

### Service Guides

* [Auth](services/auth) - Authentication service configuration
* [TailorDB](services/tailordb) - Database service configuration
* [Resolver](services/resolver) - Custom GraphQL resolver service
* [Executor](services/executor) - Event-driven automation service
* [Workflow](services/workflow) - Job orchestration service
* [Plugin](plugin/) - Extend TailorDB types with plugin-generated types, executors, and output files

---

---
url: https://docs.tailor.tech/sdk/quickstart.md
---
# Quickstart

## Getting Started

In this quickstart tutorial, you'll create an app using the Tailor Platform SDK.
Follow the steps below to get started.

## Prerequisite

You'll need a Tailor account to start using the Tailor Platform.
Contact us [here](https://www.tailor.tech/demo) to get started.

### Install Node.js

The SDK requires Node.js 22.18.0 or later. Install Node.js via your package manager by following the official Node.js instructions.

Alternatively, you can use Bun as the runtime.

> **Note:** Bun has a known issue with HTTP/2 connections that may cause intermittent failures during `deploy` or `generate` commands ([bun#14249](https://github.com/oven-sh/bun/issues/14249), [bun#26719](https://github.com/oven-sh/bun/issues/26719)). If you encounter a connection error, retry the command.

### Create an Example App

The following command creates a new project with the required configuration files and example code.

```bash
npm create @tailor-platform/sdk -- --template hello-world example-app
cd example-app
# Or with Bun:
# bun create @tailor-platform/sdk --template hello-world example-app
# cd example-app
```

Before deploying your app, you need to create a workspace:

```bash
npx @tailor-platform/sdk login
npx @tailor-platform/sdk workspace create --name <workspace-name> --region <workspace-region>
npx @tailor-platform/sdk workspace list

# Or with Bun:
# bun tailor login
# bun tailor workspace create --name <workspace-name> --region <workspace-region>

# OR
# Create a new workspace using Tailor Platform Console
# https://console.tailor.tech/
```

## Deploy Your App

Run the deploy command to deploy your project:

```bash
npm run deploy -- --workspace-id <your-workspace-id>
# Or with Bun:
# bun run deploy --workspace-id <your-workspace-id>
```

You can now open the GraphQL Playground and execute the `hello` query:

```graphql
query {
  hello(name: "sdk") {
    message
  }
}
```

## Hello World Example

Here's a simple query resolver from the hello-world template:

```typescript
import { createResolver, t } from "@tailor-platform/sdk";

export default createResolver({
  name: "hello",
  operation: "query",
  input: {
    name: t.string().description("Name to greet"),
  },
  body: (context) => {
    return {
      message: `Hello, ${context.input.name}!`,
    };
  },
  output: t
    .object({
      message: t.string().description("Greeting message"),
    })
    .description("Greeting response"),
});
```

You can edit `src/resolvers/hello.ts` to customize the message:

```typescript
export default createResolver({
  body: (context) => {
    return {
      message: `Goodbye, ${context.input.name}!`,
    };
  },
});
```

Deploy again to see the response.

## Next Steps

* Learn about [TailorDB](services/tailordb) for database schema definition
* Create custom [Resolvers](services/resolver) with business logic
* Set up [Executors](services/executor) for event-driven automation
* Explore [Templates](https://github.com/tailor-platform/sdk/tree/main/packages/create-sdk#available-templates) for more examples

---

---
url: https://docs.tailor.tech/sdk/cli-reference.md
---
# tailor

Tailor Platform SDK - The SDK to work with Tailor Platform

## Usage

```bash
tailor <command> [options]
```

## Global Options

| Option                                      | Alias | Description                                         | Required | Default |
| ------------------------------------------- | ----- | --------------------------------------------------- | -------- | ------- |
| `--env-file <ENV_FILE>`                     | `-e`  | Path to the environment file (error if not found)   | No       | -       |
| `--env-file-if-exists <ENV_FILE_IF_EXISTS>` | -     | Path to the environment file (ignored if not found) | No       | -       |
| `--verbose`                                 | -     | Enable verbose logging                              | No       | `false` |
| `--json`                                    | `-j`  | Output as JSON                                      | No       | `false` |

### JSON Output

For commands that return structured results, passing `--json` writes one parseable JSON document
to stdout on success. Empty successful result sets are emitted as JSON values such as `[]`, not as
human-readable text or empty stdout.

Commands that only perform side effects and do not define a structured result may leave stdout empty
even when `--json` is passed.

Errors, warnings, progress, and diagnostic messages are written to stderr. After argument parsing,
a command failure under `--json` emits a JSON error envelope to stderr. CLI errors include a stable
`error.code` and may include structured `error.next` and `error.context` fields for automated
recovery. Diagnostic lines may precede the error envelope, and stdout is not guaranteed to contain
an error object.

## Common Options

The following options are available for most commands:

| Option           | Short | Description                            |
| ---------------- | ----- | -------------------------------------- |
| `--workspace-id` | `-w`  | Workspace ID (for deployment commands) |
| `--profile`      | `-p`  | Workspace profile                      |
| `--config`       | `-c`  | Path to Tailor config file             |
| `--yes`          | `-y`  | Skip confirmation prompts              |

### Environment File Loading

Both `--env-file` and `--env-file-if-exists` can be specified multiple times and follow Node.js `--env-file` behavior:

* Variables already set in the environment are **not** overwritten
* Later files override earlier files
* `--env-file` files are loaded first, then `--env-file-if-exists` files

```bash
# Load .env (required) and .env.local (optional, if exists)
tailor deploy --env-file .env --env-file-if-exists .env.local

# Load multiple files
tailor deploy --env-file .env --env-file .env.production
```

## Environment Variables

You can use environment variables to configure workspace and authentication:

| Variable                                     | Description                                                                                           |
| -------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `TAILOR_PLATFORM_WORKSPACE_ID`               | Workspace ID for deployment commands                                                                  |
| `TAILOR_PLATFORM_ORGANIZATION_ID`            | Organization ID for organization commands                                                             |
| `TAILOR_PLATFORM_FOLDER_ID`                  | Folder ID for folder commands                                                                         |
| `TAILOR_PLATFORM_TOKEN`                      | Authentication token (alternative to `login`)                                                         |
| `TAILOR_PLATFORM_PROFILE`                    | Workspace profile name                                                                                |
| `TAILOR_CONFIG_PATH`                         | Path to Tailor config file                                                                            |
| `TAILOR_DTS_PATH`                            | Output path for generated `tailor.d.ts` type definition file                                          |
| `TAILOR_PLATFORM_MACHINE_USER_CLIENT_ID`     | Client ID for `login --machine-user`                                                                  |
| `TAILOR_PLATFORM_MACHINE_USER_CLIENT_SECRET` | Client secret for `login --machine-user`                                                              |
| `TAILOR_PLATFORM_MACHINE_USER_NAME`          | Default machine user name for `query`, `workflow start`, `function run`, `machineuser token`          |
| `TAILOR_PLATFORM_URL`                        | Platform API base URL. Saved into profiles created with `profile create --platform-url`               |
| `TAILOR_PLATFORM_OAUTH2_CLIENT_ID`           | OAuth2 client ID for user login. Saved into profiles created with `profile create --oauth2-client-id` |
| `TAILOR_PLATFORM_CONSOLE_URL`                | Console base URL. Saved into profiles created with `profile create --console-url`                     |
| `TAILOR_BUNDLE_CONCURRENCY`                  | Max concurrent bundle workers for `deploy` (resolvers/executors/workflows). Defaults to CPU count     |
| `TAILOR_APPLY_CONCURRENCY`                   | Max concurrent platform RPCs during `apply`/`deploy`. Defaults to 16                                  |
| `VISUAL` / `EDITOR`                          | Preferred editor for commands that open files (e.g., `vim`, `code`, `nano`)                           |
| `TAILOR_CRASH_REPORTS_LOCAL`                 | Local crash log writing: `on` (default) or `off`                                                      |
| `TAILOR_CRASH_REPORTS_REMOTE`                | Automatic crash report submission: `off` (default) or `on`                                            |

### Authentication Token Priority

Token resolution follows this priority order:

1. `TAILOR_PLATFORM_TOKEN` environment variable
2. Profile specified via `--profile` option or `TAILOR_PLATFORM_PROFILE`
3. Current user from platform config (`~/.config/tailor-platform/config.yaml`)

Config-backed login tokens are scoped to the Platform API URL. Profiles with `--platform-url` use the token saved for that URL, so switching profiles can also switch between Platform API environments.

### Workspace ID Priority

Workspace ID resolution follows this priority order:

1. `--workspace-id` command option
2. `TAILOR_PLATFORM_WORKSPACE_ID` environment variable
3. Profile specified via `--profile` option or `TAILOR_PLATFORM_PROFILE`

## CLI Plugins

> \[!WARNING]
> CLI plugins are a **beta** feature. The dispatch behavior and the set of injected environment
> variables may change in a future release.

You can extend the CLI with external plugins, similar to `gh` extensions. When you run a command that
is not a built-in, the CLI looks for an executable named `tailor-<name>` and runs it, forwarding the
remaining arguments:

```bash
# Runs the `tailor-hello` executable with: world --loud
tailor hello world --loud
```

This is how the `@tailor-platform/sdk-plugin-seed` package provides the `seed` commands:

```bash
# Runs `tailor-seed` with: apply
tailor seed apply
```

This also works under a built-in command group. The command path is joined with hyphens, so a plugin
nested under `tailordb` is named `tailor-tailordb-erd`. This is how the
`@tailor-platform/sdk-plugin-tailordb-erd`
package provides the `tailordb erd` commands:

```bash
# Runs `tailor-tailordb-erd` with: export
tailor tailordb erd export
```

Resolution rules:

* **Built-ins always win.** A plugin is only used when no built-in command matches.
* **A command that takes its own arguments is never replaced.** Plugin dispatch applies only to command
  *groups* (commands that just route to subcommands). A command that performs its own action — including
  one that accepts a positional argument — always runs itself, so a plugin can never shadow an argument value.
* **Lookup order:** the project's `node_modules/.bin` (nearest first, walking up from the current
  directory), then your `PATH`. So a plugin installed as a project dev-dependency takes precedence over a
  globally installed one.
* **Place global flags after the plugin command.** Only the arguments following the plugin name are
  forwarded; a global flag placed before it (e.g. `tailor --json tailordb erd export`) is consumed by
  the host CLI and does not reach the plugin. Write `tailor tailordb erd export --json` instead.

Because resolution is based on `node_modules/.bin` and `PATH`, any package manager that populates
`node_modules/.bin` works for project-local plugins — npm, pnpm (its content-addressable store is
transparent here), Bun, and Yarn Classic. The exception is **Yarn Plug'n'Play**, which does not create a
`node_modules` directory: install such plugins globally so they resolve via `PATH`, or use Yarn's
`nodeLinker: node-modules` setting.

Run `tailor plugin list` to see which plugins are discovered and where they resolve from.

## Context passed to plugins

Before running a plugin, the CLI injects the current Tailor Platform context as environment variables so
the plugin does not need to re-implement authentication or re-resolve the active workspace:

| Variable                           | Description                                                              |
| ---------------------------------- | ------------------------------------------------------------------------ |
| `TAILOR_PLATFORM_TOKEN`            | A valid access token (refreshed if needed). Omitted when not logged in.  |
| `TAILOR_PLATFORM_URL`              | The Tailor Platform endpoint in effect                                   |
| `TAILOR_PLATFORM_OAUTH2_CLIENT_ID` | The OAuth2 client ID in effect, for plugins that run their own auth flow |
| `TAILOR_PLATFORM_WORKSPACE_ID`     | The resolved workspace ID, when one can be determined                    |
| `TAILOR_PLATFORM_USER`             | The active user (email when known), when logged in                       |
| `TAILOR_CONFIG_PATH`               | Path to the resolved Tailor config file, when found                      |
| `TAILOR_VERSION`                   | The `tailor` version that invoked the plugin                             |
| `TAILOR_BIN`                       | Path to the `tailor` executable, for calling back into the CLI           |

The token, workspace ID, and user are best-effort: whatever the current context can resolve is injected,
and auth-free plugins still run when you are not logged in. A long-running plugin (or one started on its
own) can obtain a fresh token at any time with `tailor auth token`, which prints a valid access token to
stdout, refreshing it first if it has expired.

## Commands

### [Application Commands](cli/application)

Commands for managing Tailor Platform applications (work with `tailor.config.ts`).

| Command                                         | Description                                                         |
| ----------------------------------------------- | ------------------------------------------------------------------- |
| [init](cli/application.md#init)               | Initialize a new project using create-sdk.                          |
| [generate](cli/application.md#generate)       | Generate files using Tailor configuration.                          |
| [deploy](cli/application.md#deploy)           | Deploy your application by applying the Tailor configuration.       |
| [remove](cli/application.md#remove)           | Remove all resources managed by the application from the workspace. |
| [show](cli/application.md#show)               | Show information about the deployed application.                    |
| [open](cli/application.md#open)               | Open Tailor Platform Console.                                       |
| [api](cli/application.md#api)                 | Call Tailor Platform API endpoints directly.                        |
| [api inspect](cli/application.md#api-inspect) | Print the input message tree of an OperatorService endpoint.        |
| [api list](cli/application.md#api-list)       | List all invocable OperatorService methods.                         |

### [TailorDB Commands](cli/tailordb)

Commands for managing TailorDB tables, data, and schema migrations.

| Command                                                                          | Description                                                                                                                                                                                                                                                                                                               |
| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [tailordb](cli/tailordb.md#tailordb)                                           | Manage TailorDB tables and data.                                                                                                                                                                                                                                                                                          |
| [tailordb truncate](cli/tailordb.md#tailordb-truncate)                         | Truncate (delete all records from) TailorDB tables.                                                                                                                                                                                                                                                                       |
| [tailordb migration](cli/tailordb.md#tailordb-migration)                       | Manage TailorDB schema migrations.                                                                                                                                                                                                                                                                                        |
| [tailordb migration generate](cli/tailordb.md#tailordb-migration-generate)     | Generate migration files by detecting schema differences between current local tables and the previous migration snapshot.                                                                                                                                                                                                |
| [tailordb migration rebaseline](cli/tailordb.md#tailordb-migration-rebaseline) | Collapse the full migration history into a new 0000 baseline.                                                                                                                                                                                                                                                             |
| [tailordb migration script](cli/tailordb.md#tailordb-migration-script)         | Add a migration script (migrate.ts) template to an existing migration directory, or record with --no-script that a migration intentionally has none.                                                                                                                                                                      |
| [tailordb migration set](cli/tailordb.md#tailordb-migration-set)               | Set migration checkpoint to a specific number.                                                                                                                                                                                                                                                                            |
| [tailordb migration status](cli/tailordb.md#tailordb-migration-status)         | Show the current migration status for TailorDB namespaces, including applied and pending migrations.                                                                                                                                                                                                                      |
| [tailordb migration sync](cli/tailordb.md#tailordb-migration-sync)             | Sync remote TailorDB schema to a specific migration snapshot (recovery from --no-schema-check drift).                                                                                                                                                                                                                     |
| [tailordb migration test](cli/tailordb.md#tailordb-migration-test)             | Test pending migrations with seed fixtures or cloned data in a temporary workspace.                                                                                                                                                                                                                                       |
| [tailordb migration validate](cli/tailordb.md#tailordb-migration-validate)     | Validate the full migration history, unreviewed generated migration scripts, and schema drift (local tables vs. migration snapshot, remote schema vs. migration checkpoint) without deploying. This includes the migration and schema-drift checks used by 'deploy' and exits with a non-zero code when issues are found. |

### [Query Commands](cli/query)

Run ad-hoc SQL/GraphQL queries or enter the interactive REPL.

| Command                       | Description            |
| ----------------------------- | ---------------------- |
| [query](cli/query.md#query) | Run SQL/GraphQL query. |

### [User & Auth Commands](cli/user)

Commands for authentication and user management.

| Command                                          | Description                                                                           |
| ------------------------------------------------ | ------------------------------------------------------------------------------------- |
| [login](cli/user.md#login)                     | Login to Tailor Platform.                                                             |
| [logout](cli/user.md#logout)                   | Logout from Tailor Platform.                                                          |
| [auth](cli/user.md#auth)                       | Authentication helpers for scripts and plugins.                                       |
| [auth status](cli/user.md#auth-status)         | Show the active Tailor Platform authentication status without printing tokens.        |
| [auth token](cli/user.md#auth-token)           | Print a valid Tailor Platform access token to stdout, refreshing it first if expired. |
| [user](cli/user.md#user)                       | Manage Tailor Platform users.                                                         |
| [user current](cli/user.md#user-current)       | Show current user.                                                                    |
| [user list](cli/user.md#user-list)             | List all users.                                                                       |
| [user pat](cli/user.md#user-pat)               | Manage personal access tokens.                                                        |
| [user pat create](cli/user.md#user-pat-create) | Create a new personal access token.                                                   |
| [user pat delete](cli/user.md#user-pat-delete) | Delete a personal access token.                                                       |
| [user pat list](cli/user.md#user-pat-list)     | List all personal access tokens.                                                      |
| [user pat update](cli/user.md#user-pat-update) | Update a personal access token (delete and recreate).                                 |
| [user switch](cli/user.md#user-switch)         | Set current user.                                                                     |

### [Organization Commands](cli/organization)

Commands for managing organizations and folders.

| Command                                                                        | Description                                      |
| ------------------------------------------------------------------------------ | ------------------------------------------------ |
| [organization](cli/organization.md#organization)                             | Manage Tailor Platform organizations.            |
| [organization folder](cli/organization.md#organization-folder)               | Manage organization folders.                     |
| [organization folder create](cli/organization.md#organization-folder-create) | Create a new folder in an organization.          |
| [organization folder delete](cli/organization.md#organization-folder-delete) | Delete a folder from an organization.            |
| [organization folder get](cli/organization.md#organization-folder-get)       | Show detailed information about a folder.        |
| [organization folder list](cli/organization.md#organization-folder-list)     | List folders in an organization.                 |
| [organization folder update](cli/organization.md#organization-folder-update) | Update a folder's name.                          |
| [organization get](cli/organization.md#organization-get)                     | Show detailed information about an organization. |
| [organization list](cli/organization.md#organization-list)                   | List organizations you belong to.                |
| [organization tree](cli/organization.md#organization-tree)                   | Display organization folder hierarchy as a tree. |
| [organization update](cli/organization.md#organization-update)               | Update an organization's name.                   |

### [Workspace Commands](cli/workspace)

Commands for managing workspaces and profiles.

| Command                                                           | Description                                                |
| ----------------------------------------------------------------- | ---------------------------------------------------------- |
| [workspace](cli/workspace.md#workspace)                         | Manage Tailor Platform workspaces.                         |
| [workspace app](cli/workspace.md#workspace-app)                 | Manage workspace applications                              |
| [workspace app health](cli/workspace.md#workspace-app-health)   | Check application schema health                            |
| [workspace app list](cli/workspace.md#workspace-app-list)       | List applications in a workspace                           |
| [workspace create](cli/workspace.md#workspace-create)           | Create a new Tailor Platform workspace.                    |
| [workspace delete](cli/workspace.md#workspace-delete)           | Delete a Tailor Platform workspace.                        |
| [workspace get](cli/workspace.md#workspace-get)                 | Show detailed information about a workspace                |
| [workspace list](cli/workspace.md#workspace-list)               | List all Tailor Platform workspaces.                       |
| [workspace restore](cli/workspace.md#workspace-restore)         | Restore a deleted workspace                                |
| [workspace user](cli/workspace.md#workspace-user)               | Manage workspace users                                     |
| [workspace user invite](cli/workspace.md#workspace-user-invite) | Invite a user to a workspace                               |
| [workspace user list](cli/workspace.md#workspace-user-list)     | List users in a workspace                                  |
| [workspace user remove](cli/workspace.md#workspace-user-remove) | Remove a user from a workspace                             |
| [workspace user update](cli/workspace.md#workspace-user-update) | Update a user's role in a workspace                        |
| [profile](cli/workspace.md#profile)                             | Manage workspace profiles (user + workspace combinations). |
| [profile create](cli/workspace.md#profile-create)               | Create a new profile.                                      |
| [profile delete](cli/workspace.md#profile-delete)               | Delete a profile.                                          |
| [profile list](cli/workspace.md#profile-list)                   | List all profiles.                                         |
| [profile update](cli/workspace.md#profile-update)               | Update profile properties.                                 |

### [Auth Resource Commands](cli/auth)

Commands for managing Auth service resources.

| Command                                                            | Description                                                                           |
| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------- |
| [authconnection](cli/auth.md#authconnection)                     | Manage auth connections.                                                              |
| [authconnection authorize](cli/auth.md#authconnection-authorize) | Authorize an auth connection via OAuth2 flow.                                         |
| [authconnection delete](cli/auth.md#authconnection-delete)       | Delete an auth connection entirely.                                                   |
| [authconnection list](cli/auth.md#authconnection-list)           | List all auth connections.                                                            |
| [authconnection open](cli/auth.md#authconnection-open)           | Open the auth connections page in the Tailor Platform Console.                        |
| [authconnection revoke](cli/auth.md#authconnection-revoke)       | Revoke an auth connection's tokens (keeps the connection; use 'delete' to remove it). |
| [machineuser](cli/auth.md#machineuser)                           | Manage machine users in your Tailor Platform application.                             |
| [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](cli/auth.md#oauth2client)                         | Manage OAuth2 clients in your Tailor Platform application.                            |
| [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)

Commands for managing workflows and executions.

| Command                                                      | Description                                    |
| ------------------------------------------------------------ | ---------------------------------------------- |
| [workflow](cli/workflow.md#workflow)                       | Manage workflows and workflow executions.      |
| [workflow list](cli/workflow.md#workflow-list)             | List all workflows in the workspace.           |
| [workflow get](cli/workflow.md#workflow-get)               | Get workflow details.                          |
| [workflow start](cli/workflow.md#workflow-start)           | Start a workflow execution.                    |
| [workflow wait](cli/workflow.md#workflow-wait)             | Wait for a workflow execution.                 |
| [workflow executions](cli/workflow.md#workflow-executions) | List or get workflow executions.               |
| [workflow resume](cli/workflow.md#workflow-resume)         | Resume a failed or pending workflow execution. |

### [Function Commands](cli/function)

Commands for managing function registries and viewing function execution logs.

| Command                                              | Description                                                     |
| ---------------------------------------------------- | --------------------------------------------------------------- |
| [function](cli/function.md#function)               | Manage functions                                                |
| [function get](cli/function.md#function-get)       | Get a function registry by name                                 |
| [function list](cli/function.md#function-list)     | List function registries in a workspace                         |
| [function logs](cli/function.md#function-logs)     | List or get function execution logs.                            |
| [function run](cli/function.md#function-run)       | Run a function on the Tailor Platform server without deploying. |
| [function script](cli/function.md#function-script) | Scaffold a one-off script to run with `function run`.           |

### [Executor Commands](cli/executor)

Commands for managing executors and executor jobs.

| Command                                                          | Description                                   |
| ---------------------------------------------------------------- | --------------------------------------------- |
| [executor](cli/executor.md#executor)                           | Manage executors                              |
| [executor list](cli/executor.md#executor-list)                 | List all executors                            |
| [executor get](cli/executor.md#executor-get)                   | Get executor details                          |
| [executor jobs](cli/executor.md#executor-jobs)                 | List or get executor jobs.                    |
| [executor trigger](cli/executor.md#executor-trigger)           | Trigger an executor manually.                 |
| [executor webhook](cli/executor.md#executor-webhook)           | Manage executor webhooks                      |
| [executor webhook list](cli/executor.md#executor-webhook-list) | List executors with incoming webhook triggers |

### [Secret Commands](cli/secret)

Commands for managing secrets and vaults.

| Command                                                    | Description                                      |
| ---------------------------------------------------------- | ------------------------------------------------ |
| [secret](cli/secret.md#secret)                           | Manage Secret Manager vaults and secrets.        |
| [secret create](cli/secret.md#secret-create)             | Create a secret in a vault.                      |
| [secret delete](cli/secret.md#secret-delete)             | Delete a secret in a vault.                      |
| [secret list](cli/secret.md#secret-list)                 | List all secrets in a vault.                     |
| [secret update](cli/secret.md#secret-update)             | Update a secret in a vault.                      |
| [secret vault](cli/secret.md#secret-vault)               | Manage Secret Manager vaults.                    |
| [secret vault create](cli/secret.md#secret-vault-create) | Create a new Secret Manager vault.               |
| [secret vault delete](cli/secret.md#secret-vault-delete) | Delete a Secret Manager vault.                   |
| [secret vault list](cli/secret.md#secret-vault-list)     | List all Secret Manager vaults in the workspace. |

### [Static Website Commands](cli/staticwebsite)

Commands for managing and deploying static websites.

| Command                                                                       | Description                                           |
| ----------------------------------------------------------------------------- | ----------------------------------------------------- |
| [staticwebsite](cli/staticwebsite.md#staticwebsite)                         | Manage static websites in your workspace.             |
| [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 domain](cli/staticwebsite.md#staticwebsite-domain)           | Manage custom domains for static websites.            |
| [staticwebsite domain get](cli/staticwebsite.md#staticwebsite-domain-get)   | Get details of a custom domain.                       |
| [staticwebsite domain list](cli/staticwebsite.md#staticwebsite-domain-list) | List custom domains for a static website.             |
| [staticwebsite get](cli/staticwebsite.md#staticwebsite-get)                 | Get details of a specific static website.             |

### [Crash Report Commands](cli/crashreport)

Commands for managing crash reports.

| Command                                                   | Description                                    |
| --------------------------------------------------------- | ---------------------------------------------- |
| [crashreport](cli/crashreport.md#crashreport)           | Manage crash reports.                          |
| [crashreport list](cli/crashreport.md#crashreport-list) | List local crash report files.                 |
| [crashreport send](cli/crashreport.md#crashreport-send) | Submit a crash report to help improve the SDK. |

### [Upgrade Commands](cli/upgrade)

Commands for upgrading SDK versions with automated code migration.

| Command                             | Description                                                  |
| ----------------------------------- | ------------------------------------------------------------ |
| [upgrade](cli/upgrade.md#upgrade) | Run codemods to upgrade your project to a newer SDK version. |

### [Skills Commands](cli/skills)

Commands for managing Tailor SDK agent skills.

| Command                                        | Description                                   |
| ---------------------------------------------- | --------------------------------------------- |
| [skills](cli/skills.md#skills)               | Manage Tailor SDK agent skills.               |
| [skills add](cli/skills.md#skills-add)       | Install Tailor SDK agent skills.              |
| [skills list](cli/skills.md#skills-list)     | List Tailor SDK agent skills.                 |
| [skills remove](cli/skills.md#skills-remove) | Remove installed Tailor SDK agent skills.     |
| [skills sync](cli/skills.md#skills-sync)     | Remove and reinstall Tailor SDK agent skills. |

### [Plugin Commands](cli/plugin)

Discover and inspect CLI plugins (external `tailor-<name>` executables).

| Command                                    | Description                                                                              |
| ------------------------------------------ | ---------------------------------------------------------------------------------------- |
| [plugin](cli/plugin.md#plugin)           | Manage and inspect CLI plugins (beta).                                                   |
| [plugin list](cli/plugin.md#plugin-list) | List discovered plugins (executables named `<cli>-<name>` on PATH or node\_modules/.bin). |

### [Completion](cli/completion)

Generate shell completion scripts for bash, zsh, and fish.

| Command                                      | Description                      |
| -------------------------------------------- | -------------------------------- |
| [completion](cli/completion.md#completion) | Generate shell completion script |

---

---
url: https://docs.tailor.tech/sdk/configuration.md
---
# Configuration

The SDK uses TypeScript for configuration files. By default, it uses `tailor.config.ts` in the project root. You can specify a different path using the `--config` option.

For service-specific documentation, see:

* [TailorDB](services/tailordb) - Database schema definition
* [Resolver](services/resolver) - Custom GraphQL resolvers
* [Executor](services/executor) - Event-driven handlers
* [Workflow](services/workflow) - Job orchestration
* [Auth](services/auth) - Authentication and authorization
* [IdP](services/idp) - Built-in identity provider
* [Static Website](services/staticwebsite) - Static file hosting
* [Secret Manager](services/secret) - Secure credential storage

To deploy the same config to multiple workspaces with per-environment values, see [Multi-Environment Configuration](multi-environment).

## Application Settings

```typescript
import { defineConfig } from "@tailor-platform/sdk";

export default defineConfig({
  // SDK-managed app id — do not edit, except when copying this config to a separate app.
  // id: "<uuid>" — written here automatically on first run
  name: "my-app",
  cors: ["https://example.com"],
  allowedIpAddresses: ["192.168.1.0/24"],
  disableIntrospection: false,
  logLevel: process.env.TAILOR_APP_LOG_LEVEL ?? "DEBUG",
});
```

**Name**: Set the application name.

**Id (auto-managed)**: A stable identifier used to recognize resources managed by the SDK across renames. On first `deploy`, the SDK injects an `id: "<uuid>"` field into your `defineConfig({...})` call and commits it to `tailor.config.ts`. Keep it under version control; do not edit it by hand. Delete it only if you want the SDK to assign a new id on the next `deploy` — typically when `tailor.config.ts` was copied from another project and the new application should not share the original's id. Auto-injection requires `defineConfig({...})` to be called with an inline object literal: if the argument is a separate variable (e.g. `defineConfig(config)`), or if `tailor.config.ts` is a wrapper that re-exports `defineConfig` from another file, the SDK cannot inject — add the `id` field manually to the file that contains the actual `defineConfig({...})` object literal.

**CORS**: Specify CORS settings as an array. You can also include Static Website URL references (e.g. `website.url`) in this array; see [Static Website](services/staticwebsite).

**Allowed IP Addresses**: Specify IP addresses allowed to access the application in CIDR format.

**Disable Introspection**: Disable GraphQL introspection. Default is `false`.

**Log Level**: Controls which `console.*` and `logger.*` (from `@tailor-platform/sdk/runtime`) calls are kept when deployment functions are bundled. Supported values are `"DEBUG"`, `"INFO"`, `"WARN"`, `"ERROR"`, and `"SILENT"`. The default is `"DEBUG"` and keeps all 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, alongside `console.debug` and `logger.debug`. `logger.setAttributes` has no severity and is never dropped, regardless of `logLevel`. For production deployments, use `"WARN"` to keep warn/error calls while dropping debug, log, and info calls:

```typescript
export default defineConfig({
  name: "my-app",
  logLevel: process.env.TAILOR_APP_LOG_LEVEL ?? "DEBUG",
});
```

This is a bundle-time setting. Changing `TAILOR_APP_LOG_LEVEL` affects newly bundled deployments; already deployed functions must be redeployed.

Only `logger.*` calls made through the SDK's `logger` wrapper (from `@tailor-platform/sdk/runtime` or its `@tailor-platform/sdk/runtime/logger` subpath), or written as `globalThis.tailor.logger.*`, are covered. Other equivalent forms — such as the bare `tailor.logger.*` global or `self.tailor.logger.*` — are not affected by `logLevel`.

### Service Configuration

Specify glob patterns to load service files:

```typescript
export default defineConfig({
  db: {
    "my-db": {
      files: ["db/**/*.ts"],
      ignores: ["db/**/*.draft.ts"],
    },
  },
  resolver: {
    "my-resolver": {
      files: ["resolver/**/*.ts"],
      defaultPermission: [{ conditions: [[{ user: "_loggedIn" }, "=", true]], permit: true }],
    },
  },
  executor: {
    files: ["executors/**/*.ts"],
  },
  workflow: {
    files: ["workflows/**/*.ts"],
  },
});
```

**files**: Glob patterns to match files. Required.

**ignores**: Glob patterns to exclude files. Optional. By default, `**/*.test.ts` and `**/*.spec.ts` are automatically ignored. If you explicitly specify `ignores`, the default patterns will not be applied. Use `ignores: []` to include all files including test files.

**defaultPermission** (resolver namespaces only): Access requirement applied to every resolver in the namespace that declares no `permission` of its own. Optional, and takes the same values as a resolver's own `permission`. See [Namespace-wide default](services/resolver.md#namespace-wide-default-defaultpermission).

**Pattern resolution**: `files` and `ignores` patterns are resolved relative to the directory of the `tailor.config.ts` file that declares them, not the directory you run the command from. This matters when deploying [multiple configs](cli/application.md#deploy) together — each config's patterns only match files under its own directory. If a config's *relative* patterns match nothing under its own directory, the SDK falls back to resolving them from the directory you ran the command from and logs a warning (this fallback doesn't apply to already-absolute patterns, since their resolution can't change). Update such patterns to be relative to the config's own directory — this fallback will be removed in v2.

### Bundling

Resolvers, executors, workflow jobs, auth hooks, HTTP adapters, TailorDB hooks and validators, functions, seeds, queries, and migration scripts are all bundled before running locally or deploying. Bundling honors `compilerOptions.paths` aliases declared in a `tsconfig.json`, resolved against the importing file's own nearest `tsconfig.json` (the first one found walking up from that file's directory, following its `extends` chain) — so a path alias works the same whether it is imported directly or through another aliased import.

An import that cannot be resolved fails the command instead of shipping a broken bundle, naming the specifier, the importing file, and the tsconfig the build used:

```
Error [UNRESOLVED_IMPORT]: Could not resolve "@lib/missing" imported from "/path/to/resolver.ts".
  Suggestion: Check that each import path is correct, and that a `compilerOptions.paths`
  entry covering it is declared in the importing file's own tsconfig.json or an ancestor.
  The build used "/path/to/tsconfig.json".
```

If the unresolved specifier is a Node.js built-in (e.g. `fs`, `crypto`, `path`), the suggestion explains that it is not available in the Tailor Platform runtime and, where one exists, names a Web-standard replacement (e.g. the Fetch API instead of `http`/`https`).

### External Resources

You can reference resources managed by Terraform or other SDK projects to include them in your application's subgraph. External resources are not deployed by this project but can be used for shared access across multiple applications.

```typescript
export default defineConfig({
  name: "my-app",
  db: {
    "shared-db": { external: true },
  },
  resolver: {
    "my-resolver": { external: true },
  },
  auth: { name: "shared-auth", external: true },
  idp: [{ name: "shared-idp", external: true }],
});
```

**external**: Set to `true` to reference an external resource. The resource must already exist and be managed by another project (e.g., Terraform or another SDK application).

When using external resources:

* The resource itself is not deployed by this project
* The resource must be deployed and available before referencing it
* You can combine external resources with locally-defined resources
* TailorDB table names must remain unique across local and external TailorDB namespaces; `deploy` checks external TailorDB table names before applying changes
* Destructive operations like `tailordb truncate` (and `tailor seed apply --truncate`) automatically exclude external resources to prevent accidental data loss in shared resources
* Subscribing an executor to an external resource's events requires the config that owns the resource in the same `deploy`. Publishing is then enabled automatically, and `deploy` records the dependency so a later deploy without that config asks for confirmation instead of silently turning publishing off

### Built-in IdP

Configure the Built-in IdP service using `defineIdp()`. See [IdP](services/idp) for full documentation.

```typescript
import { defineIdp } from "@tailor-platform/sdk";

const idp = defineIdp("my-idp", {
  clients: ["my-client"],
  permission: {
    create: [{ conditions: [[{ user: "_loggedIn" }, "=", true]], permit: true }],
    read: [{ conditions: [[{ user: "_loggedIn" }, "=", true]], permit: true }],
    update: [{ conditions: [[{ user: "_loggedIn" }, "=", true]], permit: true }],
    delete: [{ conditions: [[{ user: "_loggedIn" }, "=", true]], permit: true }],
    sendPasswordResetEmail: [{ conditions: [[{ user: "_loggedIn" }, "=", true]], permit: true }],
  },
});

export default defineConfig({
  idp: [idp],
});
```

### Auth Service

Configure Auth service using `defineAuth()`. See [Auth](services/auth) for full documentation.

```typescript
import { defineAuth } from "@tailor-platform/sdk";
import { user } from "./tailordb/user";

const auth = defineAuth("my-auth", {
  userProfile: {
    type: user,
    usernameField: "email",
    attributes: { role: true },
  },
  idProvider: idp.provider("my-provider", "my-client"),
});

export default defineConfig({
  auth,
});
```

### Static Websites

Configure static website hosting using `defineStaticWebSite()`. See [Static Website](services/staticwebsite) for full documentation.

```typescript
import { defineStaticWebSite } from "@tailor-platform/sdk";

const website = defineStaticWebSite("my-website", {
  description: "My Static Website",
});

export default defineConfig({
  staticWebsites: [website],
});
```

### Secret Manager

Configure secrets using `defineSecretManager()`. See [Secret Manager](services/secret) for full documentation.

```typescript
import { defineSecretManager } from "@tailor-platform/sdk";

export const secrets = defineSecretManager({
  "api-keys": {
    "stripe-secret-key": process.env.STRIPE_SECRET_KEY!,
    "sendgrid-api-key": process.env.SENDGRID_API_KEY!,
  },
});

export default defineConfig({
  secrets,
});
```

### Environment Variables

Use `env` in `defineConfig()` for non-secret values that application code needs at runtime, such as environment names, feature flags, and public service URLs. Values must be strings, numbers, or booleans.

```typescript
export default defineConfig({
  name: "my-app",
  env: {
    foo: 1,
    bar: "hello",
    baz: true,
  },
});
```

`tailor.config.ts` runs locally when an SDK command loads the config. If values come from your shell or an env file, SDK commands can load them before config evaluation with the global [`--env-file`](cli-reference.md#environment-file-loading) and `--env-file-if-exists` options:

```typescript
export default defineConfig({
  name: "my-app",
  env: {
    foo: Number(process.env.FOO ?? "1"),
    bar: process.env.BAR ?? "hello",
    baz: (process.env.BAZ ?? "true") === "true",
  },
});
```

If the same config defines an auth before-login hook, make sure the config module can be evaluated without Node-only globals in the platform runtime. Avoid arbitrary `process.env` reads in that module; pass literal values, or values generated into a config module before deployment, and read them from the hook's `env` argument.

When the SDK deploys application code or runs detected service code with `function run`, it passes the resolved values as the `env` argument. Do not read `process.env` from deployed resolvers, executors, workflow jobs, auth hooks, or migration scripts; Node-side environment variables are not available there. Put sensitive values in [Secret Manager](services/secret) instead of `env`.

| Code location             | Runtime access                                                                                                                            |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Resolver body             | `body: ({ env }) => ...`                                                                                                                  |
| Executor callbacks        | `body: ({ env }) => ...`, `url: ({ env }) => String(env.bar)`, `variables: ({ env }) => ({ enabled: env.baz })`, or similar callback args |
| Workflow job body         | `body: (input, { env }) => ...`                                                                                                           |
| Auth before-login hook    | `handler: async ({ env }) => ...`                                                                                                         |
| TailorDB migration script | `main(trx, { env }: MigrationContext)`                                                                                                    |
| `function run`            | Same `env` argument shape as the detected resolver, executor, or workflow job                                                             |

```typescript
// In resolvers
body: ({ input, env }) => {
  return {
    result: input.multiplier * env.foo,
    message: env.bar,
    enabled: env.baz,
  };
};

// In executors
body: ({ newRecord, env }) => {
  console.log(`Environment: ${env.bar}, User: ${newRecord.name}`);
};

// In workflow jobs
body: (input, { env }) => {
  console.log(`Environment: ${env.bar}`);
  return { value: env.foo };
};

// In auth before-login hooks
hooks: {
  beforeLogin: {
    handler: async ({ claims, idpConfigName, env }) => {
      console.log(`Environment: ${env.bar}`);
    },
    invoker: "hook-invoker",
  },
};

// In TailorDB migration scripts
export async function main(trx: Transaction, { env }: MigrationContext): Promise<void> {
  if (!env.baz) return;
  await trx.updateTable("User").set({ stage: env.bar }).execute();
}
```

#### Secret Detection

`env` values are deployed as plaintext, so loading a config fails when one of them looks like a credential:

```
✖ Secret detected in 'env' in /path/to/tailor.config.ts:
  - env.SLACK_BOT_TOKEN (matched slack: SLACK_TOKEN)
    https://github.com/secretlint/secretlint/blob/master/packages/%40secretlint/secretlint-rule-slack/README.md#SLACK_TOKEN
```

Each finding names the pattern that matched and links to its description, so a value flagged as an AWS account id is distinguishable from one flagged as an AWS secret access key.

Move the value to [Secret Manager](services/secret) to fix this. Detection recognizes the credential formats published by common providers, such as Slack, GitHub and AWS.

A value that is merely long and random-looking, with no recognizable provider format, is reported as a warning instead and does not fail the command.

When detection is wrong about a value, allow it in place with `allowSecretReason`, stating why the value is safe to deploy as plaintext:

```typescript
export default defineConfig({
  name: "my-app",
  env: {
    slackRelayUrl: {
      value: process.env.SLACK_RELAY_URL ?? "",
      allowSecretReason: "Public relay endpoint; the token it proxies stays in Secret Manager.",
    },
  },
});
```

This silences both the failure and the warning, so it also covers a value that is random-looking without being a credential — say so in the reason. Only string and number values accept an allowance: a boolean is never flagged, so it never needs one.

Application code still reads `env.slackRelayUrl` as the value itself: the wrapper only carries the reason and does not reach the deployed application.

### Workflow Service

Configure Workflow service by specifying glob patterns for workflow files:

```typescript
export default defineConfig({
  workflow: {
    files: ["workflows/**/*.ts"],
    ignores: ["workflows/**/*.draft.ts"],
  },
});
```

**files**: Glob patterns to match workflow files. Required.

**ignores**: Glob patterns to exclude files. Optional.

### Workflow Execution Policies

Register workspace-scoped execution policies that workflow job functions reference at runtime for per-key concurrency control. See [Execution Policies](services/workflow.md#execution-policies) in the Workflow guide for the declaration API.

```typescript
import { defineWorkflowExecutionPolicies } from "@tailor-platform/sdk";

const executionPolicies = defineWorkflowExecutionPolicies((define) => ({
  premium: define({ concurrencyPolicy: { maxConcurrentExecutions: 5 } }),
  tenantApi: define({
    name: "tenant-api",
    matchType: "prefix",
    concurrencyPolicy: { maxConcurrentExecutions: 3 },
  }),
}));

export default defineConfig({
  workflow: {
    files: ["workflows/**/*.ts"],
    executionPolicies,
  },
});
```

### Plugins

Configure plugins using `definePlugins()`. Plugins must be exported as a named export.

```typescript
import { definePlugins } from "@tailor-platform/sdk";
import { kyselyTypePlugin } from "@tailor-platform/sdk/plugin/kysely-type";
import { enumConstantsPlugin } from "@tailor-platform/sdk/plugin/enum-constants";

export const plugins = definePlugins(
  kyselyTypePlugin({ distPath: "./generated/tailordb.ts" }),
  enumConstantsPlugin({ distPath: "./generated/enums.ts" }),
);
```

---

---
url: https://docs.tailor.tech/sdk/github-actions.md
---
# GitHub Actions Integration

`tailor setup` generates GitHub repository automation for your Tailor Platform
application, including deploy workflows and Renovate configuration.

> **Beta:** This command is under active development. CLI flags, the generated
> workflow, and the `.github/tailor.lock` schema may change before general
> availability.

## Installation

The `setup` commands are provided by the `@tailor-platform/sdk-plugin-setup` CLI
plugin. Install it next to the SDK:

```bash
npm install -D @tailor-platform/sdk-plugin-setup
```

The Tailor CLI discovers the plugin automatically from `node_modules/.bin` (or
your `PATH`). Run `tailor plugin list` to confirm it resolves.

## Quick start

Run the command from the root of your SDK project (where `tailor.config.ts`
lives):

```bash
# Branch target: deploy to stg on every push to main
tailor setup branch --name my-app-stg

# Tag target: deploy to production when a tag is pushed, with an approval gate
tailor setup tag --name my-app-prod \
  --branch main --environment production
```

After running the command, follow the **Next steps** printed to the terminal to
set the required secrets, set the `TAILOR_PLATFORM_WORKSPACE_ID` variable, and
commit the generated files.

The generated workflow deploys to whichever workspace its
`TAILOR_PLATFORM_WORKSPACE_ID` Environment variable points at — it never
creates or renames a workspace. Provision the workspace and set that variable
before the first deploy (see [Targeting a workspace](#targeting-a-workspace)).

## Targets

A *target* is one workflow file that handles one deployment destination.
Run `setup` once per target.

### Branch target (recommended for staging)

The branch target fires on pull requests and pushes to the branch you specify
(defaulting to the repository's default branch when `--target` is
omitted):

```bash
tailor setup branch --name my-app-stg
# Equivalent to:
tailor setup branch --name my-app-stg --target main
```

What it does:

* On **pull request**: runs `generate`, checks that generated files are
  committed (`generate-check`), and posts a deployment plan as a PR comment.
  (The plan and deploy jobs are independent; pull requests run plan only.)
* On **push to the branch**: deploys. The deploy action runs `generate` and
  applies the config; it does not re-run the PR plan.
* On **`workflow_dispatch`** with `dry-run: true`: runs plan only (useful for
  rollback verification — see [Rollback](#rollback)). With `dry-run: false`
  (default) it deploys, like a push.

Fork pull requests cannot read repository secrets. For forks, the plan step is
automatically skipped; `generate-check` and other non-secret checks still run.

## ERD preview artifacts

Pass `--erd-preview` on a branch target to add TailorDB ERD preview artifacts
to pull requests:

```bash
tailor setup branch --name my-app-stg --erd-preview
```

The generated workflow runs `tailor tailordb erd`, which is provided by the
`@tailor-platform/sdk-plugin-tailordb-erd` CLI plugin — install it as a
dev-dependency in your project:

```bash
npm install -D @tailor-platform/sdk-plugin-tailordb-erd
```

The generated workflow builds one self-contained ERD viewer HTML file for each
owned TailorDB namespace in `tailor.config.ts`. The viewer compares the pull
request merge result with the base branch, can switch between the current schema
and highlighted diff, uploads the HTML files as unarchived Actions artifacts,
and upserts a PR comment with artifact links.

ERD preview does not use Tailor Platform credentials. Fork pull requests still
build artifacts, but the comment step is skipped because fork tokens cannot
write PR comments.

`--erd-preview` is only available for branch targets. The namespace list is
recorded in `.github/tailor.lock`; the pull request workflow compares the head
and base lock files so newly added or removed namespaces can still produce
all-added or all-removed viewer artifacts. Re-run `setup branch` after adding or
removing TailorDB namespaces. `setup check` reports drift when the recorded ERD
preview namespaces no longer match the current config.

### Tag target (recommended for production)

The tag target fires when a tag matching `--tag-pattern` (default `v*`) is
pushed:

```bash
tailor setup tag --name my-app-prod \
  --tag-pattern "v*" --branch main --environment production
```

What it does:

* **`tailor-tag-guard`** (generated when `--branch` is supplied): checks that
  the tagged commit is reachable from `main`. A tag on an unrelated commit is
  silently skipped, not an error.
* **`tailor-plan`**: runs `generate`, `generate-check`, and posts a plan
  summary to the Actions step summary (no PR comment, because there is no PR).
* **`tailor-deploy`**: waits for `tailor-plan`, then deploys. If the target
  environment has required reviewers configured, GitHub requires their approval
  before the deploy job starts.
* On **`workflow_dispatch`**: the `tailor-tag-guard` result is ignored — the
  plan job runs regardless of branch reachability (useful for rolling back to
  any tag). `dry-run: true` stops before the deploy job.

### Choosing `--branch` for the tag target

The branch each target reads plays a different role, under a different flag:

| Target | Flag       | Role                                                                                           |
| ------ | ---------- | ---------------------------------------------------------------------------------------------- |
| Branch | `--target` | The branch that triggers the workflow (push + PR base). Defaults to the repo's default branch. |
| Tag    | `--branch` | The branch whose history the tag must be reachable from. Omit to disable the guard entirely.   |

The workspace name (`--name`, or the config `name` when omitted) must
be 3–63 characters of lowercase letters, numbers, and hyphens, and cannot start
or end with a hyphen. It is used for the generated file name, the workflow
`name:`, the plan label, and the default GitHub Environment name; it does not
select which workspace gets deployed (see
[Targeting a workspace](#targeting-a-workspace)).

## Targeting a workspace

The generated `plan` and `deploy` jobs target a workspace by **id**, read from
the `TAILOR_PLATFORM_WORKSPACE_ID` GitHub Environment variable. They never
resolve a workspace by name and never create one. Set this variable per
environment before the first deploy.

Because the variable is scoped to a GitHub Environment, both the `plan` and
`deploy` jobs declare `environment:` so the value resolves. When you omit
`--environment`, the environment name defaults to the workspace name.

1. Provision the workspace (once per environment) and obtain its id. For now
   this is a manual step:

   ```bash
   tailor workspace create   # copy the printed workspace id
   ```

2. Set the id as the Environment variable (the environment name is your
   `--environment` value, or the workspace name when omitted):

   ```bash
   gh variable set TAILOR_PLATFORM_WORKSPACE_ID --env my-app-stg
   ```

If `TAILOR_PLATFORM_WORKSPACE_ID` is unset, `deploy` fails because the target
workspace is not provisioned, and `plan` reports that the workspace is not
provisioned yet instead of running a dry-run.

If the target environment has required reviewers, that approval gate applies to
the `plan` job as well as `deploy`, because `plan` must enter the environment to
read the variable. (A token-based read that lets `plan` run without entering the
environment is planned.)

## Generated files

Running a workflow setup subcommand creates or updates:

### `.github/workflows/tailor-<workspace-name>.yml`

The workflow file. The `name:` field is set to `Tailor (<workspace-name>)` so
you can distinguish multiple workspaces in the Actions UI.

Jobs and steps whose `id` starts with `tailor-` are managed by the SDK. Do not
edit or rename them — the SDK tracks them by id.

You can add your own jobs and steps around the managed ones. To add
project-specific setup (such as private registry authentication or a system
dependency), add a step *before* the managed `tailor-setup` step. For
post-install extras (such as `playwright install`), add a step *after* it.

Note that re-running `setup` currently regenerates the whole file: if
the file differs from what the SDK last wrote — whether you edited a managed
step or added your own — the command stops and reports the conflict. Pass
`--force` to discard your edits and regenerate from the current template, then
re-apply your own steps. (Preserving user-added steps across regeneration is
planned.)

### `.github/tailor.lock`

A machine-owned JSON file that tracks which files the SDK manages, the inputs
they were generated from, and their content hashes. **Commit this file. Never
edit it by hand.** The SDK uses it to recognize its own files on re-runs and to
detect hand edits.

### `tailor.config.ts` (id injection)

If your config does not already have an `id` field, `setup` injects one.
This `id` must be committed alongside the workflow file. In CI, `tailor
deploy` refuses to inject a new id — if the id were assigned fresh on each CI
run, every deploy would create a brand-new application and lose ownership of
previously deployed resources.

If your pipeline intentionally deploys a fresh, throwaway application on every
run (for example an end-to-end test harness that creates and deletes its own
workspace), set `TAILOR_CI_ALLOW_ID_INJECTION=true` to opt back
into automatic id injection for that pipeline.

## Secrets

The generated workflow reads two secrets:

| Secret                                       | Description                |
| -------------------------------------------- | -------------------------- |
| `TAILOR_PLATFORM_MACHINE_USER_CLIENT_ID`     | Machine user client ID     |
| `TAILOR_PLATFORM_MACHINE_USER_CLIENT_SECRET` | Machine user client secret |

Set them on the target GitHub Environment (the `--environment` value, or the
workspace name when omitted) with the GitHub CLI:

```bash
gh secret set TAILOR_PLATFORM_MACHINE_USER_CLIENT_ID --env my-app-stg
gh secret set TAILOR_PLATFORM_MACHINE_USER_CLIENT_SECRET --env my-app-stg
```

Setting them at the environment level isolates each target's credentials and
keeps them alongside that environment's `TAILOR_PLATFORM_WORKSPACE_ID`
variable. You can also set them as repository-level secrets if every target
shares one machine user.

## GitHub Environments (approval gate)

Both the `plan` and `deploy` jobs are associated with a GitHub Environment — the
`--environment` value, or the workspace name when omitted. The environment holds
that target's `TAILOR_PLATFORM_WORKSPACE_ID` variable and machine-user secrets,
and lets you:

* **Require reviewer approval** before the jobs run (suitable for production).
* **Scope secrets and the workspace-id variable** to specific environments so
  staging and production deploy to separate workspaces with separate machine
  users.

To configure the environment, go to your repository's **Settings → Environments**
and create an environment whose name matches the target's environment. Add
required reviewers, the `TAILOR_PLATFORM_WORKSPACE_ID` variable, and the
environment-scoped secrets there.

Required reviewers gate the `plan` job as well, because `plan` must enter the
environment to read `TAILOR_PLATFORM_WORKSPACE_ID`. (A token-based read that
lets `plan` run without entering the environment is planned.)

## Manual runs and dry-run

You can trigger the workflow manually from **Actions → Run workflow**. The
`dry-run` input (boolean, default `false`) runs the plan job without
deploying. Use this to preview what would change before executing a rollback
or an out-of-band deploy. With `dry-run` off, a branch-target dispatch goes
straight to deploy (like a push), while a tag-target dispatch runs plan first
and then deploys.

For tag targets, you can select any branch or tag when dispatching manually. The tag-guard check is skipped for manual dispatches, so
you can deploy any commit regardless of branch membership.

## Monorepo setup

For a monorepo where your SDK app lives in a subdirectory, pass `--dir`:

```bash
tailor setup branch --name my-app --dir apps/backend
```

The generated workflow adds a `paths` filter on `apps/backend/**` so the
workflow only runs when that subdirectory changes. The `working-directory` for
SDK commands is set accordingly.

## Rollback

`tailor deploy` is declarative: redeploying a past configuration returns
the platform to that state. The recommended rollback approaches are:

### Option 1 — Revert the commit (branch target)

```bash
git revert <commit-sha>
git push
```

The push triggers the deploy job, which applies the reverted configuration. To
preview the diff first, open the revert as a pull request (the plan job comments
the diff) or use a `dry-run: true` manual dispatch before merging.

### Option 2 — Advance the tag (tag target)

Move the production tag to an earlier commit:

```bash
git tag -f v1.2.3 <earlier-commit-sha>
git push --force-with-lease origin v1.2.3
```

Or create a new tag that points to the earlier commit:

```bash
git tag v1.2.4 <earlier-commit-sha>
git push origin v1.2.4
```

### Option 3 — Manual dispatch with dry-run verification

1. Go to **Actions → `Tailor (<workspace-name>)` → Run workflow**.
2. Enter the tag or ref you want to redeploy.
3. Set `dry-run` to `true` and run. Inspect the plan output.
4. Run again with `dry-run` set to `false`.

For tag targets, the tag-guard step is bypassed on manual dispatch, so you can
dispatch from any ref. Environment approval (if configured) applies as usual.

### Rollback limitations

* **Schema and data are not rolled back.** If the older config expects a schema
  state that no longer exists, the plan may show errors. In that case, review
  the diff carefully before proceeding.
* **Seed data** is not part of the deployment pipeline and is unaffected by
  rollbacks.
* **Static websites** are not yet integrated into the generated pipeline.
  Static asset rollbacks must be performed manually.

## Multi-environment example

A typical setup with staging and production:

```bash
# Staging: main → stg (deploy on every push to main)
tailor setup branch --name my-app-stg

# Production: tagged commits → prod, with approval gate and branch guard
tailor setup tag --name my-app-prod \
  --branch main --environment production
```

Then provision each workspace and set its id on the matching environment (the
staging target's environment defaults to `my-app-stg`; production uses
`production`):

```bash
gh variable set TAILOR_PLATFORM_WORKSPACE_ID --env my-app-stg
gh secret set TAILOR_PLATFORM_MACHINE_USER_CLIENT_ID --env my-app-stg
gh secret set TAILOR_PLATFORM_MACHINE_USER_CLIENT_SECRET --env my-app-stg

gh variable set TAILOR_PLATFORM_WORKSPACE_ID --env production
gh secret set TAILOR_PLATFORM_MACHINE_USER_CLIENT_ID --env production
gh secret set TAILOR_PLATFORM_MACHINE_USER_CLIENT_SECRET --env production
```

Commit both workflow files and `.github/tailor.lock`.

## Keeping dependencies and actions updated

Run this command once from the repository root to add Renovate configuration:

```bash
tailor setup deps
```

It generates `renovate.json`, which extends Tailor's shared Renovate preset. The
preset groups `@tailor-platform/*` package updates into one pull request and
lets Renovate update the SHA-pinned GitHub Actions used by generated workflows.
Enable Renovate for the repository by following the
Renovate onboarding guide,
then commit the generated file.

If the repository already has Renovate configuration, the command adds
`github>tailor-inc/renovate-config` to its `extends` array in place instead of
writing a new file, leaving your other settings untouched. It checks Renovate's
standard root, `.github`, `.gitlab`, and `.renovaterc` locations, including the
deprecated `package.json` configuration. When that configuration already extends
the preset, the command reports that Renovate is set up and changes nothing.

JSONC and JSON5 configurations are updated in place while preserving their
comments and formatting. Configurations that Renovate itself cannot load — such
as invalid syntax, or duplicate keys outside JSON5 — are left unchanged and
reported for manual inspection.

`renovate.json` is yours to edit — it is not tracked in `.github/tailor.lock`.
Add your own rules freely; re-running `tailor setup deps` does not overwrite
them. To remove it, delete the file.

Renovate updates the SDK dependency and action pins, but it does not regenerate
the workflow template. After an SDK update, `tailor setup check --ci` reports a
template-version warning until you re-run the relevant workflow setup
subcommand.

## Checking for drift

`tailor setup check` audits the workflows recorded in
`.github/tailor.lock` against your current config and repository, without
writing anything. It reports when a workflow file is missing or hand-edited, a
newer template is available, `tailor.config.ts` is no longer under the recorded
`--dir`, or the repository default branch no longer matches a branch target's
trigger. It exits non-zero when it finds drift, so you can run it in CI. Each
finding names a stable rule key for future suppression.

Workflows generated by `setup branch`, `setup tag`, `setup preview`, and
`setup coordinate` self-audit: each contains a `tailor-drift-check` step that
runs the check in CI. Preview workflows run it alongside each preview deploy,
so pull requests that deploy no preview (drafts, fork PRs, and unlabeled PRs
in label-triggered mode) skip the check. A single run audits every target
recorded in `.github/tailor.lock`, so per-app composite actions generated by
`setup action` are covered by their coordinator's step and do not carry one of
their own.

Drift findings are advisory by default. Set the repository variable
`TAILOR_PLATFORM_FAIL_ON_DRIFT` to `true` to make unsuppressed findings fail
the job. Execution and configuration errors fail regardless of this variable.

## Updating the generated workflow

When you upgrade the SDK, re-run the relevant workflow setup subcommand with
the same flags to pick up template improvements. If the SDK detects that you
have hand-edited a managed section, it stops and asks you to use `--force` to
overwrite your edits, or to move your customizations into your own steps before
regenerating.

The `.github/tailor.lock` file records the flags used at generation time,
so you can check what arguments were used previously.

---

---
url: https://docs.tailor.tech/sdk/multi-environment.md
---
# Multi-Environment Configuration

A project typically runs in more than one environment — for example, each developer's own workspace, a staging workspace, and a production workspace. The SDK has no separate "environment" concept: an environment is a workspace you deploy to, and all environments share the same `tailor.config.ts`. This guide shows how to switch the deployment target and how to vary configuration values per environment.

The auto-managed `id` in `defineConfig()` identifies the application, not an environment. Keep the same committed `id` when deploying the same config to multiple workspaces; see [Application Settings](configuration.md#application-settings).

## Selecting the target workspace

Deployment commands resolve the target workspace from, in priority order, the `--workspace-id` (`-w`) option, the `TAILOR_PLATFORM_WORKSPACE_ID` environment variable, and the active profile. See [Workspace ID Priority](cli-reference.md#workspace-id-priority).

For one-off commands, pass the workspace explicitly:

```bash
tailor deploy -w <staging-workspace-id>
```

For environments you switch between regularly, create a named profile per environment with the [profile commands](cli/workspace.md#profile-create) and select it with `--profile` (`-p`) or `TAILOR_PLATFORM_PROFILE`:

```bash
tailor profile create staging -u you@example.com -w <staging-workspace-id>
tailor profile create production -u you@example.com -w <production-workspace-id> --permission read

tailor deploy -p staging
```

Profiles are created with `write` permission by default. The production profile above opts into `--permission read`, which blocks write commands such as `deploy` while the profile is active — a guard against deploying to production by accident. To deploy to production deliberately, pass the workspace explicitly with `-w` without selecting the profile — the guard applies only while a profile is selected via `-p` or `TAILOR_PLATFORM_PROFILE` — or use a separate profile created with `write` permission.

If a profile targets a non-default Tailor Platform API, save that connection on the profile as well. User login tokens are stored per Platform URL, so you can log in once for each Platform and then switch with only the profile:

```bash
export TAILOR_PLATFORM_URL=<platform-api-url>
export TAILOR_PLATFORM_OAUTH2_CLIENT_ID=<oauth2-client-id>
export TAILOR_PLATFORM_CONSOLE_URL=<console-url>

tailor login
tailor profile create development \
  -u you@example.com \
  -w <development-workspace-id> \
  --platform-url "$TAILOR_PLATFORM_URL" \
  --oauth2-client-id "$TAILOR_PLATFORM_OAUTH2_CLIENT_ID" \
  --console-url "$TAILOR_PLATFORM_CONSOLE_URL"

unset TAILOR_PLATFORM_URL TAILOR_PLATFORM_OAUTH2_CLIENT_ID TAILOR_PLATFORM_CONSOLE_URL
tailor deploy -p development
tailor open -p development
```

After the profile exists, run `tailor login -p development` to refresh the login for that Platform without re-exporting the connection variables.

## Varying config values per environment

`tailor.config.ts` is a TypeScript module evaluated locally each time an SDK command loads it, so any value can branch on `process.env`. If the config also defines an auth before-login hook, mind the `process.env` caveat in [Environment Variables](configuration.md#environment-variables). Keep one env file per environment and load it with the global [`--env-file`](cli-reference.md#environment-file-loading) option:

```ini
# .env.production
APP_ENV=production
TAILOR_APP_LOG_LEVEL=WARN
```

```bash
tailor deploy -w <production-workspace-id> --env-file .env.production
```

```typescript
export default defineConfig({
  name: "my-app",
  logLevel: process.env.TAILOR_APP_LOG_LEVEL ?? "DEBUG",
});
```

Variables already set in your shell are not overwritten by env files, and later files override earlier ones — see [Environment File Loading](cli-reference.md#environment-file-loading).

## Passing environment values to application code

`process.env` is only available while the config is evaluated locally; deployed resolvers, executors, workflow jobs, auth hooks, and migration scripts cannot read it. To make a value available at runtime, forward it through `env` in `defineConfig()`:

```typescript
export default defineConfig({
  name: "my-app",
  env: {
    appEnv: process.env.APP_ENV ?? "development",
  },
});
```

See [Environment Variables](configuration.md#environment-variables) for how `env` values reach each code location. For sensitive values such as API keys, use [Secret Manager](services/secret) instead and supply the per-environment value via `process.env` the same way.

## Settings that belong to a single environment

Some settings reference resources that can exist in only one environment at a time. The static website [customDomains](services/staticwebsite.md#customdomains) option is an example: a domain is globally unique, so the same `customDomains` value cannot be deployed from two workspaces. Set such values only in the environment that owns the resource:

```typescript
defineStaticWebSite("my-website", {
  customDomains: process.env.APP_ENV === "production" ? ["app.example.com"] : undefined,
});
```

---

---
url: https://docs.tailor.tech/sdk/runtime.md
---
# Runtime API

`@tailor-platform/sdk/runtime` provides typed wrappers for the `tailor.*` and `tailordb.file` APIs that the Tailor Platform Function runtime injects into the global scope at execution time. The wrappers are thin and delegate to the platform-provided globals; they exist so that you can:

* Reach the runtime API without relying on a separate ambient `.d.ts` package
* Get IDE-friendly imports (`iconv.convert`, `idp.Client`, …) instead of unmemorable `tailor.iconv.convert(...)` calls
* Use the same module surface in resolvers, executors, and workflows

The wrappers and their associated types are self-contained — you do not need to activate any ambient globals to use them. If you also want `tailor.iconv.convert(...)` calls to type-check, opt into the globals via the [Activating the global types](#activating-the-global-types) section below.

## Quick Start

```ts
import {
  iconv,
  secretmanager,
  authconnection,
  idp,
  workflow,
  context,
  file,
  aigateway,
  logger,
} from "@tailor-platform/sdk/runtime";

const utf8 = iconv.convert(sjisBuffer, "Shift_JIS", "UTF-8");

const apiKey = await secretmanager.getSecret("my-vault", "API_KEY");

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.startWorkflow("approval", { reportId });

const invoker = context.getInvoker();

const { metadata } = await file.upload("my-namespace", "Document", "attachment", recordId, bytes);

const { url } = await aigateway.get("my-aigateway");

logger.info("order processed", { orderId: "o-1", total: 99.5 });
```

## Subpath imports

Each namespace can also be imported individually so you only pull what you need:

```ts
import { iconv } from "@tailor-platform/sdk/runtime/iconv";
import { idp, type ListUsersResponse, type ClientConfig } from "@tailor-platform/sdk/runtime/idp";
```

`TailorContextAPI` and `TailorWorkflowAPI` describe the imported SDK wrapper objects. When typing direct access to the platform-provided globals or a runtime mock, use `PlatformContextAPI` or `PlatformWorkflowAPI` instead.

## Activating the global types

Most users do not need to touch the globals entry — `@tailor-platform/sdk/runtime` (and its subpath modules) cover the same surface without depending on any ambient declaration.

Importing from `@tailor-platform/sdk` does not activate the ambient `tailor.*` / `tailordb.*` declarations. If you want to opt into the globals, add a single side-effect import anywhere in your project:

```ts
import "@tailor-platform/sdk/runtime/globals";
```

Or register the entry in `tsconfig.json`:

```jsonc
{
  "compilerOptions": {
    "types": ["@tailor-platform/sdk/runtime/globals"],
  },
}
```

The globals entry exposes the lowercase `tailordb.*` namespace only. If your project still references the removed capital-cased `Tailordb.*` namespace from `@tailor-platform/function-types`, migrate before upgrading in two steps: run `pnpm dlx @tailor-platform/sdk-codemod v2/tailordb-namespace` to rewrite `Tailordb.*` references to lowercase `tailordb.*`, then add the `import "@tailor-platform/sdk/runtime/globals"` opt-in above so the rewritten references resolve.

## Namespaces

The runtime entry re-exports the following namespaces. Detailed signatures, parameters, and return types live in the JSDoc next to each export — hover the symbol in your IDE or browse the source.

* `iconv` — character encoding conversion (`convert`, `convertBuffer`, `decode`, `encode`, `encodings`, `Iconv`)
* `secretmanager` — secret-vault access (`getSecret`, `getSecrets`)
* `authconnection` — OAuth-style connection tokens (`getConnectionToken`)
* `idp` — IdP user management (`new Client({ namespace })`)
* `workflow` — workflow & job control (`startWorkflow`, `resumeWorkflowExecution`, `execJobFunction`, `wait`, `resolve`)
* `context` — execution context (`getInvoker`)
* `file` — `tailordb.file` BLOB API (`upload`, `download`, `downloadAsBase64`, `delete`, `getMetadata`, `downloadStream`, `uploadStream`)
* `aigateway` — AI Gateway URL resolution (`get`)
* `logger` — structured logging with severity and attributes; the message is written to standard output, the full entry with its attributes is exported over OpenTelemetry where the attributes are queryable (`debug`, `info`, `warn`, `error`, `setAttributes`)

## 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. 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 { mockIconv, mockSecretmanager } from "@tailor-platform/sdk/vitest";
import { expect, test } from "vitest";

test("encodes via iconv", () => {
  using iconvM = mockIconv();
  iconvM.convert.mockReturnValue(new Uint8Array([0x82, 0xa0]));

  const out = iconv.convert("あ", "UTF-8", "Shift_JIS");

  expect(out).toEqual(new Uint8Array([0x82, 0xa0]));
  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({ secrets: { "my-vault": { API_KEY: "sk-123" } } });

  await expect(secretmanager.getSecret("my-vault", "API_KEY")).resolves.toBe("sk-123");
});
```

See [Testing Guide](testing.md#runtime-environment-emulation-beta) for the full list of mock controllers and the `tailor-runtime` environment setup.

---

---
url: https://docs.tailor.tech/sdk/testing.md
---
# Testing Guide

Tailor Platform SDK applications are tested with [Vitest](https://vitest.dev/) at two layers:

| Layer      | What it exercises                                    | Deployment required |
| ---------- | ---------------------------------------------------- | ------------------- |
| Unit tests | Resolver / workflow job / executor TypeScript source | No                  |
| E2E tests  | Deployed GraphQL API, TailorDB, and workflows        | Yes                 |

Lean on unit tests for the day-to-day feedback loop — they run fast and exercise business logic against real SDK types with no deployment in the loop. Reach for E2E tests to confirm integration against a live platform, where mocked globals can drift from the real GraphQL, TailorDB, and workflow runtime.

Unit-test entrypoints exposed by the SDK:

* `resolver.body({ input, caller, invoker, env })` — invoke a resolver
* `workflowJob.body(input, { env, invoker })` — invoke a workflow job body directly
* `workflowJob.start(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

For anonymous direct calls:

* 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
* `mockTailordbWithPGlite` — TailorDB backed by a real in-memory Postgres (PGlite)
* `mockWorkflow` — `tailor.workflow` job / wait / resolve mocks
* `runWorkflowLocally` — local full-chain workflow runner
* `mockSecretmanager`, `mockAuthconnection`, `mockIdp`, `mockFile`, `mockIconv`, `mockAigateway`, `mockLogger` — 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.

Three starter templates demonstrate the patterns below in a working project:

* `npm create @tailor-platform/sdk -- --template resolver <name>` — resolvers, TailorDB mocking, and DI
* `npm create @tailor-platform/sdk -- --template executor <name>` — executors with extracted DB helpers
* `npm create @tailor-platform/sdk -- --template workflow <name>` — workflow jobs, wait points, and an E2E suite

## Runtime Environment Emulation (Beta)

The Tailor Platform function runtime only provides Web Standard APIs. Node.js built-in modules like `node:crypto` and globals like `Buffer` are not available. The `tailor-runtime` Vitest environment catches these incompatibilities locally before deployment.

### Setup

```typescript
// vitest.config.ts
import { defineConfig } from "vitest/config";
import { tailorRuntime } from "@tailor-platform/sdk/vitest";

export default defineConfig({
  plugins: [tailorRuntime()],
  test: {
    environment: "tailor-runtime",
  },
});
```

`tailorRuntime()` provides:

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** — the platform error classes (`TailorErrors`, `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.

### Acquiring mocks with `using`

Each mock controller (`mockTailordb`, `mockTailordbWithPGlite`, `mockWorkflow`, `mockSecretmanager`, `mockAuthconnection`, `mockIdp`, `mockFile`, `mockIconv`, `mockAigateway`, `mockLogger`) 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 { mockTailordb } from "@tailor-platform/sdk/vitest";

test("...", () => {
  using db = mockTailordb();
  db.onQuery(/SELECT age/).returnsRows([{ age: 30 }]);
  // …
}); // reset automatically here
```

Runtime operations are exposed as typed Vitest mocks wherever the platform API has a stable operation shape. For example, use `file.download.mockResolvedValue(...)`, `iconv.decode.mockReturnValue(...)`, or `wf.job(myJob).mockResolvedValue(...)`, then assert with native Vitest matchers. Service-specific helpers cover stateful fixtures and query matching.

Every controller provides two lifecycle methods when manual reuse is useful:

* `clear()` removes call history but preserves configured behavior.
* `reset()` removes call history and configured behavior, restoring the controller's default behavior.

> **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; per-test fixtures passed to `mockSecretmanager({ secrets: ... })` apply 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();
  // Use an explicit queue when transaction order is part of the test.
  db.enqueueRows(
    [], // BEGIN (empty result)
    [{ age: 30 }], // SELECT (one row)
    [], // COMMIT
  );

  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);
  expect(db.createdClients).toMatchObject([{ namespace: "tailordb" }]);
});
```

Match queries by SQL text, a regular expression, SQL plus parameters, or a predicate. The most recently registered matcher wins:

```typescript
test("content-based mock", async () => {
  using db = mockTailordb();
  db.onQuery({ sql: /FROM users/i, params: ["1"] }).returnsRows([{ id: "1", name: "test" }]);
  db.onQuery(/FROM audit_logs/i)
    .returnsRowsOnce([{ id: "first" }])
    .returnsRows([{ id: "later" }]);

  const result = await resolver.body({
    input: { userId: "1" },
    caller: null,
    invoker: null,
    env: {},
  });

  expect(db.executedQueries[0].query).toContain("SELECT");
});
```

Within one `mockTailordb()` instance, use either `onQuery()` matchers or a direct `queryObject.mockImplementation()` override. A direct override replaces matcher-based behavior, so do not combine the two styles.

`returnsRowsOnce` and `rejectsOnce` configure one-time responses before the persistent `returnsRows` or `rejects` response. `enqueueRows(...rowArrays)` remains available for transaction sequences whose exact call order is under test. The existing `enqueueResult`, `enqueueResults`, and `setQueryResolver` helpers remain supported for compatibility.

Pass `{ onUnhandled: "error" }` to make an unmatched query fail instead of returning an empty result.

#### Real SQL execution with PGlite (`mockTailordbWithPGlite`)

Instead of staging responses, back TailorDB with `@electric-sql/pglite` — an in-memory PostgreSQL (install it as a devDependency) — so the queries a resolver, executor, or workflow job issues through `getDB()` execute against real data. `getDB(namespace)` needs no test-side swap: acquire the mock, and each namespace you list resolves to its PGlite instance.

Create the tables the test touches with `CREATE TABLE` statements matching the generated Kysely types — `text` for string and enum fields, `timestamptz` for date/datetime, `jsonb` for nested objects. The schema only has to match what your code reads and writes, not TailorDB's storage; relations are not enforced.

```typescript
import { PGlite } from "@electric-sql/pglite";
import { mockTailordbWithPGlite } from "@tailor-platform/sdk/vitest";
import { afterAll, beforeAll, expect, test } from "vitest";
import { getDB } from "../generated/db";
import resolver from "./upsertUsers";

const pglite = new PGlite();

beforeAll(async () => {
  await pglite.exec(`
    CREATE TABLE "User" (
      "id" uuid PRIMARY KEY DEFAULT gen_random_uuid(),
      "name" text NOT NULL,
      "email" text NOT NULL,
      "age" integer NOT NULL
    );
  `);
});

afterAll(async () => {
  await pglite.close();
});

test("upserts against real rows", async () => {
  using _db = mockTailordbWithPGlite({ namespaces: { "main-db": pglite } });
  const db = getDB("main-db");
  await db
    .insertInto("User")
    .values({ name: "Existing", email: "exists@example.com", age: 40 })
    .execute();

  const result = await resolver.body({
    input: {
      users: [
        { name: "Newcomer", email: "new@example.com", age: 22 },
        { name: "Existing", email: "exists@example.com", age: 41 },
      ],
    },
    caller: null,
    invoker: null,
    env: { appName: "Resolver Template", version: 1 },
  });

  expect(result).toEqual({ created: 1, updated: 1 });
  const rows = await db.selectFrom("User").selectAll().orderBy("email", "asc").execute();
  expect(rows.map((row) => row.age)).toEqual([41, 22]);
});
```

A `.serial()` field is omitted from generated `getDB()` inserts, so its PGlite column must generate a value. Use an identity for an integer serial. For a formatted string serial, create a sequence and reproduce the format in its `DEFAULT` expression:

```sql
CREATE SEQUENCE "invoiceNumberSequence" START WITH 1000;
CREATE TABLE "Invoice" (
  "sequentialId" integer GENERATED BY DEFAULT AS IDENTITY (START WITH 1),
  "invoiceNumber" text NOT NULL
    DEFAULT ('INV-' || lpad(nextval('"invoiceNumberSequence"')::text, 5, '0'))
);
```

PGlite does not apply the TailorDB `.serial()` configuration itself. Match the `start`, `format`, and any limit that the behavior under test relies on.

* The PGlite instance is yours: the mock never closes it, so close it in `afterAll`. Reuse one instance across a suite — creating one per test is slow.
* Pass the same instance under several namespaces to drive them against one shared database.
* Seed through `getDB` itself. When a column type rejects a value that only the test must stage, use `createKyselyPGlite<Unmigrated<...>>(pglite)` instead — see [Testing Migrations Locally](services/tailordb-migration.md#testing-migrations-locally). This only affects test setup; it cannot supply a `.serial()` value for an insert issued by the code under test.
* Transactions on a shared instance are serialized: while one is open, queries from other `getDB` instances wait. Do not use `test.concurrent` with a shared instance, and do not query the same instance through a second `getDB` from inside a transaction — that waits on itself.
* PGlite runs full PostgreSQL while TailorDB supports a subset of it, and TailorDB hooks, validations, and permissions do not run here — a test passing on PGlite can still behave differently on the platform. Keep [`mockTailordb`](#tailordb-mock) or [`createKyselyMock`](#kysely-layer-mock-createkyselymock) tests for query shape and error paths, and E2E tests for platform behavior.

### Workflow Mock

Workflow job `.start()` calls use the platform workflow runtime. Acquire `mockWorkflow()` when you want to provide start responses with `setJobHandler` / `enqueueResult` or assert on `startedJobs`. If no response is configured, the mock throws so missing job mocks fail loudly. Use `job(definition)` or `workflow(definition)` to get a stable, fully typed Vitest mock for one definition:

```typescript
import { mockWorkflow } from "@tailor-platform/sdk/vitest";
import { processPayment, validateOrder } from "./jobs";

test("workflow starts jobs", async () => {
  using wf = mockWorkflow();
  const validate = wf.job(validateOrder);
  const payment = wf.job(processPayment);
  validate.mockResolvedValue({ valid: true });
  payment.mockResolvedValue({ txnId: "txn-1" });

  const result = await main({ input: { orderId: "o-1" } });

  expect(validate).toHaveBeenCalledWith({ orderId: "o-1" });
  expect(payment).toHaveBeenCalledWith({ orderId: "o-1" });
});
```

Unconfigured definition mocks continue to run their real implementations. The lower-level `execJobFunction`, `startWorkflow`, `resumeWorkflowExecution`, `wait`, and `resolve` mocks and the existing `setJobHandler`, `enqueueResult`, `enqueueResults`, and call-record helpers remain available.

Use `waitPoint(definition)` for typed wait-point control:

```typescript
using wf = mockWorkflow();
const approvalMock = wf.waitPoint(approvalWaitPoint);

approvalMock.wait.mockResolvedValue({ approved: true });
await approvalWaitPoint.wait({ message: "Please approve" });

expect(approvalMock.wait).toHaveBeenCalledWith({ message: "Please approve" });
```

For a wait point whose key contains `$params`, use `waitPointWith(definition, params)` to control one param binding at a time. Calls made with any other binding fall through to the platform mock:

```typescript
using wf = mockWorkflow();
const lineOne = wf.waitPointWith(lineApproval, { lineId: "line-1" });

lineOne.wait.mockResolvedValue({ approved: true });
await lineApproval.with({ lineId: "line-1" }).wait({ message: "Please approve" });

expect(lineOne.wait).toHaveBeenCalledWith({ message: "Please approve" });
```

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
import { mockSecretmanager } from "@tailor-platform/sdk/vitest";

test("reads secrets from vault", async () => {
  using sm = mockSecretmanager({
    secrets: { "my-vault": { API_KEY: "sk-123" } },
  });
  sm.setSecret("my-vault", "API_KEY", "override");
  sm.mergeSecrets("my-vault", { DB_PASS: "secret" });

  const key = await tailor.secretmanager.getSecret("my-vault", "API_KEY");
  expect(key).toBe("override");
  expect(sm.calls).toEqual([{ method: "getSecret", vault: "my-vault", name: "API_KEY" }]);
});
```

### AuthConnection Mock

```typescript
import { mockAuthconnection } from "@tailor-platform/sdk/vitest";

test("returns configured token", async () => {
  using ac = mockAuthconnection({
    tokens: { google: { access_token: "ya29.xxx" } },
    onUnhandled: "error",
  });
  ac.setToken("google", { access_token: "replacement" });

  const token = await tailor.authconnection.getConnectionToken("google");
  expect(token.access_token).toBe("replacement");
});
```

By default, an unconfigured connection returns `{ access_token: "mock-token" }`. Pass `onUnhandled: "error"` to fail instead.

### IDP Mock

```typescript
import { mockIdp } from "@tailor-platform/sdk/vitest";

test("namespace-specific mock", async () => {
  using idp = mockIdp({ onUnhandled: "error" });
  const customerIdp = idp.namespace("my-ns");
  customerIdp.user.mockResolvedValue({
    id: "u-1",
    name: "alice",
    disabled: false,
    mfaEnrolled: false,
    mfaFactorIds: [],
  });

  const client = new tailor.idp.Client({ namespace: "my-ns" });
  const user = await client.user("u-1");
  expect(user.name).toBe("alice");
  expect(customerIdp.user).toHaveBeenCalledWith("u-1");
});
```

Each namespace exposes typed mocks for `users`, `user`, `userByName`, `createUser`, `updateUser`, `deleteUser`, `sendPasswordResetEmail`, and `unenrollMfa`. The existing resolver, queue, and aggregate `calls` APIs remain supported.

### File Mock

```typescript
import { mockFile } from "@tailor-platform/sdk/vitest";

test("mock file download", async () => {
  using file = mockFile({ onUnhandled: "error" });
  file.download.mockResolvedValue({
    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(file.download).toHaveBeenCalledWith("ns", "Doc", "attachment", "r-1");
});
```

All File operations are typed Vitest mocks: `upload`, `download`, `downloadAsBase64`, `delete`, `getMetadata`, `downloadStream`, and `uploadStream`. Use native methods such as `mockResolvedValueOnce` and `mockRejectedValueOnce` to model success and failure. The existing resolver, queue, and aggregate `calls` APIs remain supported.

For `downloadStream`, configure a `FileDownloadStreamResponse` object with a `ReadableStream` body and metadata:

```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();
    },
  });
  file.downloadStream.mockResolvedValue({
    body,
    metadata: { contentType: "image/png", fileSize: 3, sha256sum: "abc", lastUploadedAt: "" },
  });

  const result = await tailordb.file.downloadStream("ns", "Doc", "attachment", "r-1");
  expect(result.metadata.fileSize).toBe(3);
});
```

### Iconv Mock

```typescript
import { mockIconv } from "@tailor-platform/sdk/vitest";

test("mock encoding conversion", () => {
  using iconv = mockIconv();
  iconv.decode.mockReturnValue("decoded-text");

  const result = tailor.iconv.decode(new Uint8Array([0x48, 0x69]), "UTF-8");
  expect(result).toBe("decoded-text");
  expect(iconv.calls).toMatchObject([{ method: "decode" }]);
});
```

`convert`, `convertBuffer`, `decode`, `encode`, and `encodings` are all typed Vitest mocks. Pass `{ onUnhandled: "error" }` to fail calls without a configured implementation. The existing resolver and aggregate `calls` APIs remain supported.

### AI Gateway Mock

```typescript
import { mockAigateway } from "@tailor-platform/sdk/vitest";

test("resolves an AI Gateway URL", async () => {
  using aigateway = mockAigateway({
    urls: { "my-aigateway": "https://my-aigateway.example.com" },
  });
  aigateway.setUrl("my-aigateway", "https://replacement.example.com");

  const { url } = await tailor.aigateway.get("my-aigateway");
  expect(url).toBe("https://replacement.example.com");
  expect(aigateway.calls).toEqual([{ name: "my-aigateway" }]);
});
```

Calling `get` for a name that has not been registered throws. `setUrls` remains available when replacing the complete URL fixture.

### Logger Mock

Each method is a `vi.fn`, so assert on it directly. `calls` returns the emitted `debug`/`info`/`warn`/`error` entries in order.

```typescript
import { mockLogger } from "@tailor-platform/sdk/vitest";

test("logs the processed order", () => {
  using logger = mockLogger();

  tailor.logger.info("order processed", { orderId: "o-1" });

  expect(logger.info).toHaveBeenCalledWith("order processed", { orderId: "o-1" });
  expect(logger.calls).toEqual([
    { severity: "info", message: "order processed", attributes: { orderId: "o-1" } },
  ]);
});
```

Without an explicit `mockLogger()`, `tailor.logger.*` calls are no-ops in the `tailor-runtime` environment (they neither throw nor record).

### Loading Secrets from Config

Pass a config path to load `defineSecretManager()` values into the mock:

```typescript
export default defineConfig({
  plugins: [tailorRuntime({ config: "./tailor.config.ts" })],
  test: { environment: "tailor-runtime" },
});
```

This makes `tailor.secretmanager.getSecret("vault", "key")` return the values defined in your config. You can still override with `mockSecretmanager({ secrets: ... })` in individual tests: a per-test overlay applies only within that test, and the config-loaded secrets remain available to every other test.

### Per-Project Configuration

Apply the runtime environment only to unit tests while keeping other test projects (e.g. e2e) in the default Node.js environment:

```typescript
export default defineConfig({
  plugins: [tailorRuntime()],
  test: {
    projects: [
      // `extends: true` is required so each project inherits the root-level
      // `tailorRuntime()` plugin (transform hook + injected setup file).
      // Without it, only the environment name rewrite applies — node:* import
      // blocking and per-test global cleanup will silently not run.
      {
        extends: true,
        test: {
          name: "unit",
          environment: "tailor-runtime",
          include: ["src/**/*.test.ts"],
        },
      },
      {
        extends: true,
        test: {
          name: "e2e",
          include: ["e2e/**/*.test.ts"],
          globalSetup: "e2e/globalSetup.ts",
        },
      },
    ],
  },
});
```

### Known Limitations

* **`process` and `require`** are not removed or blocked. Vitest's internal runner depends on them extensively. On the real platform runtime, they do not exist.

## Unit Tests

Unit tests call `.body()` (or `.start()`) directly on a resolver, workflow job, or executor and stub any platform-provided globals they touch.

### Testing Resolvers

#### Simple resolver

For pure logic with no external dependencies, invoke `.body()` directly:

```typescript
import { describe, expect, test } from "vitest";
import resolver from "../src/resolver/add";

describe("add resolver", () => {
  test("adds two numbers", async () => {
    const result = await resolver.body({
      input: { left: 1, right: 2 },
      caller: null,
      invoker: null,
      env: {},
    });
    expect(result).toBe(3);
  });
});
```

**Use when:** calculations, data transformations, anything that does not hit the database.

#### Mocking the TailorDB client

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), acquire `using db = mockTailordb()` to install and drive the mock `tailordb.Client` instead of `vi.stubGlobal()`.

> The example below uses `aroundAll` / `aroundEach`, which require Vitest ≥ 4.1.

```typescript
import { aroundAll, aroundEach, describe, expect, test, vi } from "vitest";
import resolver from "../src/resolver/incrementUserAge";

describe("incrementUserAge resolver", () => {
  const mockQueryObject = vi.fn();

  aroundAll(async (runSuite) => {
    vi.stubGlobal("tailordb", {
      Client: vi.fn(
        class {
          connect = vi.fn();
          end = vi.fn();
          queryObject = mockQueryObject;
        },
      ),
    });
    await runSuite();
    vi.unstubAllGlobals();
  });
  aroundEach(async (runTest) => {
    await runTest();
    mockQueryObject.mockReset();
  });

  test("increments age inside a transaction", async () => {
    // BEGIN → SELECT → UPDATE → COMMIT
    mockQueryObject.mockResolvedValueOnce({});
    mockQueryObject.mockResolvedValueOnce({ rows: [{ age: 30 }] });
    mockQueryObject.mockResolvedValueOnce({});
    mockQueryObject.mockResolvedValueOnce({});

    const result = await resolver.body({
      input: { email: "test@example.com" },
      caller: null,
      invoker: null,
      env: {},
    });

    expect(result).toEqual({ oldAge: 30, newAge: 31 });
    expect(mockQueryObject).toHaveBeenCalledTimes(4);
  });
});
```

**Use when:** the business logic runs a few fixed queries and you want to assert the exact call sequence.

#### Extracting DB operations (dependency injection)

Once the logic gets more involved, mocking raw SQL calls becomes brittle. Push database access behind a `DbOperations` interface and test the pure function that uses it:

```typescript
// src/resolver/decrementUserAge.ts
import type { Selectable } from "@tailor-platform/sdk/kysely";
import type { Namespace } from "../generated/db";

export interface DbOperations {
  transaction: <T>(fn: (ops: DbOperations) => Promise<T>) => Promise<T>;
  getUser: (email: string, forUpdate: boolean) => Promise<Selectable<Namespace["main-db"]["User"]>>;
  updateUser: (user: Selectable<Namespace["main-db"]["User"]>) => Promise<void>;
}

export async function decrementUserAge(email: string, db: DbOperations) {
  return await db.transaction(async (ops) => {
    const user = await ops.getUser(email, true);
    const oldAge = user.age;
    const newAge = user.age - 1;
    await ops.updateUser({ ...user, age: newAge });
    return { oldAge, newAge };
  });
}
```

The `resolver` template wires this into `createResolver` by implementing a `createDbOperations` helper (backed by Kysely) and passing it to `decrementUserAge`. See `src/resolver/updateUser.ts` in the template for the full file.

```typescript
// src/resolver/decrementUserAge.test.ts
import { describe, expect, test, vi } from "vitest";
import { type DbOperations, decrementUserAge } from "./decrementUserAge";

describe("decrementUserAge", () => {
  test("decrements age", async () => {
    const db = {
      transaction: vi.fn(async (fn: (ops: DbOperations) => Promise<unknown>) => await fn(db)),
      getUser: vi.fn().mockResolvedValue({ email: "test@example.com", age: 30 }),
      updateUser: vi.fn(),
    } as DbOperations;

    const result = await decrementUserAge("test@example.com", db);

    expect(result).toEqual({ oldAge: 30, newAge: 29 });
    expect(db.getUser).toHaveBeenCalledExactlyOnceWith("test@example.com", true);
    expect(db.updateUser).toHaveBeenCalledExactlyOnceWith(expect.objectContaining({ age: 29 }));
  });
});
```

**Use when:** multi-step business logic. The tests survive query rewrites because they assert high-level intent, not SQL shape.

#### Kysely-layer mock (`createKyselyMock`)

`createKyselyMock` returns a real Kysely instance whose execution is mocked. Stage the rows each query returns, run your code, then assert what it did — each query's SQL and parameters, how many `selects`/`inserts`/`updates`/`deletes` ran, and the value your code returned. Queries stay fully typed and compile to the same SQL as production.

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 { createKyselyMock } from "@tailor-platform/sdk/vitest";
import { describe, expect, test, vi } from "vitest";
import { getDB, type Namespace } from "../generated/db";
import resolver from "./upsertUsers";

vi.mock("../generated/db", { spy: true });

describe("upsertUsers resolver", () => {
  test("inserts new users and updates existing ones", async () => {
    const mock = createKyselyMock<Namespace["main-db"]>();
    vi.mocked(getDB).mockReturnValue(mock.db);

    mock.setQueryResolver((query) => {
      switch (query.kind) {
        case "SelectQueryNode":
          return query.parameters.includes("exists@example.com") ? [{ id: "user-1" }] : [];
        case "InsertQueryNode":
        case "UpdateQueryNode":
          return { numAffectedRows: 1 };
        default:
          return [];
      }
    });

    const result = await resolver.body({
      input: {
        users: [
          { name: "Newcomer", email: "new@example.com", age: 22 },
          { name: "Existing", email: "exists@example.com", age: 41 },
        ],
      },
      caller: null,
      invoker: null,
      env: { appName: "Resolver Template", version: 1 },
    });

    expect(result).toEqual({ created: 1, updated: 1 });
    expect(mock.selects).toHaveLength(2);
    expect(mock.inserts).toHaveLength(1);
    expect(mock.updates).toHaveLength(1);
  });
});
```

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, or [`mockTailordbWithPGlite`](#real-sql-execution-with-pglite-mocktailordbwithpglite) to execute the queries against a real in-memory Postgres.

TailorDB migration scripts (`migrate.ts`) are unit-tested the same way: the generated `db.ts` exports the `Database` interface to type the mock, and `tailor tailordb migration script <N> --with-test` scaffolds a ready-to-fill test. To execute a migration script against real rows in an in-memory Postgres, use `createKyselyPGlite` with `@electric-sql/pglite`. See [Testing Migrations Locally](services/tailordb-migration.md#testing-migrations-locally).

#### Resolvers that resume a workflow

Resolvers that call `waitPoint.resolve(...)` delegate to `tailor.workflow.resolve` at runtime. With the `tailor-runtime` environment active, use `mockWorkflow().waitPoint(definition)` to invoke the callback with the payload that originally suspended the job:

```typescript
import { mockWorkflow } from "@tailor-platform/sdk/vitest";
import { describe, expect, test } from "vitest";
import { approval } from "../workflow/approval";
import resolver from "./resolveApproval";

describe("resolveApproval resolver", () => {
  test("resolves approval with approved=true", async () => {
    using wf = mockWorkflow();
    const approvalMock = wf.waitPoint(approval);
    approvalMock.setResolvePayload({
      message: "Please approve order order-1",
      orderId: "order-1",
    });

    const result = await resolver.body({
      input: { executionId: "exec-1", approved: true },
      caller: null,
      invoker: null,
      env: {},
    });

    expect(result).toEqual({ resolved: true });
    expect(approvalMock.resolve).toHaveBeenCalledWith("exec-1", expect.any(Function));
  });
});
```

`setResolvePayload` is typed from the wait-point definition. The lower-level `setResolveHandler` and `resolveCalls` APIs remain available when a test must control several wait points together.

#### Resolvers that resume failed workflows

Resolvers or executors that call `workflow.resumeWorkflowExecution(executionId)` delegate to `tailor.workflow.resumeWorkflowExecution` at runtime. With the `tailor-runtime` environment active, use `mockWorkflow().setResumeHandler` to control the returned execution ID and inspect `resumeWorkflowExecution.mock.calls`:

```typescript
import { unauthenticatedTailorUser } from "@tailor-platform/sdk/test";
import { mockWorkflow } from "@tailor-platform/sdk/vitest";
import { describe, expect, test } from "vitest";
import resolver from "./retryFailedWorkflow";

describe("retryFailedWorkflow resolver", () => {
  test("resumes a failed workflow execution", async () => {
    using wf = mockWorkflow();
    wf.setResumeHandler("exec-resumed-123");

    const result = await resolver.body({
      input: { executionId: "exec-failed-456" },
      user: unauthenticatedTailorUser,
      env: {},
    });

    expect(result).toEqual({ resumedExecutionId: "exec-resumed-123" });
    expect(wf.resumeWorkflowExecution.mock.calls).toEqual([["exec-failed-456"]]);
  });
});
```

`setResumeHandler` accepts a static string (same execution ID for every call) or a function `(executionId) => string` that computes one per call. By default the mock echoes the input `executionId`.

### 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 table'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:

```typescript
import { describe, expect, test, vi } from "vitest";
import onUserCreated from "./onUserCreated";
import * as shared from "./shared";

describe("onUserCreated executor", () => {
  test("creates an audit log with the new user's name and email", async () => {
    using createAuditLog = vi.spyOn(shared, "createAuditLog").mockResolvedValue(undefined);

    if (onUserCreated.operation.kind !== "function") {
      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",
        email: "alice@example.com",
        role: "ADMIN",
        createdAt: "2025-01-01T00:00:00Z",
        updatedAt: "2025-01-01T00:00:00Z",
      },
    });

    expect(createAuditLog).toHaveBeenCalledExactlyOnceWith({
      action: "USER_CREATED",
      entityType: "User",
      entityId: "user-1",
      message: "Admin user created: Alice (alice@example.com)",
    });
  });
});
```

To exercise the full chain (executor → helper → TailorDB), drop the spy and stub the global `tailordb.Client` instead, exactly as shown for resolvers.

### Testing Workflow Jobs

Workflow jobs expose the same `.body()` entrypoint as resolvers, plus `.start()` for calling them from another job or a test.

#### Simple job

Call `.body()` with the input and a stub `{ env: {}, invoker: null }`:

```typescript
import { describe, expect, test } from "vitest";
import { validateOrder } from "./order-fulfillment";

describe("validateOrder", () => {
  test("accepts a valid order", () => {
    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: {}, invoker: null }),
    ).toThrow("Order amount must be positive");
  });
});
```

#### Jobs that start other jobs

Use `mockWorkflow().job(definition)` to replace dependent jobs with deterministic results:

```typescript
import { mockWorkflow } from "@tailor-platform/sdk/vitest";
import { describe, expect, test } from "vitest";
import { fulfillOrder, processPayment, sendConfirmation, validateOrder } from "./order-fulfillment";

describe("fulfillOrder", () => {
  test("chains validate → pay → confirm", async () => {
    using wf = mockWorkflow();
    const validate = wf.job(validateOrder).mockResolvedValue({
      valid: true,
      orderId: "order-1",
    });
    wf.job(processPayment).mockResolvedValue({
      transactionId: "txn-order-1",
      amount: 100,
      status: "completed",
    });
    wf.job(sendConfirmation).mockResolvedValue({
      orderId: "order-1",
      transactionId: "txn-order-1",
      confirmed: true,
    });

    const result = await fulfillOrder.body(
      { orderId: "order-1", amount: 100 },
      { env: {}, invoker: null },
    );

    expect(validate).toHaveBeenCalledWith({ orderId: "order-1", amount: 100 });
    expect(result).toMatchObject({ confirmed: true, paymentStatus: "completed" });
  });
});
```

**Use when:** you want to isolate the orchestrating job from its dependencies.

#### Jobs that wait on approval

`.wait()` calls delegate to `tailor.workflow.wait`. With the `tailor-runtime` environment active, use `mockWorkflow().waitPoint(definition)` to drive each branch with a typed mock:

```typescript
import { mockWorkflow } from "@tailor-platform/sdk/vitest";
import { describe, expect, test } from "vitest";
import { approval, processWithApproval } from "./approval";

describe("processWithApproval", () => {
  test("returns approved status when .wait() resolves positively", async () => {
    using wf = mockWorkflow();
    const approvalMock = wf.waitPoint(approval);
    approvalMock.wait.mockResolvedValue({ approved: true });

    const result = await processWithApproval.body(
      { orderId: "order-1" },
      { env: {}, invoker: null },
    );

    expect(result).toEqual({ orderId: "order-1", status: "approved" });
    expect(approvalMock.wait).toHaveBeenCalledWith({
      message: "Please approve order order-1",
      orderId: "order-1",
    });
  });

  test("returns rejected status when .wait() resolves negatively", async () => {
    using wf = mockWorkflow();
    wf.waitPoint(approval).wait.mockResolvedValue({ approved: false });

    const result = await processWithApproval.body(
      { orderId: "order-2" },
      { env: {}, invoker: null },
    );

    expect(result.status).toBe("rejected");
  });
});
```

The lower-level `setWaitHandler` and `waitCalls` APIs remain available when one handler must cover several wait points.

#### Running a full workflow locally

To exercise the full chain with real job bodies, call `runWorkflowLocally(workflow, args)`. Dependent jobs run their real `.body()` functions, and start 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("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 definition with `wf.job(...)` / `wf.workflow(...)` (the rest still run their real bodies), control the env via `wf.setEnv(...)`, or assert on calls.

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 `.start()` call (N starts means N+1 passes), so any side effects outside the start results fire on every pass. Keep the body deterministic and move repeatable side effects into the started 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.

## End-to-End (E2E) Tests

E2E tests run against a deployed Tailor Platform application. They exercise the full stack — GraphQL, TailorDB, auth, workflows — end to end.

The `workflow` template ships a complete `e2e/` directory (`globalSetup.ts`, `workflow.test.ts`, `resolver.test.ts`) that you can copy.

### Install a GraphQL client

```bash
pnpm add -D graphql-request
```

### Global setup

Resolve the deployed URL and a machine-user token, and expose them to tests via `inject`:

```typescript
// e2e/globalSetup.ts
import { getMachineUserToken, show } from "@tailor-platform/sdk/cli";
import type { TestProject } from "vitest/node";

declare module "vitest" {
  export interface ProvidedContext {
    url: string;
    token: string;
  }
}

export async function setup(project: TestProject) {
  const app = await show();
  const tokens = await getMachineUserToken({ name: "admin" });
  project.provide("url", app.url);
  project.provide("token", tokens.accessToken);
}
```

### Resolver E2E test

```typescript
// e2e/resolver.test.ts
import { randomUUID } from "node:crypto";
import { gql, GraphQLClient } from "graphql-request";
import { describe, expect, inject, test } from "vitest";

function createGraphQLClient() {
  return new GraphQLClient(new URL("/query", inject("url")).href, {
    headers: { Authorization: `Bearer ${inject("token")}` },
    errorPolicy: "all",
  });
}

describe("incrementUserAge", () => {
  const client = createGraphQLClient();
  const email = `alice-${randomUUID()}@example.com`;

  test("prepares the user", async () => {
    const res = await client.rawRequest(
      gql`
        mutation ($input: UserCreateInput!) {
          createUser(input: $input) {
            id
          }
        }
      `,
      { input: { name: "alice", email, age: 30 } },
    );
    expect(res.errors).toBeUndefined();
  });

  test("increments the user's age", async () => {
    const res = await client.rawRequest(
      gql`
        mutation ($email: String!) {
          incrementUserAge(email: $email) {
            oldAge
            newAge
          }
        }
      `,
      { email },
    );
    expect(res.errors).toBeUndefined();
    expect(res.data).toEqual({ incrementUserAge: { oldAge: 30, newAge: 31 } });
  });
});
```

### Workflow E2E test

Use `startWorkflow` from the CLI helpers. It starts the workflow on the deployed platform and returns an `executionId` plus a `wait()` that blocks until the run completes:

```typescript
// e2e/workflow.test.ts
import { randomUUID } from "node:crypto";
import { startWorkflow } from "@tailor-platform/sdk/cli";
import { describe, expect, test } from "vitest";
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,
      invoker: "admin",
      arg: {
        name: "workflow-test",
        email: `wf-${randomUUID()}@example.com`,
        age: 25,
      },
    });
    console.log(`execution id: ${executionId}`);

    const result = await wait();
    expect(result).toMatchObject({
      workflowName: "user-profile-sync",
      status: "SUCCESS",
    });
  });
});
```

**Use when:** verifying actual deployments, auth flows, schema migrations, and anything that depends on runtime platform behavior you cannot mock.

---

---
url: https://docs.tailor.tech/sdk/cli/application.md
---
# Application Commands

Commands for managing Tailor Platform applications. These commands work with `tailor.config.ts`.

## init

Initialize a new project using create-sdk.

**Usage**

```
tailor init [options] [name]
```

**Arguments**

| Argument | Description  | Required |
| -------- | ------------ | -------- |
| `name`   | Project name | No       |

**Options**

| Option                  | Alias | Description   | Required | Default |
| ----------------------- | ----- | ------------- | -------- | ------- |
| `--template <TEMPLATE>` | `-t`  | Template name | No       | -       |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

## generate

Generate files using Tailor configuration.

**Usage**

```
tailor generate [options]
```

**Options**

| Option              | Alias | Description             | Required | Default              |
| ------------------- | ----- | ----------------------- | -------- | -------------------- |
| `--config <CONFIG>` | `-c`  | Path to SDK config file | No       | `"tailor.config.ts"` |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

## deploy

Deploy your application by applying the Tailor configuration.

**Usage**

```
tailor deploy [options]
```

**Options**

| Option                                  | Alias | Description                                                                          | Required | Default              | Env                               |
| --------------------------------------- | ----- | ------------------------------------------------------------------------------------ | -------- | -------------------- | --------------------------------- |
| `--workspace-id <WORKSPACE_ID>`         | `-w`  | Workspace ID                                                                         | No       | -                    | `TAILOR_PLATFORM_WORKSPACE_ID`    |
| `--profile <PROFILE>`                   | `-p`  | Workspace profile                                                                    | No       | -                    | `TAILOR_PLATFORM_PROFILE`         |
| `--config <CONFIG>`                     | `-c`  | Path to SDK config file. Use comma-separated paths to deploy multiple apps together. | No       | `"tailor.config.ts"` | `TAILOR_PLATFORM_SDK_CONFIG_PATH` |
| `--yes`                                 | `-y`  | Skip confirmation prompts                                                            | No       | `false`              | -                                 |
| `--create-workspace`                    | -     | Create a workspace when the account has none                                         | No       | -                    | -                                 |
| `--workspace-name <WORKSPACE_NAME>`     | -     | Name for a workspace created during deploy                                           | No       | -                    | -                                 |
| `--workspace-region <WORKSPACE_REGION>` | -     | Region for a workspace created during deploy                                         | No       | -                    | -                                 |
| `--organization-id <ORGANIZATION_ID>`   | -     | Organization ID for a workspace created during deploy                                | No       | -                    | `TAILOR_PLATFORM_ORGANIZATION_ID` |
| `--folder-id <FOLDER_ID>`               | -     | Folder ID for a workspace created during deploy                                      | No       | -                    | `TAILOR_PLATFORM_FOLDER_ID`       |
| `--dry-run`                             | `-d`  | Run the command without making any changes                                           | No       | -                    | -                                 |
| `--no-schema-check`                     | -     | Skip schema diff check against migration snapshots                                   | No       | -                    | -                                 |
| `--no-validate`                         | -     | Skip client-side validation against platform resource constraints                    | No       | -                    | -                                 |
| `--no-cache`                            | -     | Disable bundle caching for this run                                                  | No       | -                    | -                                 |
| `--clean-cache`                         | -     | Clean the bundle cache before building                                               | No       | -                    | -                                 |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.
**Workspace Selection:**

After validating the configuration file, `deploy` resolves a workspace before bundling the
application. Explicit configuration takes precedence in this order: `--workspace-id`,
`TAILOR_PLATFORM_WORKSPACE_ID`, and the selected profile. Otherwise, `deploy` reuses the workspace
previously selected for that configuration from project-local state. Each config file keeps an
independent selection, including when multiple configs share a directory. An explicit workspace also
updates this selection. Saved selections are verified against the workspaces currently visible to
the authenticated user before reuse, and `deploy` warns when it uses one.

When the project has no saved selection, `deploy` discovers the account's workspaces:

* One or more workspaces open a selection prompt in an interactive terminal, with an option to
  create a new workspace. With one workspace in non-interactive or JSON mode, it is selected
  automatically. With multiple workspaces, pass `--workspace-id` instead.
* No workspaces open a guided creation flow in an interactive terminal. The flow asks for a name,
  fetches the available regions from the Platform, and confirms before creating anything. After
  creation, the output shows how to reuse the workspace with `--workspace-id` or
  `TAILOR_PLATFORM_WORKSPACE_ID` from CI or another machine.

In CI and other non-interactive environments, workspace creation must be explicit:

```bash
tailor deploy \
  --create-workspace \
  --workspace-name example-workspace \
  --workspace-region us-west
```

`--create-workspace` only creates when the account has no workspace. If the existing workspace
matches the requested name, region, organization, and folder, `deploy` reuses it so the same command
is safe to rerun. If multiple workspaces exist, the flag never creates another one or guesses which
workspace to use. `--yes` skips deployment confirmation but does not authorize workspace creation.

If a saved workspace has been deleted or is no longer accessible, interactive terminals return to
workspace selection. Non-interactive environments stop with `WORKSPACE_CONTEXT_STALE` instead of
silently switching to another workspace. Automatically selected targets are printed with their
region, organization, and workspace ID.

`--dry-run` never creates a workspace or writes project context. When an account has no workspace,
create one explicitly before requesting a deployment plan.

**Config File Modification:**

On first run, `deploy` automatically injects a stable `id: "<uuid>"` field into your `defineConfig({...})` call in `tailor.config.ts`. This UUID is used to track your application across renames so the SDK can recognize ownership across renames. Commit the generated id to version control. See [Configuration](../configuration.md#application-settings) for details.

**Multiple Config Deploys:**

To deploy interdependent applications to the same workspace in one run, pass comma-separated config paths:

```bash
tailor deploy --config apps/buyer/tailor.config.ts,apps/supplier/tailor.config.ts
```

When multiple configs are provided, `deploy` creates or updates all configured services first, then updates the applications. This lets one application reference resources owned by another config with `external: true` during the same deploy.

Each config's `files` and `ignores` patterns (see [Service Configuration](../configuration.md#service-configuration)) resolve relative to that config's own directory, not the directory you ran `deploy` from. For example, `apps/buyer/tailor.config.ts` declaring `files: ["db/**/*.ts"]` loads files from `apps/buyer/db/`, independent of where `apps/supplier/tailor.config.ts`'s patterns resolve. If a config's relative patterns match nothing under its own directory, the SDK falls back to the invocation directory and logs a warning (see [Service Configuration](../configuration.md#service-configuration) for details).

**Migration Handling:**

When migrations are configured (`db.tailordb.migration` in config), the `deploy` command automatically:

1. Detects pending migration scripts that haven't been executed
2. Applies schema changes in a safe order (pre-migration → script execution → post-migration)
3. Runs the pending migration scripts
4. Updates the migration checkpoint so the same migrations are not re-run

See [Automatic Migration Execution](../services/tailordb-migration.md#automatic-migration-execution) for details on automatic migration execution.

**Concurrent Deploys:**

Deploys that target the same workspace and application from the same project directory are serialized while secrets and auth connections are updated: one deploy proceeds and the other waits for it to finish. A deploy that cannot proceed within 5 minutes fails with an error, which normally means another deploy is still running. If a previous deploy was interrupted, the next deploy recovers automatically within about a minute. Deploys to different workspaces or applications are not affected.

**Schema Check:**

By default, `deploy` performs two verification steps:

1. **Local schema check**: Verifies that local schema changes match the migration files. This ensures migrations are properly generated before deployment.
2. **Remote schema check**: Verifies that the remote schema matches the expected state based on migration history. This detects schema drift caused by manual changes or other developers.

If remote schema drift is detected, the deploy will fail with an error showing the differences. This helps prevent applying migrations to an inconsistent state.

Use `--no-schema-check` to skip both verifications (not recommended for production).

**Plan Output:**

Before applying changes, `deploy` shows a preview of the planned resource changes.

* `+` means the resource will be created
* `~` means the resource will be updated
* `-` means the resource will be deleted
* `±` means the resource will be replaced

After the detailed list, a summary line is printed:

```text
Plan: 5 to create, 3 to update, 1 to delete
```

Use `--dry-run` to preview the plan without applying anything. In dry-run mode the plan is written to **stdout**, so it can be captured in CI without `2>&1`:

```bash
tailor deploy --dry-run > plan.txt
```

In apply mode, the plan is printed to stderr so it does not interfere with piped output.

**JSON Output:**

Pass the global `--json` / `-j` flag to get machine-readable output.

**Dry-run** (`--dry-run --json`): writes a JSON object to stdout:

```json
{
  "summary": { "create": 2, "update": 1, "delete": 0, "replace": 0 },
  "changes": [
    { "action": "create", "name": "Order", "labels": ["table"], "namespace": "tailordb" }
  ],
  "warnings": [
    { "type": "unmanaged", "resourceType": "tailorDB", "name": "LegacyType" },
    { "type": "skippedSecret", "resourceType": "secret", "name": "DB_PASSWORD" }
  ],
  "conflicts": [{ "resourceType": "tailorDB", "name": "User", "currentOwner": "other-app" }]
}
```

* `summary` — counts of each change type.
* `changes` — planned resource changes, each with `action`, `name`, and optional `labels` / `namespace`.
* `warnings` — resources not in config (`type: "unmanaged"`) or secrets with missing values (`type: "skippedSecret"`). Unmanaged resources require confirmation in apply mode (apply is cancelled if declined); skipped secrets are non-blocking.
* `conflicts` — resources owned by another application that conflict with the current config. Require confirmation in apply mode; apply is cancelled if declined.

**Apply** (`--json`): writes a JSON object to stdout:

```json
{ "summary": { "create": 1, "update": 2, "delete": 0, "replace": 0 }, "status": "applied" }
```

## remove

Remove all resources managed by the application from the workspace.

**Usage**

```
tailor remove [options]
```

**Options**

| Option                          | Alias | Description                | Required | Default              | Env                            |
| ------------------------------- | ----- | -------------------------- | -------- | -------------------- | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID               | No       | -                    | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>`           | `-p`  | Workspace profile          | No       | -                    | `TAILOR_PLATFORM_PROFILE`      |
| `--config <CONFIG>`             | `-c`  | Path to Tailor config file | No       | `"tailor.config.ts"` | `TAILOR_CONFIG_PATH`           |
| `--yes`                         | `-y`  | Skip confirmation prompts  | No       | `false`              | -                              |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

## show

Show information about the deployed application.

**Usage**

```
tailor show [options]
```

**Options**

| Option                          | Alias | Description                | Required | Default              | Env                            |
| ------------------------------- | ----- | -------------------------- | -------- | -------------------- | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID               | No       | -                    | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>`           | `-p`  | Workspace profile          | No       | -                    | `TAILOR_PLATFORM_PROFILE`      |
| `--config <CONFIG>`             | `-c`  | Path to Tailor config file | No       | `"tailor.config.ts"` | `TAILOR_CONFIG_PATH`           |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

## open

Open Tailor Platform Console.

**Usage**

```
tailor open [options]
```

**Options**

| Option                          | Alias | Description                | Required | Default              | Env                            |
| ------------------------------- | ----- | -------------------------- | -------- | -------------------- | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID               | No       | -                    | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>`           | `-p`  | Workspace profile          | No       | -                    | `TAILOR_PLATFORM_PROFILE`      |
| `--config <CONFIG>`             | `-c`  | Path to Tailor config file | No       | `"tailor.config.ts"` | `TAILOR_CONFIG_PATH`           |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

## api

Call Tailor Platform API endpoints directly.

**Usage**

```
tailor api [options] [command] <endpoint>
```

**Arguments**

| Argument   | Description                                                                                  | Required |
| ---------- | -------------------------------------------------------------------------------------------- | -------- |
| `endpoint` | API endpoint to call (e.g., 'GetApplication' or 'tailor.v1.OperatorService/GetApplication'). | Yes      |

**Options**

| Option                          | Alias | Description                                                                       | Required | Default              | Env                            |
| ------------------------------- | ----- | --------------------------------------------------------------------------------- | -------- | -------------------- | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID                                                                      | No       | -                    | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>`           | `-p`  | Workspace profile                                                                 | No       | -                    | `TAILOR_PLATFORM_PROFILE`      |
| `--config <CONFIG>`             | `-c`  | Path to Tailor config file                                                        | No       | `"tailor.config.ts"` | `TAILOR_CONFIG_PATH`           |
| `--body <BODY>`                 | `-b`  | Request body as JSON.                                                             | No       | `"{}"`               | -                              |
| `--field <FIELD>`               | `-f`  | Set a body field as `key=value` (repeatable; dotted keys nest). Overrides --body. | No       | -                    | -                              |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

**Commands**

| Command                       | Description                                                  |
| ----------------------------- | ------------------------------------------------------------ |
| [`api list`](#api-list)       | List all invocable OperatorService methods.                  |
| [`api inspect`](#api-inspect) | Print the input message tree of an OperatorService endpoint. |

**Examples**

**Call an endpoint; workspaceId is auto-injected.**

```bash
$ tailor api GetApplication -b '{"applicationName":"app-1"}'
```

**Same as above, using --field instead of --body.**

```bash
$ tailor api GetApplication -f applicationName=app-1
```

**List all invocable OperatorService methods.**

```bash
$ tailor api list
```

**Show the input message tree for an endpoint.**

```bash
$ tailor api inspect GetApplication
```

**Notes**

Use `tailor api list` to enumerate invocable methods and `tailor api inspect <endpoint>` to print an endpoint's input message tree (combine with `--json` for machine-readable output).

The request body is inferred from the target endpoint's request schema, and commonly required fields are auto-injected so they can be omitted from `--body`:

* `workspaceId` — resolved from `-w` / `TAILOR_PLATFORM_WORKSPACE_ID` / the selected profile.
* `namespaceName` — resolved from `tailor.config.ts` based on the endpoint's service:
  * Auth / Tenant / UserProfile endpoints use `auth.name`.
  * IdP / TailorDB / Pipeline endpoints use the sole configured namespace when exactly one is defined.

Values already present in `--body` are never overridden. If a value cannot be resolved (e.g. no config found), injection is silently skipped and the server-side validation error takes precedence.

Use `--field key=value` (repeatable) to set request body fields without writing JSON. Dotted keys (e.g. `application.name=foo`) build nested objects. `--field` overrides matching fields in `--body` and tab-completes from the endpoint's request schema.

### api inspect

Print the input message tree of an OperatorService endpoint.

**Usage**

```
tailor api inspect <endpoint>
```

**Arguments**

| Argument   | Description                                                                                     | Required |
| ---------- | ----------------------------------------------------------------------------------------------- | -------- |
| `endpoint` | API endpoint to inspect (e.g., 'GetApplication' or 'tailor.v1.OperatorService/GetApplication'). | Yes      |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

**Examples**

**Show fields of GetApplicationRequest.**

```bash
$ tailor api inspect GetApplication
```

**Inspect a deeply nested input with `(oneof config)` annotations.**

```bash
$ tailor api inspect CreateExecutorExecutor
```

**Notes**

Combine with the global `--json` flag for a machine-readable descriptor. Recursive type references and `oneof` membership are annotated. Use `tailor api list` to discover endpoint names.

### api list

List all invocable OperatorService methods.

**Usage**

```
tailor api list
```

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

**Notes**

Only single-request (non-streaming) methods are listed, because the CLI issues a single JSON request and reads one JSON response.

---

---
url: https://docs.tailor.tech/sdk/cli/auth.md
---
# Auth Resource Commands

Commands for managing Auth service resources (auth connections, machine users, and OAuth2 clients).

## authconnection

Manage auth connections.

**Usage**

```
tailor authconnection [command]
```

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

**Commands**

| Command                                                 | Description                                                                           |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| [`authconnection authorize`](#authconnection-authorize) | Authorize an auth connection via OAuth2 flow.                                         |
| [`authconnection list`](#authconnection-list)           | List all auth connections.                                                            |
| [`authconnection open`](#authconnection-open)           | Open the auth connections page in the Tailor Platform Console.                        |
| [`authconnection revoke`](#authconnection-revoke)       | Revoke an auth connection's tokens (keeps the connection; use 'delete' to remove it). |
| [`authconnection delete`](#authconnection-delete)       | Delete an auth connection entirely.                                                   |

### authconnection authorize

Authorize an auth connection via OAuth2 flow.

**Usage**

```
tailor authconnection authorize [options]
```

**Options**

| Option                          | Alias | Description                                | Required | Default                  | Env                            |
| ------------------------------- | ----- | ------------------------------------------ | -------- | ------------------------ | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID                               | No       | -                        | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>`           | `-p`  | Workspace profile                          | No       | -                        | `TAILOR_PLATFORM_PROFILE`      |
| `--name <NAME>`                 | `-n`  | Auth connection name                       | Yes      | -                        | -                              |
| `--scopes <SCOPES>`             | -     | OAuth2 scopes to request (comma-separated) | No       | `"openid,profile,email"` | -                              |
| `--port <PORT>`                 | -     | Local callback server port                 | No       | `8080`                   | -                              |
| `--no-browser`                  | -     | Don't open browser automatically           | No       | `false`                  | -                              |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

### authconnection delete

Delete an auth connection entirely.

**Usage**

```
tailor authconnection delete [options]
```

**Options**

| Option                          | Alias | Description               | Required | Default | Env                            |
| ------------------------------- | ----- | ------------------------- | -------- | ------- | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID              | No       | -       | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>`           | `-p`  | Workspace profile         | No       | -       | `TAILOR_PLATFORM_PROFILE`      |
| `--name <NAME>`                 | `-n`  | Auth connection name      | Yes      | -       | -                              |
| `--yes`                         | `-y`  | Skip confirmation prompts | No       | `false` | -                              |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

### authconnection list

List all auth connections.

**Usage**

```
tailor authconnection list [options]
```

**Options**

| Option                          | Alias | Description                                              | Required | Default  | Env                            |
| ------------------------------- | ----- | -------------------------------------------------------- | -------- | -------- | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID                                             | No       | -        | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>`           | `-p`  | Workspace profile                                        | No       | -        | `TAILOR_PLATFORM_PROFILE`      |
| `--order <ORDER>`               | -     | Sort order (asc or desc)                                 | No       | `"desc"` | -                              |
| `--limit <LIMIT>`               | `-l`  | Maximum number of items to return (0 or omit: unlimited) | No       | -        | -                              |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

### authconnection open

Open the auth connections page in the Tailor Platform Console.

**Usage**

```
tailor authconnection open [options]
```

**Options**

| Option                          | Alias | Description       | Required | Default | Env                            |
| ------------------------------- | ----- | ----------------- | -------- | ------- | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID      | No       | -       | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>`           | `-p`  | Workspace profile | No       | -       | `TAILOR_PLATFORM_PROFILE`      |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

### authconnection revoke

Revoke an auth connection's tokens (keeps the connection; use 'delete' to remove it).

**Usage**

```
tailor authconnection revoke [options]
```

**Options**

| Option                          | Alias | Description               | Required | Default | Env                            |
| ------------------------------- | ----- | ------------------------- | -------- | ------- | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID              | No       | -       | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>`           | `-p`  | Workspace profile         | No       | -       | `TAILOR_PLATFORM_PROFILE`      |
| `--name <NAME>`                 | `-n`  | Auth connection name      | Yes      | -       | -                              |
| `--yes`                         | `-y`  | Skip confirmation prompts | No       | `false` | -                              |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

**Notes**

Revoke invalidates the connection's active session and tokens but keeps the connection and its stored credentials, so it can be re-authorized later. Use `delete` to remove the connection entirely.

## machineuser

Manage machine users in your Tailor Platform application.

**Usage**

```
tailor machineuser [command]
```

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

**Commands**

| Command                                   | Description                                |
| ----------------------------------------- | ------------------------------------------ |
| [`machineuser list`](#machineuser-list)   | List all machine users in the application. |
| [`machineuser token`](#machineuser-token) | Get an access token for a machine user.    |

### machineuser list

List all machine users in the application.

**Usage**

```
tailor machineuser list [options]
```

**Options**

| Option                          | Alias | Description                                              | Required | Default              | Env                            |
| ------------------------------- | ----- | -------------------------------------------------------- | -------- | -------------------- | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID                                             | No       | -                    | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>`           | `-p`  | Workspace profile                                        | No       | -                    | `TAILOR_PLATFORM_PROFILE`      |
| `--config <CONFIG>`             | `-c`  | Path to Tailor config file                               | No       | `"tailor.config.ts"` | `TAILOR_CONFIG_PATH`           |
| `--order <ORDER>`               | -     | Sort order (asc or desc)                                 | No       | `"desc"`             | -                              |
| `--limit <LIMIT>`               | `-l`  | Maximum number of items to return (0 or omit: unlimited) | No       | -                    | -                              |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

### machineuser token

Get an access token for a machine user.

**Usage**

```
tailor machineuser token [options] [name]
```

**Arguments**

| Argument | Description                                                                                                         | Required |
| -------- | ------------------------------------------------------------------------------------------------------------------- | -------- |
| `name`   | Machine user name. Falls back to TAILOR\_PLATFORM\_MACHINE\_USER\_NAME, then the active profile's default machine user. | No       |

**Options**

| Option                          | Alias | Description                | Required | Default              | Env                            |
| ------------------------------- | ----- | -------------------------- | -------- | -------------------- | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID               | No       | -                    | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>`           | `-p`  | Workspace profile          | No       | -                    | `TAILOR_PLATFORM_PROFILE`      |
| `--config <CONFIG>`             | `-c`  | Path to Tailor config file | No       | `"tailor.config.ts"` | `TAILOR_CONFIG_PATH`           |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

## oauth2client

Manage OAuth2 clients in your Tailor Platform application.

**Usage**

```
tailor oauth2client [command]
```

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

**Commands**

| Command                                   | Description                                              |
| ----------------------------------------- | -------------------------------------------------------- |
| [`oauth2client list`](#oauth2client-list) | List all OAuth2 clients in the application.              |
| [`oauth2client get`](#oauth2client-get)   | Get OAuth2 client credentials (including client secret). |

### oauth2client list

List all OAuth2 clients in the application.

**Usage**

```
tailor oauth2client list [options]
```

**Options**

| Option                          | Alias | Description                                              | Required | Default              | Env                            |
| ------------------------------- | ----- | -------------------------------------------------------- | -------- | -------------------- | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID                                             | No       | -                    | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>`           | `-p`  | Workspace profile                                        | No       | -                    | `TAILOR_PLATFORM_PROFILE`      |
| `--config <CONFIG>`             | `-c`  | Path to Tailor config file                               | No       | `"tailor.config.ts"` | `TAILOR_CONFIG_PATH`           |
| `--order <ORDER>`               | -     | Sort order (asc or desc)                                 | No       | `"desc"`             | -                              |
| `--limit <LIMIT>`               | `-l`  | Maximum number of items to return (0 or omit: unlimited) | No       | -                    | -                              |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

**Output:**

Returns a list of OAuth2 clients with the following fields:

* `name` - Client name
* `description` - Client description
* `clientId` - OAuth2 client ID
* `grantTypes` - Supported grant types (e.g., `authorization_code`, `refresh_token`)
* `redirectUris` - Registered redirect URIs
* `createdAt` - Creation timestamp

### oauth2client get

Get OAuth2 client credentials (including client secret).

**Usage**

```
tailor oauth2client get [options] <name>
```

**Arguments**

| Argument | Description        | Required |
| -------- | ------------------ | -------- |
| `name`   | OAuth2 client name | Yes      |

**Options**

| Option                          | Alias | Description                | Required | Default              | Env                            |
| ------------------------------- | ----- | -------------------------- | -------- | -------------------- | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID               | No       | -                    | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>`           | `-p`  | Workspace profile          | No       | -                    | `TAILOR_PLATFORM_PROFILE`      |
| `--config <CONFIG>`             | `-c`  | Path to Tailor config file | No       | `"tailor.config.ts"` | `TAILOR_CONFIG_PATH`           |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

**Output:**

Returns the OAuth2 client credentials with the following fields:

* `name` - Client name
* `description` - Client description
* `clientId` - OAuth2 client ID
* `clientSecret` - OAuth2 client secret
* `grantTypes` - Supported grant types
* `redirectUris` - Registered redirect URIs
* `createdAt` - Creation timestamp

---

---
url: https://docs.tailor.tech/sdk/cli/completion.md
---
# Completion

## completion

Generate shell completion script

**Usage**

```
tailor completion [options] [shell]
```

**Arguments**

| Argument | Description                     | Required |
| -------- | ------------------------------- | -------- |
| `shell`  | Shell type (bash, zsh, or fish) | No       |

**Options**

| Option           | Alias | Description                                                                                                                          | Required | Default |
| ---------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------ | -------- | ------- |
| `--instructions` | `-i`  | Show installation instructions                                                                                                       | No       | `false` |
| `--loader`       | -     | Print just the rc loader snippet (bash/zsh). Add it to ~/.bashrc or ~/.zshrc; it auto-regenerates the cache when the binary changes. | No       | `false` |
| `--install`      | -     | Write the completion script to its on-disk cache (bash/zsh) or autoload location (fish) instead of printing it.                      | No       | `false` |
| `--static`       | -     | Generate the legacy static completion script with command metadata baked in.                                                         | No       | `false` |
| `--dispatcher`   | -     | Generate the runtime dispatcher completion script. This is the default.                                                              | No       | `false` |
| `--worker`       | -     | Generate an internal static worker artifact for dispatcher mode.                                                                     | No       | `false` |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

---

---
url: https://docs.tailor.tech/sdk/cli/crashreport.md
---
# Crash Report Commands

Commands for managing crash reports.

## crashreport

Manage crash reports.

**Usage**

```
tailor crashreport [command]
```

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

**Commands**

| Command                                 | Description                                    |
| --------------------------------------- | ---------------------------------------------- |
| [`crashreport list`](#crashreport-list) | List local crash report files.                 |
| [`crashreport send`](#crashreport-send) | Submit a crash report to help improve the SDK. |

### crashreport list

List local crash report files.

**Usage**

```
tailor crashreport list [options]
```

**Options**

| Option            | Alias | Description                                              | Required | Default  |
| ----------------- | ----- | -------------------------------------------------------- | -------- | -------- |
| `--order <ORDER>` | -     | Sort order (asc or desc)                                 | No       | `"desc"` |
| `--limit <LIMIT>` | `-l`  | Maximum number of items to return (0 or omit: unlimited) | No       | -        |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

### crashreport send

Submit a crash report to help improve the SDK.

**Usage**

```
tailor crashreport send [options]
```

**Options**

| Option          | Alias | Description                   | Required | Default |
| --------------- | ----- | ----------------------------- | -------- | ------- |
| `--file <FILE>` | -     | Path to the crash report file | Yes      | -       |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

---

---
url: https://docs.tailor.tech/sdk/cli/executor.md
---
# Executor Commands

Commands for managing executors and executor jobs.

## executor

Manage executors

**Usage**

```
tailor executor [command]
```

**Commands**

| Command                                 | Description                   |
| --------------------------------------- | ----------------------------- |
| [`executor trigger`](#executor-trigger) | Trigger an executor manually. |
| [`executor jobs`](#executor-jobs)       | List or get executor jobs.    |
| [`executor list`](#executor-list)       | List all executors            |
| [`executor get`](#executor-get)         | Get executor details          |
| [`executor webhook`](#executor-webhook) | Manage executor webhooks      |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

### executor list

List all executors

**Usage**

```
tailor executor list [options]
```

**Options**

| Option                          | Alias | Description                                              | Required | Default  | Env                            |
| ------------------------------- | ----- | -------------------------------------------------------- | -------- | -------- | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID                                             | No       | -        | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>`           | `-p`  | Workspace profile                                        | No       | -        | `TAILOR_PLATFORM_PROFILE`      |
| `--order <ORDER>`               | -     | Sort order (asc or desc)                                 | No       | `"desc"` | -                              |
| `--limit <LIMIT>`               | `-l`  | Maximum number of items to return (0 or omit: unlimited) | No       | -        | -                              |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

### executor get

Get executor details

**Usage**

```
tailor executor get [options] <name>
```

**Arguments**

| Argument | Description   | Required |
| -------- | ------------- | -------- |
| `name`   | Executor name | Yes      |

**Options**

| Option                          | Alias | Description       | Required | Default | Env                            |
| ------------------------------- | ----- | ----------------- | -------- | ------- | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID      | No       | -       | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>`           | `-p`  | Workspace profile | No       | -       | `TAILOR_PLATFORM_PROFILE`      |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

### executor jobs

List or get executor jobs.

**Usage**

```
tailor executor jobs [options] <executor-name> [job-id]
```

**Arguments**

| Argument        | Description                             | Required |
| --------------- | --------------------------------------- | -------- |
| `executor-name` | Executor name                           | Yes      |
| `job-id`        | Job ID (if provided, shows job details) | No       |

**Options**

| Option                          | Alias | Description                                                                                           | Required | Default  | Env                            |
| ------------------------------- | ----- | ----------------------------------------------------------------------------------------------------- | -------- | -------- | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID                                                                                          | No       | -        | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>`           | `-p`  | Workspace profile                                                                                     | No       | -        | `TAILOR_PLATFORM_PROFILE`      |
| `--status <STATUS>`             | `-s`  | Filter by status (PENDING, RUNNING, SUCCESS, FAILED, CANCELED) (list mode only)                       | No       | -        | -                              |
| `--attempts`                    | -     | Show job attempts (only with job ID) (detail mode only)                                               | No       | `false`  | -                              |
| `--wait`                        | `-W`  | Wait for job completion and downstream execution (workflow/function) if applicable (detail mode only) | No       | `false`  | -                              |
| `--interval <INTERVAL>`         | `-i`  | Polling interval when using --wait (e.g., '3s', '500ms', '1m')                                        | No       | `"3s"`   | -                              |
| `--timeout <TIMEOUT>`           | `-t`  | Maximum time to wait when using --wait (e.g., '30s', '5m')                                            | No       | `"5m"`   | -                              |
| `--order <ORDER>`               | -     | Sort order (asc or desc)                                                                              | No       | `"desc"` | -                              |
| `--limit <LIMIT>`               | -     | Maximum number of jobs to list (0: unlimited, default: 50) (list mode only)                           | No       | `50`     | -                              |
| `--logs`                        | `-l`  | Display function execution logs after completion (requires --wait)                                    | No       | `false`  | -                              |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

**Examples**

**List jobs for an executor (default: 50 jobs)**

```bash
$ tailor executor jobs my-executor
```

**Limit the number of jobs**

```bash
$ tailor executor jobs my-executor --limit 10
```

**Filter by status**

```bash
$ tailor executor jobs my-executor -s RUNNING
```

**Get job details**

```bash
$ tailor executor jobs my-executor <job-id>
```

**Get job details with attempts**

```bash
$ tailor executor jobs my-executor <job-id> --attempts
```

**Wait for job to complete**

```bash
$ tailor executor jobs my-executor <job-id> -W
```

**Wait for job with logs**

```bash
$ tailor executor jobs my-executor <job-id> -W -l
```

### executor trigger

Trigger an executor manually.

**Usage**

```
tailor executor trigger [options] <executor-name>
```

**Arguments**

| Argument        | Description   | Required |
| --------------- | ------------- | -------- |
| `executor-name` | Executor name | Yes      |

**Options**

| Option                          | Alias | Description                                                                        | Required | Default | Env                            |
| ------------------------------- | ----- | ---------------------------------------------------------------------------------- | -------- | ------- | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID                                                                       | No       | -       | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>`           | `-p`  | Workspace profile                                                                  | No       | -       | `TAILOR_PLATFORM_PROFILE`      |
| `--data <DATA>`                 | `-d`  | Request body (JSON string)                                                         | No       | -       | -                              |
| `--header <HEADER>`             | `-H`  | Request header (format: 'Key: Value', can be specified multiple times)             | No       | -       | -                              |
| `--wait`                        | `-W`  | Wait for job completion and downstream execution (workflow/function) if applicable | No       | `false` | -                              |
| `--interval <INTERVAL>`         | `-i`  | Polling interval when using --wait (e.g., '3s', '500ms', '1m')                     | No       | `"3s"`  | -                              |
| `--timeout <TIMEOUT>`           | `-t`  | Maximum time to wait when using --wait (e.g., '30s', '5m')                         | No       | `"5m"`  | -                              |
| `--logs`                        | `-l`  | Display function execution logs after completion (requires --wait)                 | No       | `false` | -                              |

**Examples**

**Trigger an executor**

```bash
$ tailor executor trigger my-executor
```

**Trigger with data**

```bash
$ tailor executor trigger my-executor -d '{"message": "hello"}'
```

**Trigger with data and headers**

```bash
$ tailor executor trigger my-executor -d '{"message": "hello"}' -H "X-Custom: value" -H "X-Another: value2"
```

**Trigger and wait for completion**

```bash
$ tailor executor trigger my-executor -W
```

**Trigger, wait, and show logs**

```bash
$ tailor executor trigger my-executor -W -l
```

**Shell automation**

Trigger an executor and wait for the executor job plus any downstream workflow or
function execution:

```bash
tailor executor trigger daily-workflow \
  --wait \
  --timeout 5m \
  --interval 5s \
  --json
```

Wait for an existing job when another process already captured the job ID:

```bash
tailor executor jobs daily-workflow "$job_id" \
  --wait \
  --timeout 5m \
  --logs \
  --json
```

**Programmatic API**

Import your executor definition and pass it to the typed API:

```ts
import { triggerExecutor, watchExecutorJob } from "@tailor-platform/sdk/cli";
import dailyWorkflow from "../executors/dailyWorkflow";

const { jobId } = await triggerExecutor({
  executor: dailyWorkflow,
});

if (!jobId) {
  throw new Error("Executor trigger did not return a job ID");
}

const result = await watchExecutorJob({
  executor: dailyWorkflow,
  jobId,
  timeout: 5 * 60 * 1000,
  interval: 5000,
});

if (result.timedOut) {
  throw new Error(`Executor job ${result.job.id} timed out at ${result.job.status}`);
}
```

**Notes**

Only executors with `INCOMING_WEBHOOK` or `SCHEDULE` trigger types can be triggered manually.
Executors with `EVENT` trigger types (such as `recordCreated`, `recordUpdated`, `recordDeleted`) cannot be triggered manually.

The `--data` and `--header` options are only available for `INCOMING_WEBHOOK` trigger type.

**Downstream Execution Tracking**

When using `--wait`, the CLI tracks not only the executor job but also any downstream executions:

* **Workflow targets**: Waits for the workflow execution to complete (SUCCESS, FAILED, or PENDING\_RESUME). Shows real-time status changes and currently running job names during execution (same output as `workflow start --wait`).
* **Function targets**: Waits for the function execution to complete
* **Webhook/GraphQL targets**: Only waits for the executor job itself

The `--logs` option displays logs from the downstream execution when available.

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

### executor webhook

Manage executor webhooks

**Usage**

```
tailor executor webhook [command]
```

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

**Commands**

| Command                                           | Description                                   |
| ------------------------------------------------- | --------------------------------------------- |
| [`executor webhook list`](#executor-webhook-list) | List executors with incoming webhook triggers |

#### executor webhook list

List executors with incoming webhook triggers

**Usage**

```
tailor executor webhook list [options]
```

**Options**

| Option                          | Alias | Description                                              | Required | Default  | Env                            |
| ------------------------------- | ----- | -------------------------------------------------------- | -------- | -------- | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID                                             | No       | -        | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>`           | `-p`  | Workspace profile                                        | No       | -        | `TAILOR_PLATFORM_PROFILE`      |
| `--order <ORDER>`               | -     | Sort order (asc or desc)                                 | No       | `"desc"` | -                              |
| `--limit <LIMIT>`               | `-l`  | Maximum number of items to return (0 or omit: unlimited) | No       | -        | -                              |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

---

---
url: https://docs.tailor.tech/sdk/cli/function.md
---
# Function Commands

Commands for managing function registries and viewing function execution logs.

## function

Manage functions

**Usage**

```
tailor function [command]
```

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

**Commands**

| Command                               | Aliases    | Description                                                     |
| ------------------------------------- | ---------- | --------------------------------------------------------------- |
| [`function get`](#function-get)       | -          | Get a function registry by name                                 |
| [`function list`](#function-list)     | -          | List function registries in a workspace                         |
| [`function logs`](#function-logs)     | -          | List or get function execution logs.                            |
| [`function run`](#function-run)       | `test-run` | Run a function on the Tailor Platform server without deploying. |
| [`function script`](#function-script) | -          | Scaffold a one-off script to run with `function run`.           |

### function get

Get a function registry by name

**Usage**

```
tailor function get [options]
```

**Options**

| Option                          | Alias | Description       | Required | Default | Env                            |
| ------------------------------- | ----- | ----------------- | -------- | ------- | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID      | No       | -       | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>`           | `-p`  | Workspace profile | No       | -       | `TAILOR_PLATFORM_PROFILE`      |
| `--name <NAME>`                 | `-n`  | Function name     | Yes      | -       | -                              |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

### function list

List function registries in a workspace

**Usage**

```
tailor function list [options]
```

**Options**

| Option                          | Alias | Description                                              | Required | Default  | Env                            |
| ------------------------------- | ----- | -------------------------------------------------------- | -------- | -------- | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID                                             | No       | -        | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>`           | `-p`  | Workspace profile                                        | No       | -        | `TAILOR_PLATFORM_PROFILE`      |
| `--order <ORDER>`               | -     | Sort order (asc or desc)                                 | No       | `"desc"` | -                              |
| `--limit <LIMIT>`               | `-l`  | Maximum number of items to return (0 or omit: unlimited) | No       | -        | -                              |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

### function logs

List or get function execution logs.

**Usage**

```
tailor function logs [options] [execution-id]
```

**Arguments**

| Argument       | Description                                         | Required |
| -------------- | --------------------------------------------------- | -------- |
| `execution-id` | Execution ID (if provided, shows details with logs) | No       |

**Options**

| Option                          | Alias | Description                                      | Required | Default  | Env                            |
| ------------------------------- | ----- | ------------------------------------------------ | -------- | -------- | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID                                     | No       | -        | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>`           | `-p`  | Workspace profile                                | No       | -        | `TAILOR_PLATFORM_PROFILE`      |
| `--order <ORDER>`               | -     | Sort order (asc or desc)                         | No       | `"desc"` | -                              |
| `--limit <LIMIT>`               | `-l`  | Maximum number of items to return (0: unlimited) | No       | `50`     | -                              |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

**Examples**

**List all function execution logs**

```bash
$ tailor function logs
```

**Get execution details with logs**

```bash
$ tailor function logs <execution-id>
```

**Output as JSON**

```bash
$ tailor function logs --json
```

**Get execution details as JSON**

```bash
$ tailor function logs <execution-id> --json
```

**Notes**

When viewing a specific execution that failed, the command displays error details with the stack trace mapped back to your original source files (clickable file links and code snippets, matching `function run` output).

Stack traces are mapped only when the execution includes a content hash for the exact build that ran. If the content hash is missing or the build is no longer available, the command falls back to a plain-text error display.

### function run

Run a function on the Tailor Platform server without deploying.

**Aliases:** `test-run`

**Usage**

```
tailor function run [options] <file>
```

**Arguments**

| Argument | Description               | Required |
| -------- | ------------------------- | -------- |
| `file`   | Path to the function file | Yes      |

**Options**

| Option                          | Alias | Description                                                                                    | Required | Default              | Env                                 |
| ------------------------------- | ----- | ---------------------------------------------------------------------------------------------- | -------- | -------------------- | ----------------------------------- |
| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID                                                                                   | No       | -                    | `TAILOR_PLATFORM_WORKSPACE_ID`      |
| `--profile <PROFILE>`           | `-p`  | Workspace profile                                                                              | No       | -                    | `TAILOR_PLATFORM_PROFILE`           |
| `--name <NAME>`                 | `-n`  | Workflow job name to run (matches the `name` field of createWorkflowJob)                       | No       | -                    | -                                   |
| `--arg <ARG>`                   | `-a`  | JSON argument to pass to the function                                                          | No       | -                    | -                                   |
| `--machine-user <MACHINE_USER>` | `-m`  | Machine user name for authentication. Falls back to the active profile's default machine user. | No       | -                    | `TAILOR_PLATFORM_MACHINE_USER_NAME` |
| `--config <CONFIG>`             | `-c`  | Path to SDK config file                                                                        | No       | `"tailor.config.ts"` | -                                   |
| `--allow-schema-drift`          | -     | Run a scaffolded script even when its schema snapshot no longer matches                        | No       | `false`              | -                                   |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

**Examples**

**Run a resolver with input arguments**

```bash
$ tailor function run resolvers/add.ts --arg '{"a":1,"b":2}'
```

**Run a specific workflow job by name**

```bash
$ tailor function run workflows/sample.ts --name validate-order
```

**Run a pre-bundled .js file directly**

```bash
$ tailor function run build/resolvers/add.js --arg '{"a":1,"b":2}'
```

**Notes**

You can pass either a source file (`.ts`) or a pre-bundled file (`.js`).
When a `.js` file is provided, detection and bundling are skipped and the file is executed as-is.

A script scaffolded by `function script` with a generated `db.ts` is checked against its `db.snapshot.json` before execution and refused on schema drift; pass `--allow-schema-drift` to run it anyway. The check compares table and field structure; hook and validator code changes are not detected.

`test-run` is a deprecated alias of this command and will be removed in v3.

> \[!WARNING]
> Workflow job `.start()` calls do not work in this mode.
> Started jobs are not executed; only the target job's `body` function runs in isolation.

### function script

Scaffold a one-off script to run with `function run`.

**Usage**

```
tailor function script [options] <file>
```

**Arguments**

| Argument | Description                                      | Required |
| -------- | ------------------------------------------------ | -------- |
| `file`   | Path to create the script at (must end with .ts) | Yes      |

**Options**

| Option                          | Alias | Description                                                           | Required | Default              | Env                            |
| ------------------------------- | ----- | --------------------------------------------------------------------- | -------- | -------------------- | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID                                                          | No       | -                    | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>`           | `-p`  | Workspace profile                                                     | No       | -                    | `TAILOR_PLATFORM_PROFILE`      |
| `--config <CONFIG>`             | `-c`  | Path to Tailor config file                                            | No       | `"tailor.config.ts"` | `TAILOR_CONFIG_PATH`           |
| `--namespace <NAMESPACE>`       | -     | Target TailorDB namespace (required when the config does not pin one) | No       | -                    | -                              |
| `--remote`                      | -     | Generate script-scoped DB types from the deployed schema              | No       | `false`              | -                              |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

**Examples**

**Scaffold a one-off script (single-namespace project)**

```bash
$ tailor function script scripts/fix-prices.ts
```

**Scaffold a script targeting a specific namespace**

```bash
$ tailor function script scripts/fix-prices.ts --namespace tailordb
```

**Scaffold from a deployed or external namespace**

```bash
$ tailor function script scripts/fix-prices.ts --namespace shared --remote
```

**Notes**

The scaffolded script is a plain default-exported function; execute it with `tailor function run <file>`.

By default, when the project configures `kyselyTypePlugin`, the skeleton imports `getDB()` from the plugin's generated types. Without the plugin, the command uses the namespace's local table definitions to write a script-scoped `db.ts` plus a `db.snapshot.json` next to the script; `function run` refuses to run the script when that snapshot no longer matches the deployed or locally defined table and field structure.

Pass `--remote` to generate the script-scoped files from the deployed schema instead, even when `kyselyTypePlugin` is configured. This is required for an external namespace. Re-running the command refreshes `db.ts` and `db.snapshot.json` from the selected source and leaves the script itself untouched.

---

---
url: https://docs.tailor.tech/sdk/cli/organization.md
---
## organization

Manage Tailor Platform organizations.

**Usage**

```
tailor organization [command]
```

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

**Commands**

| Command                                       | Description                                      |
| --------------------------------------------- | ------------------------------------------------ |
| [`organization folder`](#organization-folder) | Manage organization folders.                     |
| [`organization get`](#organization-get)       | Show detailed information about an organization. |
| [`organization list`](#organization-list)     | List organizations you belong to.                |
| [`organization tree`](#organization-tree)     | Display organization folder hierarchy as a tree. |
| [`organization update`](#organization-update) | Update an organization's name.                   |

### organization folder

Manage organization folders.

**Usage**

```
tailor organization folder <command>
```

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

**Commands**

| Command                                                     | Description                               |
| ----------------------------------------------------------- | ----------------------------------------- |
| [`organization folder create`](#organization-folder-create) | Create a new folder in an organization.   |
| [`organization folder delete`](#organization-folder-delete) | Delete a folder from an organization.     |
| [`organization folder get`](#organization-folder-get)       | Show detailed information about a folder. |
| [`organization folder list`](#organization-folder-list)     | List folders in an organization.          |
| [`organization folder update`](#organization-folder-update) | Update a folder's name.                   |

#### organization folder create

Create a new folder in an organization.

**Usage**

```
tailor organization folder create [options]
```

**Options**

| Option                                  | Alias | Description      | Required | Default | Env                               |
| --------------------------------------- | ----- | ---------------- | -------- | ------- | --------------------------------- |
| `--organization-id <ORGANIZATION_ID>`   | `-o`  | Organization ID  | Yes      | -       | `TAILOR_PLATFORM_ORGANIZATION_ID` |
| `--parent-folder-id <PARENT_FOLDER_ID>` | -     | Parent folder ID | No       | -       | -                                 |
| `--name <NAME>`                         | `-n`  | Folder name      | Yes      | -       | -                                 |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

#### organization folder delete

Delete a folder from an organization.

**Usage**

```
tailor organization folder delete [options]
```

**Options**

| Option                                | Alias | Description               | Required | Default | Env                               |
| ------------------------------------- | ----- | ------------------------- | -------- | ------- | --------------------------------- |
| `--organization-id <ORGANIZATION_ID>` | `-o`  | Organization ID           | Yes      | -       | `TAILOR_PLATFORM_ORGANIZATION_ID` |
| `--folder-id <FOLDER_ID>`             | `-f`  | Folder ID                 | Yes      | -       | `TAILOR_PLATFORM_FOLDER_ID`       |
| `--yes`                               | `-y`  | Skip confirmation prompts | No       | `false` | -                                 |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

#### organization folder get

Show detailed information about a folder.

**Usage**

```
tailor organization folder get [options]
```

**Options**

| Option                                | Alias | Description     | Required | Default | Env                               |
| ------------------------------------- | ----- | --------------- | -------- | ------- | --------------------------------- |
| `--organization-id <ORGANIZATION_ID>` | `-o`  | Organization ID | Yes      | -       | `TAILOR_PLATFORM_ORGANIZATION_ID` |
| `--folder-id <FOLDER_ID>`             | `-f`  | Folder ID       | Yes      | -       | `TAILOR_PLATFORM_FOLDER_ID`       |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

#### organization folder list

List folders in an organization.

**Usage**

```
tailor organization folder list [options]
```

**Options**

| Option                                  | Alias | Description                                              | Required | Default  | Env                               |
| --------------------------------------- | ----- | -------------------------------------------------------- | -------- | -------- | --------------------------------- |
| `--organization-id <ORGANIZATION_ID>`   | `-o`  | Organization ID                                          | Yes      | -        | `TAILOR_PLATFORM_ORGANIZATION_ID` |
| `--parent-folder-id <PARENT_FOLDER_ID>` | -     | Parent folder ID to list children of                     | No       | -        | -                                 |
| `--order <ORDER>`                       | -     | Sort order (asc or desc)                                 | No       | `"desc"` | -                                 |
| `--limit <LIMIT>`                       | `-l`  | Maximum number of items to return (0 or omit: unlimited) | No       | -        | -                                 |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

#### organization folder update

Update a folder's name.

**Usage**

```
tailor organization folder update [options]
```

**Options**

| Option                                | Alias | Description     | Required | Default | Env                               |
| ------------------------------------- | ----- | --------------- | -------- | ------- | --------------------------------- |
| `--organization-id <ORGANIZATION_ID>` | `-o`  | Organization ID | Yes      | -       | `TAILOR_PLATFORM_ORGANIZATION_ID` |
| `--folder-id <FOLDER_ID>`             | `-f`  | Folder ID       | Yes      | -       | `TAILOR_PLATFORM_FOLDER_ID`       |
| `--name <NAME>`                       | `-n`  | New folder name | Yes      | -       | -                                 |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

### organization get

Show detailed information about an organization.

**Usage**

```
tailor organization get [options]
```

**Options**

| Option                                | Alias | Description     | Required | Default | Env                               |
| ------------------------------------- | ----- | --------------- | -------- | ------- | --------------------------------- |
| `--organization-id <ORGANIZATION_ID>` | `-o`  | Organization ID | Yes      | -       | `TAILOR_PLATFORM_ORGANIZATION_ID` |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

### organization list

List organizations you belong to.

**Usage**

```
tailor organization list [options]
```

**Options**

| Option            | Alias | Description                             | Required | Default |
| ----------------- | ----- | --------------------------------------- | -------- | ------- |
| `--limit <LIMIT>` | `-l`  | Maximum number of organizations to list | No       | -       |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

### organization tree

Display organization folder hierarchy as a tree.

**Usage**

```
tailor organization tree [options]
```

**Options**

| Option                                | Alias | Description                           | Required | Default | Env                               |
| ------------------------------------- | ----- | ------------------------------------- | -------- | ------- | --------------------------------- |
| `--organization-id <ORGANIZATION_ID>` | `-o`  | Organization ID (show all if omitted) | No       | -       | `TAILOR_PLATFORM_ORGANIZATION_ID` |
| `--depth <DEPTH>`                     | `-d`  | Maximum folder depth to display       | No       | -       | -                                 |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

### organization update

Update an organization's name.

**Usage**

```
tailor organization update [options]
```

**Options**

| Option                                | Alias | Description           | Required | Default | Env                               |
| ------------------------------------- | ----- | --------------------- | -------- | ------- | --------------------------------- |
| `--organization-id <ORGANIZATION_ID>` | `-o`  | Organization ID       | Yes      | -       | `TAILOR_PLATFORM_ORGANIZATION_ID` |
| `--name <NAME>`                       | `-n`  | New organization name | Yes      | -       | -                                 |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

---

---
url: https://docs.tailor.tech/sdk/cli/plugin.md
---
## plugin

Manage and inspect CLI plugins (beta).

**Usage**

```
tailor plugin [command]
```

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

**Commands**

| Command                       | Description                                                                              |
| ----------------------------- | ---------------------------------------------------------------------------------------- |
| [`plugin list`](#plugin-list) | List discovered plugins (executables named `<cli>-<name>` on PATH or node\_modules/.bin). |

### plugin list

List discovered plugins (executables named `<cli>-<name>` on PATH or node\_modules/.bin).

**Usage**

```
tailor plugin list
```

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

---

---
url: https://docs.tailor.tech/sdk/cli/query.md
---
## query

Run SQL/GraphQL query.

**Usage**

```
tailor query [options]
```

**Options**

| Option                          | Alias | Description                                                                                          | Required | Default              | Env                                 |
| ------------------------------- | ----- | ---------------------------------------------------------------------------------------------------- | -------- | -------------------- | ----------------------------------- |
| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID                                                                                         | No       | -                    | `TAILOR_PLATFORM_WORKSPACE_ID`      |
| `--profile <PROFILE>`           | `-p`  | Workspace profile                                                                                    | No       | -                    | `TAILOR_PLATFORM_PROFILE`           |
| `--config <CONFIG>`             | `-c`  | Path to Tailor config file                                                                           | No       | `"tailor.config.ts"` | `TAILOR_CONFIG_PATH`                |
| `--engine <ENGINE>`             | -     | Query engine (sql or gql)                                                                            | Yes      | -                    | -                                   |
| `--query <QUERY>`               | `-q`  | Query string to execute directly; omit to start REPL mode                                            | No       | -                    | -                                   |
| `--file <FILE>`                 | `-f`  | Read query string from file; omit to start REPL mode                                                 | No       | -                    | -                                   |
| `--edit`                        | -     | Open a temporary file in your editor; omit to start REPL mode                                        | No       | `false`              | -                                   |
| `--machine-user <MACHINE_USER>` | `-m`  | Machine user name for query execution. Falls back to the active profile's default machine user.      | No       | -                    | `TAILOR_PLATFORM_MACHINE_USER_NAME` |
| `--newline-on-enter`            | -     | REPL: when true, Enter inserts a newline and Shift+Enter submits. Use --no-newline-on-enter to swap. | No       | -                    | -                                   |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

---

---
url: https://docs.tailor.tech/sdk/cli/secret.md
---
# Secret Commands

Commands for managing Secret Manager vaults and secrets.

## secret

Manage Secret Manager vaults and secrets.

**Usage**

```
tailor secret [command]
```

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

**Commands**

| Command                           | Description                   |
| --------------------------------- | ----------------------------- |
| [`secret vault`](#secret-vault)   | Manage Secret Manager vaults. |
| [`secret create`](#secret-create) | Create a secret in a vault.   |
| [`secret update`](#secret-update) | Update a secret in a vault.   |
| [`secret list`](#secret-list)     | List all secrets in a vault.  |
| [`secret delete`](#secret-delete) | Delete a secret in a vault.   |

### secret create

Create a secret in a vault.

**Usage**

```
tailor secret create [options]
```

**Options**

| Option                          | Alias | Description               | Required | Default | Env                            |
| ------------------------------- | ----- | ------------------------- | -------- | ------- | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID              | No       | -       | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>`           | `-p`  | Workspace profile         | No       | -       | `TAILOR_PLATFORM_PROFILE`      |
| `--vault-name <VAULT_NAME>`     | `-V`  | Vault name                | Yes      | -       | -                              |
| `--name <NAME>`                 | `-n`  | Secret name               | Yes      | -       | -                              |
| `--value <VALUE>`               | `-v`  | Secret value              | Yes      | -       | -                              |
| `--yes`                         | `-y`  | Skip confirmation prompts | No       | `false` | -                              |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

### secret delete

Delete a secret in a vault.

**Usage**

```
tailor secret delete [options]
```

**Options**

| Option                          | Alias | Description               | Required | Default | Env                            |
| ------------------------------- | ----- | ------------------------- | -------- | ------- | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID              | No       | -       | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>`           | `-p`  | Workspace profile         | No       | -       | `TAILOR_PLATFORM_PROFILE`      |
| `--vault-name <VAULT_NAME>`     | `-V`  | Vault name                | Yes      | -       | -                              |
| `--name <NAME>`                 | `-n`  | Secret name               | Yes      | -       | -                              |
| `--yes`                         | `-y`  | Skip confirmation prompts | No       | `false` | -                              |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

### secret list

List all secrets in a vault.

**Usage**

```
tailor secret list [options]
```

**Options**

| Option                          | Alias | Description                                              | Required | Default  | Env                            |
| ------------------------------- | ----- | -------------------------------------------------------- | -------- | -------- | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID                                             | No       | -        | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>`           | `-p`  | Workspace profile                                        | No       | -        | `TAILOR_PLATFORM_PROFILE`      |
| `--vault-name <VAULT_NAME>`     | `-V`  | Vault name                                               | Yes      | -        | -                              |
| `--order <ORDER>`               | -     | Sort order (asc or desc)                                 | No       | `"desc"` | -                              |
| `--limit <LIMIT>`               | `-l`  | Maximum number of items to return (0 or omit: unlimited) | No       | -        | -                              |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

### secret update

Update a secret in a vault.

**Usage**

```
tailor secret update [options]
```

**Options**

| Option                          | Alias | Description               | Required | Default | Env                            |
| ------------------------------- | ----- | ------------------------- | -------- | ------- | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID              | No       | -       | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>`           | `-p`  | Workspace profile         | No       | -       | `TAILOR_PLATFORM_PROFILE`      |
| `--vault-name <VAULT_NAME>`     | `-V`  | Vault name                | Yes      | -       | -                              |
| `--name <NAME>`                 | `-n`  | Secret name               | Yes      | -       | -                              |
| `--value <VALUE>`               | `-v`  | Secret value              | Yes      | -       | -                              |
| `--yes`                         | `-y`  | Skip confirmation prompts | No       | `false` | -                              |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

### secret vault

Manage Secret Manager vaults.

**Usage**

```
tailor secret vault [command]
```

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

**Commands**

| Command                                       | Description                                      |
| --------------------------------------------- | ------------------------------------------------ |
| [`secret vault create`](#secret-vault-create) | Create a new Secret Manager vault.               |
| [`secret vault delete`](#secret-vault-delete) | Delete a Secret Manager vault.                   |
| [`secret vault list`](#secret-vault-list)     | List all Secret Manager vaults in the workspace. |

#### secret vault create

Create a new Secret Manager vault.

**Usage**

```
tailor secret vault create [options] <name>
```

**Arguments**

| Argument | Description | Required |
| -------- | ----------- | -------- |
| `name`   | Vault name  | Yes      |

**Options**

| Option                          | Alias | Description       | Required | Default | Env                            |
| ------------------------------- | ----- | ----------------- | -------- | ------- | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID      | No       | -       | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>`           | `-p`  | Workspace profile | No       | -       | `TAILOR_PLATFORM_PROFILE`      |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

#### secret vault delete

Delete a Secret Manager vault.

**Usage**

```
tailor secret vault delete [options] <name>
```

**Arguments**

| Argument | Description | Required |
| -------- | ----------- | -------- |
| `name`   | Vault name  | Yes      |

**Options**

| Option                          | Alias | Description               | Required | Default | Env                            |
| ------------------------------- | ----- | ------------------------- | -------- | ------- | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID              | No       | -       | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>`           | `-p`  | Workspace profile         | No       | -       | `TAILOR_PLATFORM_PROFILE`      |
| `--yes`                         | `-y`  | Skip confirmation prompts | No       | `false` | -                              |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

#### secret vault list

List all Secret Manager vaults in the workspace.

**Usage**

```
tailor secret vault list [options]
```

**Options**

| Option                          | Alias | Description                                              | Required | Default  | Env                            |
| ------------------------------- | ----- | -------------------------------------------------------- | -------- | -------- | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID                                             | No       | -        | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>`           | `-p`  | Workspace profile                                        | No       | -        | `TAILOR_PLATFORM_PROFILE`      |
| `--order <ORDER>`               | -     | Sort order (asc or desc)                                 | No       | `"desc"` | -                              |
| `--limit <LIMIT>`               | `-l`  | Maximum number of items to return (0 or omit: unlimited) | No       | -        | -                              |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

---

---
url: https://docs.tailor.tech/sdk/cli/skills.md
---
## skills

Manage Tailor SDK agent skills.

**Usage**

```
tailor skills [command]
```

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

**Commands**

| Command                           | Description                                   |
| --------------------------------- | --------------------------------------------- |
| [`skills sync`](#skills-sync)     | Remove and reinstall Tailor SDK agent skills. |
| [`skills add`](#skills-add)       | Install Tailor SDK agent skills.              |
| [`skills remove`](#skills-remove) | Remove installed Tailor SDK agent skills.     |
| [`skills list`](#skills-list)     | List Tailor SDK agent skills.                 |

### skills add

Install Tailor SDK agent skills.

**Usage**

```
tailor skills add [name]
```

**Arguments**

| Argument | Description                             | Required |
| -------- | --------------------------------------- | -------- |
| `name`   | Skill name(s) to install (default: all) | No       |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

### skills list

List Tailor SDK agent skills.

**Usage**

```
tailor skills list
```

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

### skills remove

Remove installed Tailor SDK agent skills.

**Usage**

```
tailor skills remove [name]
```

**Arguments**

| Argument | Description                         | Required |
| -------- | ----------------------------------- | -------- |
| `name`   | Skill name to remove (default: all) | No       |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

### skills sync

Remove and reinstall Tailor SDK agent skills.

**Usage**

```
tailor skills sync [options]
```

**Options**

| Option                | Alias | Description                      | Required | Default |
| --------------------- | ----- | -------------------------------- | -------- | ------- |
| `--exclude <EXCLUDE>` | `-x`  | Skill names to exclude from sync | No       | `[]`    |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

---

---
url: https://docs.tailor.tech/sdk/cli/staticwebsite.md
---
# Static Website Commands

Commands for managing and deploying static websites.

## staticwebsite

Manage static websites in your workspace.

**Usage**

```
tailor staticwebsite [command]
```

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

**Commands**

| Command                                         | Description                                           |
| ----------------------------------------------- | ----------------------------------------------------- |
| [`staticwebsite deploy`](#staticwebsite-deploy) | Deploy a static website from a local build directory. |
| [`staticwebsite domain`](#staticwebsite-domain) | Manage custom domains for static websites.            |
| [`staticwebsite list`](#staticwebsite-list)     | List all static websites in a workspace.              |
| [`staticwebsite get`](#staticwebsite-get)       | Get details of a specific static website.             |

### staticwebsite deploy

Deploy a static website from a local build directory.

**Usage**

```
tailor staticwebsite deploy [options]
```

**Options**

| Option                          | Alias | Description                      | Required | Default | Env                            |
| ------------------------------- | ----- | -------------------------------- | -------- | ------- | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID                     | No       | -       | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>`           | `-p`  | Workspace profile                | No       | -       | `TAILOR_PLATFORM_PROFILE`      |
| `--name <NAME>`                 | `-n`  | Static website name              | Yes      | -       | -                              |
| `--dir <DIR>`                   | `-d`  | Path to the static website files | Yes      | -       | -                              |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

**Example:**

```bash
# Deploy a static website from the dist directory
tailor staticwebsite deploy --name my-website --dir ./dist

# Deploy with workspace ID
tailor staticwebsite deploy -n my-website -d ./dist -w ws_abc123
```

**Notes:**

* The deployment process uploads all files from the specified directory
* Files are uploaded with appropriate MIME types based on file extensions
* Unsupported file types or invalid files will be skipped with warnings
* The deployment URL is returned after successful deployment

## staticwebsite list

List all static websites in a workspace.

**Usage**

```
tailor staticwebsite list [options]
```

**Options**

| Option                          | Alias | Description                                              | Required | Default  | Env                            |
| ------------------------------- | ----- | -------------------------------------------------------- | -------- | -------- | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID                                             | No       | -        | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>`           | `-p`  | Workspace profile                                        | No       | -        | `TAILOR_PLATFORM_PROFILE`      |
| `--order <ORDER>`               | -     | Sort order (asc or desc)                                 | No       | `"desc"` | -                              |
| `--limit <LIMIT>`               | `-l`  | Maximum number of items to return (0 or omit: unlimited) | No       | -        | -                              |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

**Example:**

```bash
# List all static websites
tailor staticwebsite list

# List with JSON output
tailor staticwebsite list --json
```

## staticwebsite domain

Manage custom domains for static websites.

**Usage**

```
tailor staticwebsite domain <command>
```

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

**Commands**

| Command                                                   | Description                               |
| --------------------------------------------------------- | ----------------------------------------- |
| [`staticwebsite domain list`](#staticwebsite-domain-list) | List custom domains for a static website. |
| [`staticwebsite domain get`](#staticwebsite-domain-get)   | Get details of a custom domain.           |

### staticwebsite domain get

Get details of a custom domain.

**Usage**

```
tailor staticwebsite domain get [options] <domain>
```

**Arguments**

| Argument | Description        | Required |
| -------- | ------------------ | -------- |
| `domain` | Custom domain name | Yes      |

**Options**

| Option                          | Alias | Description       | Required | Default | Env                            |
| ------------------------------- | ----- | ----------------- | -------- | ------- | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID      | No       | -       | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>`           | `-p`  | Workspace profile | No       | -       | `TAILOR_PLATFORM_PROFILE`      |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

#### staticwebsite domain list

List custom domains for a static website.

**Usage**

```
tailor staticwebsite domain list [options] <name>
```

**Arguments**

| Argument | Description         | Required |
| -------- | ------------------- | -------- |
| `name`   | Static website name | Yes      |

**Options**

| Option                          | Alias | Description       | Required | Default | Env                            |
| ------------------------------- | ----- | ----------------- | -------- | ------- | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID      | No       | -       | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>`           | `-p`  | Workspace profile | No       | -       | `TAILOR_PLATFORM_PROFILE`      |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

### staticwebsite get

Get details of a specific static website.

**Usage**

```
tailor staticwebsite get [options] <name>
```

**Arguments**

| Argument | Description         | Required |
| -------- | ------------------- | -------- |
| `name`   | Static website name | Yes      |

**Options**

| Option                          | Alias | Description       | Required | Default | Env                            |
| ------------------------------- | ----- | ----------------- | -------- | ------- | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID      | No       | -       | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>`           | `-p`  | Workspace profile | No       | -       | `TAILOR_PLATFORM_PROFILE`      |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

**Example:**

```bash
# Get details of a static website
tailor staticwebsite get my-website

# Get with JSON output
tailor staticwebsite get my-website --json
```

---

---
url: https://docs.tailor.tech/sdk/cli/tailordb.md
---
# TailorDB Commands

Commands for managing TailorDB tables, data, and schema migrations.

## tailordb

Manage TailorDB tables and data.

**Usage**

```
tailor tailordb <command>
```

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

**Commands**

| Command                                     | Description                                         |
| ------------------------------------------- | --------------------------------------------------- |
| [`tailordb truncate`](#tailordb-truncate)   | Truncate (delete all records from) TailorDB tables. |
| [`tailordb migration`](#tailordb-migration) | Manage TailorDB schema migrations.                  |

### tailordb truncate

Truncate (delete all records from) TailorDB tables.

**Usage**

```
tailor tailordb truncate [options] [tables]
```

**Arguments**

| Argument | Description             | Required |
| -------- | ----------------------- | -------- |
| `tables` | Table names to truncate | No       |

**Options**

| Option                          | Alias | Description                                                                | Required | Default              | Env                            |
| ------------------------------- | ----- | -------------------------------------------------------------------------- | -------- | -------------------- | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID                                                               | No       | -                    | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>`           | `-p`  | Workspace profile                                                          | No       | -                    | `TAILOR_PLATFORM_PROFILE`      |
| `--config <CONFIG>`             | `-c`  | Path to Tailor config file                                                 | No       | `"tailor.config.ts"` | `TAILOR_CONFIG_PATH`           |
| `--yes`                         | `-y`  | Skip confirmation prompts                                                  | No       | `false`              | -                              |
| `--all`                         | `-a`  | Truncate all tables in all owned namespaces (excludes external namespaces) | No       | `false`              | -                              |
| `--namespace <NAMESPACE>`       | `-n`  | Truncate all tables in specified namespace                                 | No       | -                    | -                              |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

**Usage Examples:**

```bash
# Truncate all tables in all namespaces (requires confirmation)
tailor tailordb truncate --all

# Truncate all tables in all namespaces (skip confirmation)
tailor tailordb truncate --all --yes

# Truncate all tables in a specific namespace
tailor tailordb truncate --namespace myNamespace

# Truncate specific tables (namespace is auto-detected)
tailor tailordb truncate User Post Comment

# Truncate specific tables with confirmation skipped
tailor tailordb truncate User Post --yes
```

**Notes:**

* You must specify exactly one of: `--all`, `--namespace`, or table names
* When truncating specific tables, the namespace is automatically detected from your config
* Confirmation prompts vary based on the operation:
  * `--all`: requires typing `truncate all`
  * `--namespace`: requires typing `truncate <namespace-name>`
  * Specific tables: requires typing `yes`
* Use `--yes` flag to skip confirmation prompts (useful for scripts and CI/CD)
* Namespaces declared with `{ external: true }` are skipped by `--all` and rejected with a dedicated error when targeted by `--namespace`. Run truncate from the app that owns the namespace.

## tailordb migration

Manage TailorDB schema migrations.

Note: Migration scripts are automatically executed during `tailor deploy`. See [Automatic Migration Execution](../services/tailordb-migration.md#automatic-migration-execution) for details.

**Usage**

```
tailor tailordb migration <command>
```

**Commands**

| Command                                                           | Description                                                                                                                                                                                                                                                                                                               |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`tailordb migration generate`](#tailordb-migration-generate)     | Generate migration files by detecting schema differences between current local tables and the previous migration snapshot.                                                                                                                                                                                                |
| [`tailordb migration rebaseline`](#tailordb-migration-rebaseline) | Collapse the full migration history into a new 0000 baseline.                                                                                                                                                                                                                                                             |
| [`tailordb migration script`](#tailordb-migration-script)         | Add a migration script (migrate.ts) template to an existing migration directory, or record with --no-script that a migration intentionally has none.                                                                                                                                                                      |
| [`tailordb migration set`](#tailordb-migration-set)               | Set migration checkpoint to a specific number.                                                                                                                                                                                                                                                                            |
| [`tailordb migration status`](#tailordb-migration-status)         | Show the current migration status for TailorDB namespaces, including applied and pending migrations.                                                                                                                                                                                                                      |
| [`tailordb migration sync`](#tailordb-migration-sync)             | Sync remote TailorDB schema to a specific migration snapshot (recovery from --no-schema-check drift).                                                                                                                                                                                                                     |
| [`tailordb migration test`](#tailordb-migration-test)             | Test pending migrations with seed fixtures or cloned data in a temporary workspace.                                                                                                                                                                                                                                       |
| [`tailordb migration validate`](#tailordb-migration-validate)     | Validate the full migration history, unreviewed generated migration scripts, and schema drift (local tables vs. migration snapshot, remote schema vs. migration checkpoint) without deploying. This includes the migration and schema-drift checks used by 'deploy' and exits with a non-zero code when issues are found. |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

### tailordb migration generate

Generate migration files by detecting schema differences between current local tables and the previous migration snapshot.

**Usage**

```
tailor tailordb migration generate [options]
```

**Options**

| Option                                | Alias | Description                                                                                                                                                                                     | Required | Default              | Env                  |
| ------------------------------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------- | -------------------- |
| `--yes`                               | `-y`  | Skip confirmation prompts                                                                                                                                                                       | No       | `false`              | -                    |
| `--config <CONFIG>`                   | `-c`  | Path to Tailor config file                                                                                                                                                                      | No       | `"tailor.config.ts"` | `TAILOR_CONFIG_PATH` |
| `--name <NAME>`                       | `-n`  | Optional description for the migration                                                                                                                                                          | No       | -                    | -                    |
| `--init`                              | -     | Delete existing migrations and start fresh                                                                                                                                                      | No       | `false`              | -                    |
| `--data-only`                         | -     | Create a migration with no schema changes whose migration script runs a standalone data transformation                                                                                          | No       | `false`              | -                    |
| `--namespace <NAMESPACE>`             | -     | Target TailorDB namespace for --data-only (required if multiple namespaces exist)                                                                                                               | No       | -                    | -                    |
| `--rename <RENAME>`                   | -     | Record a field or table rename instead of remove + add (format: "Table.oldField:newField" or "OldTable:NewTable"; repeatable). Renames require a migration script that copies the data.         | No       | -                    | -                    |
| `--drop <DROP>`                       | -     | Confirm that a removed field or table is a genuine removal, not a rename (format: "Table.field" or "Table"; repeatable). Required in non-interactive runs for a removal with rename candidates. | No       | -                    | -                    |
| `--expand-contract <EXPAND_CONTRACT>` | -     | Convert a field type through a temporary field (format: "Table.field"; repeatable). Generates two migrations.                                                                                   | No       | -                    | -                    |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

#### tailordb migration rebaseline

Collapse the full migration history into a new 0000 baseline.

**Usage**

```
tailor tailordb migration rebaseline [options]
```

**Options**

| Option                          | Alias | Description                                                       | Required | Default              | Env                            |
| ------------------------------- | ----- | ----------------------------------------------------------------- | -------- | -------------------- | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID                                                      | No       | -                    | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>`           | `-p`  | Workspace profile                                                 | No       | -                    | `TAILOR_PLATFORM_PROFILE`      |
| `--config <CONFIG>`             | `-c`  | Path to Tailor config file                                        | No       | `"tailor.config.ts"` | `TAILOR_CONFIG_PATH`           |
| `--yes`                         | `-y`  | Skip confirmation prompts                                         | No       | `false`              | -                              |
| `--namespace <NAMESPACE>`       | `-n`  | Target TailorDB namespace (required if multiple namespaces exist) | No       | -                    | -                              |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

**Notes**

Re-baselining removes migrations after 0000 from the working tree, records a new migration history ID, and resets the connected workspace checkpoint without changing its schema or data. Every environment must already have applied the latest migration before you run this command.

#### tailordb migration script

Add a migration script (migrate.ts) template to an existing migration directory, or record with --no-script that a migration intentionally has none.

**Usage**

```
tailor tailordb migration script [options] <number>
```

**Arguments**

| Argument | Description                                           | Required |
| -------- | ----------------------------------------------------- | -------- |
| `number` | Migration number to add a script to (e.g., 0001 or 1) | Yes      |

**Options**

| Option                    | Alias | Description                                                                                           | Required | Default              | Env                  |
| ------------------------- | ----- | ----------------------------------------------------------------------------------------------------- | -------- | -------------------- | -------------------- |
| `--config <CONFIG>`       | `-c`  | Path to Tailor config file                                                                            | No       | `"tailor.config.ts"` | `TAILOR_CONFIG_PATH` |
| `--namespace <NAMESPACE>` | `-n`  | Target TailorDB namespace (required if multiple namespaces exist)                                     | No       | -                    | -                    |
| `--no-script`             | -     | Record that this migration intentionally runs without a migration script (requires --reason)          | No       | -                    | -                    |
| `--reason <REASON>`       | -     | Reason why no migration script is needed (used with --no-script)                                      | No       | -                    | -                    |
| `--with-test`             | -     | Also add a migrate.test.ts unit-test scaffold; when migrate.ts already exists, only the test is added | No       | -                    | -                    |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

**Notes**

When `migrate.ts` already exists, running the command clears a previously recorded `--no-script` acknowledgment.

#### tailordb migration set

Set migration checkpoint to a specific number.

**Usage**

```
tailor tailordb migration set [options] <number>
```

**Arguments**

| Argument | Description                               | Required |
| -------- | ----------------------------------------- | -------- |
| `number` | Migration number to set (e.g., 0001 or 1) | Yes      |

**Options**

| Option                          | Alias | Description                                                       | Required | Default              | Env                            |
| ------------------------------- | ----- | ----------------------------------------------------------------- | -------- | -------------------- | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID                                                      | No       | -                    | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>`           | `-p`  | Workspace profile                                                 | No       | -                    | `TAILOR_PLATFORM_PROFILE`      |
| `--config <CONFIG>`             | `-c`  | Path to Tailor config file                                        | No       | `"tailor.config.ts"` | `TAILOR_CONFIG_PATH`           |
| `--yes`                         | `-y`  | Skip confirmation prompts                                         | No       | `false`              | -                              |
| `--namespace <NAMESPACE>`       | `-n`  | Target TailorDB namespace (required if multiple namespaces exist) | No       | -                    | -                              |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

**Notes**

The migration number must be a 4-digit value (e.g. `0001`) or a bare integer (e.g. `1`) within 0–9999, and must exist in the local migration history; `0` is always accepted as the baseline, provided the local history passes validation. A gapped history is rejected.

Metadata lookup failures (authentication, permission, or network errors) are reported as errors; only a not-yet-deployed namespace is treated as having no checkpoint.

#### tailordb migration status

Show the current migration status for TailorDB namespaces, including applied and pending migrations.

**Usage**

```
tailor tailordb migration status [options]
```

**Options**

| Option                          | Alias | Description                                                       | Required | Default              | Env                            |
| ------------------------------- | ----- | ----------------------------------------------------------------- | -------- | -------------------- | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID                                                      | No       | -                    | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>`           | `-p`  | Workspace profile                                                 | No       | -                    | `TAILOR_PLATFORM_PROFILE`      |
| `--config <CONFIG>`             | `-c`  | Path to Tailor config file                                        | No       | `"tailor.config.ts"` | `TAILOR_CONFIG_PATH`           |
| `--namespace <NAMESPACE>`       | `-n`  | Target TailorDB namespace (shows all namespaces if not specified) | No       | -                    | -                              |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

**Notes**

Every local migration file is checked for a compatible format version, and deployed migration history IDs must match the local baseline. Compatibility errors, history mismatches, and metadata lookup failures are reported per namespace and make the command exit non-zero; only a not-yet-deployed namespace is treated as having no applied migrations.

#### tailordb migration sync

Sync remote TailorDB schema to a specific migration snapshot (recovery from --no-schema-check drift).

**Usage**

```
tailor tailordb migration sync [options] <number>
```

**Arguments**

| Argument | Description                                                                    | Required |
| -------- | ------------------------------------------------------------------------------ | -------- |
| `number` | Migration number to sync to (e.g., 0001 or 1; 0 targets the baseline snapshot) | Yes      |

**Options**

| Option                          | Alias | Description                                                       | Required | Default              | Env                            |
| ------------------------------- | ----- | ----------------------------------------------------------------- | -------- | -------------------- | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID                                                      | No       | -                    | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>`           | `-p`  | Workspace profile                                                 | No       | -                    | `TAILOR_PLATFORM_PROFILE`      |
| `--config <CONFIG>`             | `-c`  | Path to Tailor config file                                        | No       | `"tailor.config.ts"` | `TAILOR_CONFIG_PATH`           |
| `--yes`                         | `-y`  | Skip confirmation prompts                                         | No       | `false`              | -                              |
| `--namespace <NAMESPACE>`       | `-n`  | Target TailorDB namespace (required if multiple namespaces exist) | No       | -                    | -                              |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

#### tailordb migration test

Test pending migrations with seed fixtures or cloned data in a temporary workspace.

**Usage**

```
tailor tailordb migration test [options]
```

**Options**

| Option                                        | Alias | Description                                                            | Required | Default              | Env                            |
| --------------------------------------------- | ----- | ---------------------------------------------------------------------- | -------- | -------------------- | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>`               | `-w`  | Workspace ID                                                           | No       | -                    | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>`                         | `-p`  | Workspace profile                                                      | No       | -                    | `TAILOR_PLATFORM_PROFILE`      |
| `--config <CONFIG>`                           | `-c`  | Path to Tailor config file                                             | No       | `"tailor.config.ts"` | `TAILOR_CONFIG_PATH`           |
| `--yes`                                       | `-y`  | Acknowledge that a designated target workspace may be overwritten      | No       | `false`              | -                              |
| `--data <DATA>`                               | -     | Data source for the migration test (seed or clone)                     | No       | `"seed"`             | -                              |
| `--target-workspace-id <TARGET_WORKSPACE_ID>` | -     | Existing throwaway workspace to retain after the test (requires --yes) | No       | -                    | -                              |
| `--keep`                                      | -     | Keep the automatically created workspace after the test                | No       | `false`              | -                              |
| `--assert <ASSERT>`                           | -     | Path to a TypeScript assertion script to run after migrations          | No       | -                    | -                              |
| `--assert-namespace <ASSERT_NAMESPACE>`       | -     | TailorDB namespace exposed to the assertion script                     | No       | -                    | -                              |
| `--machine-user <MACHINE_USER>`               | -     | Machine user for seed and assertion script execution                   | No       | -                    | -                              |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

**Notes**

The source workspace is read-only. Without --target-workspace-id, the command creates a workspace in the source workspace's region and deletes it after success or failure; pass --keep to retain it for inspection. A designated target is retained and requires --yes. Clone mode copies TailorDB records only; it does not copy IdP users or file blobs.

#### tailordb migration validate

Validate the full migration history, unreviewed generated migration scripts, and schema drift (local tables vs. migration snapshot, remote schema vs. migration checkpoint) without deploying. This includes the migration and schema-drift checks used by 'deploy' and exits with a non-zero code when issues are found.

**Usage**

```
tailor tailordb migration validate [options]
```

**Options**

| Option                          | Alias | Description                                                                | Required | Default              | Env                            |
| ------------------------------- | ----- | -------------------------------------------------------------------------- | -------- | -------------------- | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID                                                               | No       | -                    | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>`           | `-p`  | Workspace profile                                                          | No       | -                    | `TAILOR_PLATFORM_PROFILE`      |
| `--config <CONFIG>`             | `-c`  | Path to Tailor config file                                                 | No       | `"tailor.config.ts"` | `TAILOR_CONFIG_PATH`           |
| `--namespace <NAMESPACE>`       | `-n`  | Target TailorDB namespace (validates all namespaces if not specified)      | No       | -                    | -                              |
| `--strict`                      | -     | Also fail when a pending migration can drop data without an acknowledgment | No       | `false`              | -                              |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

**See also:** For migration concepts, configuration, workflow, and troubleshooting, see the [TailorDB Migrations guide](../services/tailordb-migration).

### tailordb erd

The `tailordb erd` commands (export, diff, serve, deploy) are provided by the `@tailor-platform/sdk-plugin-tailordb-erd` CLI plugin. Install it next to the SDK and keep running `tailor tailordb erd <command>` as before:

```bash
npm install -D @tailor-platform/sdk-plugin-tailordb-erd
tailor tailordb erd export --namespace myNamespace
```

See the plugin's README for the full command reference.

---

---
url: https://docs.tailor.tech/sdk/cli/upgrade.md
---
## upgrade

Run codemods to upgrade your project to a newer SDK version.

**Usage**

```
tailor upgrade [options]
```

**Options**

| Option          | Alias | Description                                   | Required | Default |
| --------------- | ----- | --------------------------------------------- | -------- | ------- |
| `--from <FROM>` | -     | SDK version before the upgrade (e.g., 1.33.0) | Yes      | -       |
| `--dry-run`     | `-d`  | Preview changes without modifying files       | No       | `false` |
| `--path <PATH>` | -     | Project directory to upgrade                  | No       | `"."`   |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

### How It Works

The `upgrade` command runs codemods that automatically transform your project code for breaking changes between SDK versions. The target version (`--to`) is auto-detected from the installed `@tailor-platform/sdk` in `node_modules`.

**Typical workflow:**

1. Update your SDK packages to the new version (e.g., `pnpm update @tailor-platform/sdk`)
2. Run `tailor upgrade --from <old-version>` to apply codemods
3. Review changes and commit

Use `--dry-run` to preview what changes will be made before applying them.

---

---
url: https://docs.tailor.tech/sdk/cli/user.md
---
# User & Auth Commands

Commands for authentication and user management.

## login

Login to Tailor Platform.

**Usage**

```
tailor login [options]
```

**Options**

| Option                | Alias | Description                                                         | Required | Default | Env                       |
| --------------------- | ----- | ------------------------------------------------------------------- | -------- | ------- | ------------------------- |
| `--profile <PROFILE>` | `-p`  | Workspace profile whose platform settings should be used for login. | No       | -       | `TAILOR_PLATFORM_PROFILE` |

> One of the following option groups is required:

**User Login:**

*no options*

**Machine User Login:**

| Option                            | Alias | Description                       | Required | Default | Env                                          |
| --------------------------------- | ----- | --------------------------------- | -------- | ------- | -------------------------------------------- |
| `--machine-user <MACHINE_USER>`   | -     | Login as a platform machine user. | Yes      | -       | -                                            |
| `--client-id <CLIENT_ID>`         | -     | Client ID                         | Yes      | -       | `TAILOR_PLATFORM_MACHINE_USER_CLIENT_ID`     |
| `--client-secret <CLIENT_SECRET>` | -     | Client secret                     | No       | -       | `TAILOR_PLATFORM_MACHINE_USER_CLIENT_SECRET` |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

## logout

Logout from Tailor Platform.

**Usage**

```
tailor logout [options]
```

**Options**

| Option                | Alias | Description                                                          | Required | Default | Env                       |
| --------------------- | ----- | -------------------------------------------------------------------- | -------- | ------- | ------------------------- |
| `--profile <PROFILE>` | `-p`  | Workspace profile whose platform settings should be used for logout. | No       | -       | `TAILOR_PLATFORM_PROFILE` |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

## auth

Authentication helpers for scripts and plugins.

**Usage**

```
tailor auth <command>
```

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

**Commands**

| Command                       | Description                                                                           |
| ----------------------------- | ------------------------------------------------------------------------------------- |
| [`auth status`](#auth-status) | Show the active Tailor Platform authentication status without printing tokens.        |
| [`auth token`](#auth-token)   | Print a valid Tailor Platform access token to stdout, refreshing it first if expired. |

### auth status

Show the active Tailor Platform authentication status without printing tokens.

**Usage**

```
tailor auth status [options]
```

**Options**

| Option                | Alias | Description       | Required | Default | Env                       |
| --------------------- | ----- | ----------------- | -------- | ------- | ------------------------- |
| `--profile <PROFILE>` | `-p`  | Workspace profile | No       | -       | `TAILOR_PLATFORM_PROFILE` |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

### auth token

Print a valid Tailor Platform access token to stdout, refreshing it first if expired.

**Usage**

```
tailor auth token [options]
```

**Options**

| Option                | Alias | Description       | Required | Default | Env                       |
| --------------------- | ----- | ----------------- | -------- | ------- | ------------------------- |
| `--profile <PROFILE>` | `-p`  | Workspace profile | No       | -       | `TAILOR_PLATFORM_PROFILE` |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

## user

Manage Tailor Platform users.

**Usage**

```
tailor user [command]
```

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

**Commands**

| Command                         | Description                    |
| ------------------------------- | ------------------------------ |
| [`user current`](#user-current) | Show current user.             |
| [`user list`](#user-list)       | List all users.                |
| [`user switch`](#user-switch)   | Set current user.              |
| [`user pat`](#user-pat)         | Manage personal access tokens. |

### user current

Show current user.

**Usage**

```
tailor user current [options]
```

**Options**

| Option                | Alias | Description       | Required | Default | Env                       |
| --------------------- | ----- | ----------------- | -------- | ------- | ------------------------- |
| `--profile <PROFILE>` | `-p`  | Workspace profile | No       | -       | `TAILOR_PLATFORM_PROFILE` |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

### user list

List all users.

**Usage**

```
tailor user list [options]
```

**Options**

| Option                | Alias | Description       | Required | Default | Env                       |
| --------------------- | ----- | ----------------- | -------- | ------- | ------------------------- |
| `--profile <PROFILE>` | `-p`  | Workspace profile | No       | -       | `TAILOR_PLATFORM_PROFILE` |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

### user pat

Manage personal access tokens.

**Usage**

```
tailor user pat [command]
```

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

**Commands**

| Command                               | Description                                           |
| ------------------------------------- | ----------------------------------------------------- |
| [`user pat list`](#user-pat-list)     | List all personal access tokens.                      |
| [`user pat create`](#user-pat-create) | Create a new personal access token.                   |
| [`user pat delete`](#user-pat-delete) | Delete a personal access token.                       |
| [`user pat update`](#user-pat-update) | Update a personal access token (delete and recreate). |

#### user pat create

Create a new personal access token.

**Usage**

```
tailor user pat create [options] <name>
```

**Arguments**

| Argument | Description | Required |
| -------- | ----------- | -------- |
| `name`   | Token name  | Yes      |

**Options**

| Option                | Alias | Description                                 | Required | Default | Env                       |
| --------------------- | ----- | ------------------------------------------- | -------- | ------- | ------------------------- |
| `--write`             | `-W`  | Grant write permission (default: read-only) | No       | `false` | -                         |
| `--profile <PROFILE>` | `-p`  | Workspace profile                           | No       | -       | `TAILOR_PLATFORM_PROFILE` |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

#### user pat delete

Delete a personal access token.

**Usage**

```
tailor user pat delete [options] <name>
```

**Arguments**

| Argument | Description | Required |
| -------- | ----------- | -------- |
| `name`   | Token name  | Yes      |

**Options**

| Option                | Alias | Description       | Required | Default | Env                       |
| --------------------- | ----- | ----------------- | -------- | ------- | ------------------------- |
| `--profile <PROFILE>` | `-p`  | Workspace profile | No       | -       | `TAILOR_PLATFORM_PROFILE` |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

#### user pat list

List all personal access tokens.

**Usage**

```
tailor user pat list [options]
```

**Options**

| Option                | Alias | Description                                              | Required | Default  | Env                       |
| --------------------- | ----- | -------------------------------------------------------- | -------- | -------- | ------------------------- |
| `--order <ORDER>`     | -     | Sort order (asc or desc)                                 | No       | `"desc"` | -                         |
| `--limit <LIMIT>`     | `-l`  | Maximum number of items to return (0 or omit: unlimited) | No       | -        | -                         |
| `--profile <PROFILE>` | `-p`  | Workspace profile                                        | No       | -        | `TAILOR_PLATFORM_PROFILE` |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

#### user pat update

Update a personal access token (delete and recreate).

**Usage**

```
tailor user pat update [options] <name>
```

**Arguments**

| Argument | Description | Required |
| -------- | ----------- | -------- |
| `name`   | Token name  | Yes      |

**Options**

| Option                | Alias | Description                                                | Required | Default | Env                       |
| --------------------- | ----- | ---------------------------------------------------------- | -------- | ------- | ------------------------- |
| `--write`             | `-W`  | Grant write permission (if not specified, keeps read-only) | No       | `false` | -                         |
| `--profile <PROFILE>` | `-p`  | Workspace profile                                          | No       | -       | `TAILOR_PLATFORM_PROFILE` |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

### user switch

Set current user.

**Usage**

```
tailor user switch [options] <user>
```

**Arguments**

| Argument | Description                                  | Required |
| -------- | -------------------------------------------- | -------- |
| `user`   | User email address or machine user client ID | Yes      |

**Options**

| Option                | Alias | Description       | Required | Default | Env                       |
| --------------------- | ----- | ----------------- | -------- | ------- | ------------------------- |
| `--profile <PROFILE>` | `-p`  | Workspace profile | No       | -       | `TAILOR_PLATFORM_PROFILE` |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.
When no subcommand is provided, defaults to `list`.

**Output (default):**

```
┌──────────────┬────────────┬──────────────┬──────────────┐
│ name         │ scopes     │ createdAt    │ lastUsedAt   │
├──────────────┼────────────┼──────────────┼──────────────┤
│ token-name-1 │ read/write │ 8 months ago │ 6 months ago │
│ token-name-2 │ read       │ 8 months ago │ never        │
└──────────────┴────────────┴──────────────┴──────────────┘
```

`lastUsedAt` reads `never` until the token has been used to authenticate, and is
updated at most once per hour.

**Output (`-j, --json`):**

```json
[
  {
    "name": "token-name-1",
    "scopes": ["read", "write"],
    "createdAt": "2026-01-02T03:04:05.000Z",
    "lastUsedAt": "2026-03-04T05:06:07.000Z"
  },
  {
    "name": "token-name-2",
    "scopes": ["read"],
    "createdAt": "2026-01-02T03:04:05.000Z",
    "lastUsedAt": null
  }
]
```

**Output (default):**

```
Personal access token created successfully.

  name: token-name
scopes: read/write
 token: tpp_xxxxxxxxxxxxx

Please save this token in a secure location. You won't be able to see it again.
```

**Output (`-j, --json`):**

```json
{ "name": "token-name", "scopes": ["read", "write"], "token": "eyJhbGc..." }
```

**Output (default):**

```
Personal access token updated successfully.

  name: token-name
scopes: read/write
 token: tpp_xxxxxxxxxxxxx

Please save this token in a secure location. You won't be able to see it again.
```

**Output (`-j, --json`):**

```json
{
  "name": "token-name",
  "scopes": ["read", "write"],
  "token": "tpp_xxxxxxxxxxxxx"
}
```

---

---
url: https://docs.tailor.tech/sdk/cli/workflow.md
---
# Workflow Commands

Commands for managing workflows and workflow executions.

## workflow

Manage workflows and workflow executions.

**Usage**

```
tailor workflow [command]
```

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

**Commands**

| Command                                       | Description                                    |
| --------------------------------------------- | ---------------------------------------------- |
| [`workflow list`](#workflow-list)             | List all workflows in the workspace.           |
| [`workflow get`](#workflow-get)               | Get workflow details.                          |
| [`workflow start`](#workflow-start)           | Start a workflow execution.                    |
| [`workflow wait`](#workflow-wait)             | Wait for a workflow execution.                 |
| [`workflow executions`](#workflow-executions) | List or get workflow executions.               |
| [`workflow resume`](#workflow-resume)         | Resume a failed or pending workflow execution. |

### workflow list

List all workflows in the workspace.

**Usage**

```
tailor workflow list [options]
```

**Options**

| Option                          | Alias | Description                                              | Required | Default  | Env                            |
| ------------------------------- | ----- | -------------------------------------------------------- | -------- | -------- | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID                                             | No       | -        | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>`           | `-p`  | Workspace profile                                        | No       | -        | `TAILOR_PLATFORM_PROFILE`      |
| `--order <ORDER>`               | -     | Sort order (asc or desc)                                 | No       | `"desc"` | -                              |
| `--limit <LIMIT>`               | `-l`  | Maximum number of items to return (0 or omit: unlimited) | No       | -        | -                              |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

### workflow get

Get workflow details.

**Usage**

```
tailor workflow get [options] <name>
```

**Arguments**

| Argument | Description   | Required |
| -------- | ------------- | -------- |
| `name`   | Workflow name | Yes      |

**Options**

| Option                          | Alias | Description       | Required | Default | Env                            |
| ------------------------------- | ----- | ----------------- | -------- | ------- | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID      | No       | -       | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>`           | `-p`  | Workspace profile | No       | -       | `TAILOR_PLATFORM_PROFILE`      |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

### workflow start

Start a workflow execution.

**Usage**

```
tailor workflow start [options] <name>
```

**Arguments**

| Argument | Description   | Required |
| -------- | ------------- | -------- |
| `name`   | Workflow name | Yes      |

**Options**

| Option                          | Alias | Description                                                                 | Required | Default              | Env                                 |
| ------------------------------- | ----- | --------------------------------------------------------------------------- | -------- | -------------------- | ----------------------------------- |
| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID                                                                | No       | -                    | `TAILOR_PLATFORM_WORKSPACE_ID`      |
| `--profile <PROFILE>`           | `-p`  | Workspace profile                                                           | No       | -                    | `TAILOR_PLATFORM_PROFILE`           |
| `--config <CONFIG>`             | `-c`  | Path to Tailor config file                                                  | No       | `"tailor.config.ts"` | `TAILOR_CONFIG_PATH`                |
| `--machine-user <MACHINE_USER>` | `-m`  | Machine user name. Falls back to the active profile's default machine user. | No       | -                    | `TAILOR_PLATFORM_MACHINE_USER_NAME` |
| `--arg <ARG>`                   | `-a`  | Workflow argument (JSON string)                                             | No       | -                    | -                                   |
| `--wait`                        | `-W`  | Wait for execution to complete                                              | No       | `false`              | -                                   |
| `--interval <INTERVAL>`         | `-i`  | Polling interval when waiting (e.g., '3s', '500ms', '1m')                   | No       | `"3s"`               | -                                   |
| `--timeout <TIMEOUT>`           | `-t`  | Maximum time to wait (e.g., '30s', '10m')                                   | No       | `"10m"`              | -                                   |
| `--until <UNTIL>`               | `-u`  | Wait target (success, suspended, terminal)                                  | No       | `"terminal"`         | -                                   |
| `--logs`                        | `-l`  | Display job execution logs after completion                                 | No       | `false`              | -                                   |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

**Usage Examples:**

```bash
# Start a workflow
tailor workflow start my-workflow -m admin-machine-user

# Start with argument
tailor workflow start my-workflow -m admin -a '{"userId": "123"}'

# Start and wait for completion
tailor workflow start my-workflow -m admin -W
```

## workflow wait

Wait for a workflow execution.

**Usage**

```
tailor workflow wait [options] <execution-id>
```

**Arguments**

| Argument       | Description  | Required |
| -------------- | ------------ | -------- |
| `execution-id` | Execution ID | Yes      |

**Options**

| Option                          | Alias | Description                                               | Required | Default      | Env                            |
| ------------------------------- | ----- | --------------------------------------------------------- | -------- | ------------ | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID                                              | No       | -            | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>`           | `-p`  | Workspace profile                                         | No       | -            | `TAILOR_PLATFORM_PROFILE`      |
| `--interval <INTERVAL>`         | `-i`  | Polling interval when waiting (e.g., '3s', '500ms', '1m') | No       | `"3s"`       | -                              |
| `--timeout <TIMEOUT>`           | `-t`  | Maximum time to wait (e.g., '30s', '10m')                 | No       | `"10m"`      | -                              |
| `--until <UNTIL>`               | `-u`  | Wait target (success, suspended, terminal)                | No       | `"terminal"` | -                              |
| `--logs`                        | `-l`  | Display job execution logs after completion               | No       | `false`      | -                              |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

**Examples**

**Wait for workflow success**

```bash
$ tailor workflow wait execution-id --until success --timeout 10m --json
```

**Wait for a workflow wait point**

```bash
$ tailor workflow wait execution-id --until suspended --timeout 6m --logs --json
```

**Wait for success, failure, or suspension**

```bash
$ tailor workflow wait execution-id --until terminal
```

**Shell automation**

Capture the execution ID from `workflow start` and wait for the same run from a
separate command:

```bash
execution_id="$(
  tailor workflow start order-workflow --json | jq -r '.executionId'
)"

tailor workflow wait "$execution_id" \
  --until success \
  --timeout 10m \
  --interval 5s \
  --json
```

Wait until a workflow reaches a wait point, such as an approval step:

```bash
tailor workflow wait "$execution_id" \
  --until suspended \
  --timeout 6m \
  --logs \
  --json
```

**Programmatic API**

Use `waitWorkflowExecution` when a script already has an execution ID and needs
the same waiter behavior as the CLI:

```ts
import { waitWorkflowExecution } from "@tailor-platform/sdk/cli";

const executionId = process.env.EXECUTION_ID;

if (!executionId) {
  throw new Error("EXECUTION_ID is required");
}

const result = await waitWorkflowExecution({
  executionId,
  until: "success",
  timeout: 10 * 60 * 1000,
  interval: 5000,
});

if (result.timedOut) {
  throw new Error(`Workflow ${result.id} timed out at ${result.status}`);
}
```

### workflow executions

List or get workflow executions.

**Usage**

```
tailor workflow executions [options] [execution-id]
```

**Arguments**

| Argument       | Description                               | Required |
| -------------- | ----------------------------------------- | -------- |
| `execution-id` | Execution ID (if provided, shows details) | No       |

**Options**

| Option                            | Alias | Description                                               | Required | Default      | Env                            |
| --------------------------------- | ----- | --------------------------------------------------------- | -------- | ------------ | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>`   | `-w`  | Workspace ID                                              | No       | -            | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>`             | `-p`  | Workspace profile                                         | No       | -            | `TAILOR_PLATFORM_PROFILE`      |
| `--order <ORDER>`                 | -     | Sort order (asc or desc)                                  | No       | `"desc"`     | -                              |
| `--limit <LIMIT>`                 | `-l`  | Maximum number of items to return (0: unlimited)          | No       | `50`         | -                              |
| `--workflow-name <WORKFLOW_NAME>` | `-n`  | Filter by workflow name (list mode only)                  | No       | -            | -                              |
| `--status <STATUS>`               | `-s`  | Filter by status (list mode only)                         | No       | -            | -                              |
| `--wait`                          | `-W`  | Wait for execution to complete                            | No       | `false`      | -                              |
| `--interval <INTERVAL>`           | `-i`  | Polling interval when waiting (e.g., '3s', '500ms', '1m') | No       | `"3s"`       | -                              |
| `--timeout <TIMEOUT>`             | `-t`  | Maximum time to wait (e.g., '30s', '10m')                 | No       | `"10m"`      | -                              |
| `--until <UNTIL>`                 | `-u`  | Wait target (success, suspended, terminal)                | No       | `"terminal"` | -                              |
| `--logs`                          | -     | Display job execution logs (detail mode only)             | No       | `false`      | -                              |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

**Usage Examples:**

```bash
# List all executions
tailor workflow executions

# Filter by workflow name
tailor workflow executions -n my-workflow

# Filter by status
tailor workflow executions -s RUNNING

# Get execution details
tailor workflow executions <execution-id>

# Get execution details with logs
tailor workflow executions <execution-id> --logs

# Wait for execution to complete
tailor workflow executions <execution-id> -W
```

## workflow resume

Resume a failed or pending workflow execution.

**Usage**

```
tailor workflow resume [options] <execution-id>
```

**Arguments**

| Argument       | Description         | Required |
| -------------- | ------------------- | -------- |
| `execution-id` | Failed execution ID | Yes      |

**Options**

| Option                          | Alias | Description                                               | Required | Default      | Env                            |
| ------------------------------- | ----- | --------------------------------------------------------- | -------- | ------------ | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID                                              | No       | -            | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>`           | `-p`  | Workspace profile                                         | No       | -            | `TAILOR_PLATFORM_PROFILE`      |
| `--wait`                        | `-W`  | Wait for execution to complete                            | No       | `false`      | -                              |
| `--interval <INTERVAL>`         | `-i`  | Polling interval when waiting (e.g., '3s', '500ms', '1m') | No       | `"3s"`       | -                              |
| `--timeout <TIMEOUT>`           | `-t`  | Maximum time to wait (e.g., '30s', '10m')                 | No       | `"10m"`      | -                              |
| `--until <UNTIL>`               | `-u`  | Wait target (success, suspended, terminal)                | No       | `"terminal"` | -                              |
| `--logs`                        | `-l`  | Display job execution logs after completion               | No       | `false`      | -                              |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

---

---
url: https://docs.tailor.tech/sdk/cli/workspace.md
---
# Workspace Commands

Commands for managing workspaces and profiles.

## workspace

Manage Tailor Platform workspaces.

**Usage**

```
tailor workspace [command]
```

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

**Commands**

| Command                                   | Description                                 |
| ----------------------------------------- | ------------------------------------------- |
| [`workspace app`](#workspace-app)         | Manage workspace applications               |
| [`workspace create`](#workspace-create)   | Create a new Tailor Platform workspace.     |
| [`workspace delete`](#workspace-delete)   | Delete a Tailor Platform workspace.         |
| [`workspace get`](#workspace-get)         | Show detailed information about a workspace |
| [`workspace list`](#workspace-list)       | List all Tailor Platform workspaces.        |
| [`workspace restore`](#workspace-restore) | Restore a deleted workspace                 |
| [`workspace user`](#workspace-user)       | Manage workspace users                      |

### workspace app

Manage workspace applications

**Usage**

```
tailor workspace app [command]
```

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

**Commands**

| Command                                         | Description                      |
| ----------------------------------------------- | -------------------------------- |
| [`workspace app health`](#workspace-app-health) | Check application schema health  |
| [`workspace app list`](#workspace-app-list)     | List applications in a workspace |

#### workspace app health

Check application schema health

**Usage**

```
tailor workspace app health [options]
```

**Options**

| Option                          | Alias | Description       | Required | Default | Env                            |
| ------------------------------- | ----- | ----------------- | -------- | ------- | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID      | No       | -       | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>`           | `-p`  | Workspace profile | No       | -       | `TAILOR_PLATFORM_PROFILE`      |
| `--name <NAME>`                 | `-n`  | Application name  | Yes      | -       | -                              |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

#### workspace app list

List applications in a workspace

**Usage**

```
tailor workspace app list [options]
```

**Options**

| Option                          | Alias | Description                                              | Required | Default  | Env                            |
| ------------------------------- | ----- | -------------------------------------------------------- | -------- | -------- | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID                                             | No       | -        | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>`           | `-p`  | Workspace profile                                        | No       | -        | `TAILOR_PLATFORM_PROFILE`      |
| `--order <ORDER>`               | -     | Sort order (asc or desc)                                 | No       | `"desc"` | -                              |
| `--limit <LIMIT>`               | `-l`  | Maximum number of items to return (0 or omit: unlimited) | No       | -        | -                              |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

### workspace create

Create a new Tailor Platform workspace.

**Usage**

```
tailor workspace create [options]
```

**Options**

| Option                                | Alias | Description                                                                                                 | Required | Default   | Env                               |
| ------------------------------------- | ----- | ----------------------------------------------------------------------------------------------------------- | -------- | --------- | --------------------------------- |
| `--name <NAME>`                       | `-n`  | Workspace name                                                                                              | Yes      | -         | -                                 |
| `--region <REGION>`                   | `-r`  | Workspace region (us-west, asia-northeast)                                                                  | Yes      | -         | -                                 |
| `--delete-protection`                 | `-d`  | Enable delete protection                                                                                    | No       | `false`   | -                                 |
| `--organization-id <ORGANIZATION_ID>` | `-o`  | Organization ID to workspace associate with                                                                 | No       | -         | `TAILOR_PLATFORM_ORGANIZATION_ID` |
| `--folder-id <FOLDER_ID>`             | `-f`  | Folder ID to workspace associate with                                                                       | No       | -         | `TAILOR_PLATFORM_FOLDER_ID`       |
| `--profile-name <PROFILE_NAME>`       | `-p`  | Profile name to create                                                                                      | No       | -         | -                                 |
| `--profile <PROFILE>`                 | -     | Workspace profile used for authentication and Platform selection                                            | No       | -         | `TAILOR_PLATFORM_PROFILE`         |
| `--profile-user <PROFILE_USER>`       | -     | User email address or machine user client ID for the profile (defaults to current user)                     | No       | -         | -                                 |
| `--permission <PERMISSION>`           | -     | Profile permission (requires --profile-name). 'read' blocks all write commands while the profile is active. | No       | `"write"` | -                                 |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

### workspace delete

Delete a Tailor Platform workspace.

**Usage**

```
tailor workspace delete [options]
```

**Options**

| Option                          | Alias | Description               | Required | Default |
| ------------------------------- | ----- | ------------------------- | -------- | ------- |
| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID              | Yes      | -       |
| `--yes`                         | `-y`  | Skip confirmation prompts | No       | `false` |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

### workspace get

Show detailed information about a workspace

**Usage**

```
tailor workspace get [options]
```

**Options**

| Option                          | Alias | Description       | Required | Default | Env                            |
| ------------------------------- | ----- | ----------------- | -------- | ------- | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID      | No       | -       | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>`           | `-p`  | Workspace profile | No       | -       | `TAILOR_PLATFORM_PROFILE`      |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

### workspace list

List all Tailor Platform workspaces.

**Usage**

```
tailor workspace list [options]
```

**Options**

| Option                | Alias | Description                                                      | Required | Default  | Env                       |
| --------------------- | ----- | ---------------------------------------------------------------- | -------- | -------- | ------------------------- |
| `--order <ORDER>`     | -     | Sort order (asc or desc)                                         | No       | `"desc"` | -                         |
| `--limit <LIMIT>`     | `-l`  | Maximum number of items to return (0 or omit: unlimited)         | No       | -        | -                         |
| `--profile <PROFILE>` | -     | Workspace profile used for authentication and Platform selection | No       | -        | `TAILOR_PLATFORM_PROFILE` |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

### workspace restore

Restore a deleted workspace

**Usage**

```
tailor workspace restore [options]
```

**Options**

| Option                          | Alias | Description               | Required | Default |
| ------------------------------- | ----- | ------------------------- | -------- | ------- |
| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID              | Yes      | -       |
| `--yes`                         | `-y`  | Skip confirmation prompts | No       | `false` |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

### workspace user

Manage workspace users

**Usage**

```
tailor workspace user [command]
```

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

**Commands**

| Command                                           | Description                         |
| ------------------------------------------------- | ----------------------------------- |
| [`workspace user invite`](#workspace-user-invite) | Invite a user to a workspace        |
| [`workspace user list`](#workspace-user-list)     | List users in a workspace           |
| [`workspace user remove`](#workspace-user-remove) | Remove a user from a workspace      |
| [`workspace user update`](#workspace-user-update) | Update a user's role in a workspace |

#### workspace user invite

Invite a user to a workspace

**Usage**

```
tailor workspace user invite [options]
```

**Options**

| Option                          | Alias | Description                            | Required | Default | Env                            |
| ------------------------------- | ----- | -------------------------------------- | -------- | ------- | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID                           | No       | -       | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>`           | `-p`  | Workspace profile                      | No       | -       | `TAILOR_PLATFORM_PROFILE`      |
| `--email <EMAIL>`               | -     | Email address of the user to invite    | Yes      | -       | -                              |
| `--role <ROLE>`                 | `-r`  | Role to assign (admin, editor, viewer) | Yes      | -       | -                              |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

#### workspace user list

List users in a workspace

**Usage**

```
tailor workspace user list [options]
```

**Options**

| Option                          | Alias | Description                                              | Required | Default  | Env                            |
| ------------------------------- | ----- | -------------------------------------------------------- | -------- | -------- | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID                                             | No       | -        | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>`           | `-p`  | Workspace profile                                        | No       | -        | `TAILOR_PLATFORM_PROFILE`      |
| `--order <ORDER>`               | -     | Sort order (asc or desc)                                 | No       | `"desc"` | -                              |
| `--limit <LIMIT>`               | `-l`  | Maximum number of items to return (0 or omit: unlimited) | No       | -        | -                              |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

#### workspace user remove

Remove a user from a workspace

**Usage**

```
tailor workspace user remove [options]
```

**Options**

| Option                          | Alias | Description                         | Required | Default | Env                            |
| ------------------------------- | ----- | ----------------------------------- | -------- | ------- | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID                        | No       | -       | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>`           | `-p`  | Workspace profile                   | No       | -       | `TAILOR_PLATFORM_PROFILE`      |
| `--email <EMAIL>`               | -     | Email address of the user to remove | Yes      | -       | -                              |
| `--yes`                         | `-y`  | Skip confirmation prompts           | No       | `false` | -                              |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

#### workspace user update

Update a user's role in a workspace

**Usage**

```
tailor workspace user update [options]
```

**Options**

| Option                          | Alias | Description                                | Required | Default | Env                            |
| ------------------------------- | ----- | ------------------------------------------ | -------- | ------- | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID                               | No       | -       | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>`           | `-p`  | Workspace profile                          | No       | -       | `TAILOR_PLATFORM_PROFILE`      |
| `--email <EMAIL>`               | -     | Email address of the user to update        | Yes      | -       | -                              |
| `--role <ROLE>`                 | `-r`  | New role to assign (admin, editor, viewer) | Yes      | -       | -                              |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

## profile

Manage workspace profiles (user + workspace combinations).

**Usage**

```
tailor profile [command]
```

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

**Commands**

| Command                             | Description                |
| ----------------------------------- | -------------------------- |
| [`profile create`](#profile-create) | Create a new profile.      |
| [`profile delete`](#profile-delete) | Delete a profile.          |
| [`profile list`](#profile-list)     | List all profiles.         |
| [`profile update`](#profile-update) | Update profile properties. |

### profile create

Create a new profile.

**Usage**

```
tailor profile create [options] <name>
```

**Arguments**

| Argument | Description  | Required |
| -------- | ------------ | -------- |
| `name`   | Profile name | Yes      |

**Options**

| Option                                            | Alias | Description                                                                                                                            | Required | Default   | Env                                |
| ------------------------------------------------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------- | -------- | --------- | ---------------------------------- |
| `--user <USER>`                                   | `-u`  | User email address or machine user client ID                                                                                           | Yes      | -         | -                                  |
| `--workspace-id <WORKSPACE_ID>`                   | `-w`  | Workspace ID                                                                                                                           | Yes      | -         | -                                  |
| `--permission <PERMISSION>`                       | -     | Profile permission. 'read' blocks all write commands while the profile is active.                                                      | No       | `"write"` | -                                  |
| `--machine-user <MACHINE_USER>`                   | `-m`  | Default machine user name for application-data commands (query, workflow start, function run, machineuser token).                      | No       | -         | -                                  |
| `--machine-user-override <MACHINE_USER_OVERRIDE>` | -     | Whether the command line or TAILOR\_PLATFORM\_MACHINE\_USER\_NAME may override the profile's machine user. 'deny' requires --machine-user. | No       | -         | -                                  |
| `--platform-url <PLATFORM_URL>`                   | -     | Platform API base URL for this profile.                                                                                                | No       | -         | `TAILOR_PLATFORM_URL`              |
| `--oauth2-client-id <OAUTH2_CLIENT_ID>`           | -     | OAuth2 client ID for logging in to this profile's platform.                                                                            | No       | -         | `TAILOR_PLATFORM_OAUTH2_CLIENT_ID` |
| `--console-url <CONSOLE_URL>`                     | -     | Console base URL for this profile.                                                                                                     | No       | -         | `TAILOR_PLATFORM_CONSOLE_URL`      |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

### profile delete

Delete a profile.

**Usage**

```
tailor profile delete <name>
```

**Arguments**

| Argument | Description  | Required |
| -------- | ------------ | -------- |
| `name`   | Profile name | Yes      |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

### profile list

List all profiles.

**Usage**

```
tailor profile list
```

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

### profile update

Update profile properties.

**Usage**

```
tailor profile update [options] <name>
```

**Arguments**

| Argument | Description  | Required |
| -------- | ------------ | -------- |
| `name`   | Profile name | Yes      |

**Options**

| Option                                            | Alias | Description                                                                                                                                                           | Required | Default |
| ------------------------------------------------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- |
| `--user <USER>`                                   | `-u`  | New user email address or machine user client ID                                                                                                                      | No       | -       |
| `--workspace-id <WORKSPACE_ID>`                   | `-w`  | New workspace ID                                                                                                                                                      | No       | -       |
| `--permission <PERMISSION>`                       | -     | Profile permission. 'read' blocks all write commands; 'write' lifts the restriction.                                                                                  | No       | -       |
| `--machine-user <MACHINE_USER>`                   | `-m`  | Default machine user name for application-data commands (query, workflow start, function run, machineuser token). Pass an empty string to clear.                      | No       | -       |
| `--machine-user-override <MACHINE_USER_OVERRIDE>` | -     | Whether the command line or TAILOR\_PLATFORM\_MACHINE\_USER\_NAME may override the profile's machine user. 'deny' requires --machine-user; 'allow' lifts the restriction. | No       | -       |
| `--platform-url <PLATFORM_URL>`                   | -     | Platform API base URL for this profile. Pass an empty string to clear.                                                                                                | No       | -       |
| `--oauth2-client-id <OAUTH2_CLIENT_ID>`           | -     | OAuth2 client ID for logging in to this profile's platform. Pass an empty string to clear.                                                                            | No       | -       |
| `--console-url <CONSOLE_URL>`                     | -     | Console base URL for this profile. Pass an empty string to clear.                                                                                                     | No       | -       |

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

---

---
url: https://docs.tailor.tech/sdk/migration/v2.md
---
# Migrating to v2

Run the codemods, then finish anything reported as not migrated automatically:

```sh
npx @tailor-platform/sdk-codemod --from <current-version> --to <target-version>
```

## Type-only imports → `import type`

**Migration:** Manual

The v2 CLI runs TypeScript by stripping types from each file in isolation,
with no cross-file type information. A plain (non-`type`) import of a
type-only export therefore survives stripping and fails when the module
loads:

```
SyntaxError: The requested module './types.ts' does not provide an export named 'Row'
```

`tailor generate` / `tailor deploy` stop at this error before doing any work.
Import types with `import type` (or the inline `type` modifier), and
re-export them with `export type`, in every module the CLI loads. Generated
Kysely types (`DB`, `Insertable`, `Selectable`, table row types) are almost
entirely type-only, so v1 projects typically hit this in many files at once.
Set `"verbatimModuleSyntax": true` in tsconfig.json to catch every violation
at typecheck; projects scaffolded by v2 `tailor init` enable it by default.

Before:

```ts
import { DB, getDB } from "./generated/db";
```

After:

```ts
import { type DB, getDB } from "./generated/db";
```

```text
In Tailor SDK v2 the CLI loads TypeScript by stripping types from each file
in isolation, so type-only exports do not exist at runtime and plain imports
of them fail to load with "does not provide an export named '<name>'".
Migrate the project so every type-only import and re-export is marked:

1. Add `"verbatimModuleSyntax": true` to compilerOptions in tsconfig.json.
2. Run `tsc --noEmit` and fix every reported violation: add the `type`
   modifier to type-only named imports (`import type { Row }` or
   `import { type Row, marker }`) and change type-only re-exports to
   `export type { ... }`.

Only add `type` modifiers; do not reorder, remove, or otherwise change
imports that are used as values.
```

## defineGenerators → definePlugins

**Migration:** Partially automatic

Migrate defineGenerators() tuple syntax to definePlugins() with explicit plugin imports

Before:

```ts
import { defineGenerators } from "@tailor-platform/sdk";

export const generators = defineGenerators(
  ["@tailor-platform/kysely-type", { distPath: "db.ts" }],
);
```

After:

```ts
import { definePlugins } from "@tailor-platform/sdk";
import { kyselyTypePlugin } from "@tailor-platform/sdk/plugin/kysely-type";

export const generators = definePlugins(kyselyTypePlugin({ distPath: "db.ts" }));
```

```text
defineGenerators() is replaced by definePlugins() in v2. The codemod rewrites the
known plugin tuples (kysely-type, enum-constants, file-utils, seed). For any
remaining defineGenerators([...]) the codemod left in place — a plugin it does not
know, or a non-tuple/spread form — convert it to definePlugins(pluginFn(config)),
importing the matching plugin from its @tailor-platform/sdk/plugin/<name> subpath.
```

## @tailor-platform/sdk/cli plugin imports → dedicated subpaths

**Migration:** Automatic

Rewrite deprecated plugin re-export imports (kyselyTypePlugin, enumConstantsPlugin, fileUtilsPlugin, seedPlugin) from `@tailor-platform/sdk/cli` to their dedicated plugin subpaths

Before:

```ts
import { kyselyTypePlugin } from "@tailor-platform/sdk/cli";
```

After:

```ts
import { kyselyTypePlugin } from "@tailor-platform/sdk/plugin/kysely-type";
```

## function test-run --arg input unwrap

**Migration:** Automatic

Strip the deprecated {input: ...} wrapper from `tailor function test-run --arg` JSON in scripts and docs

Before:

```sh
tailor function test-run resolvers/add.ts --arg '{"input":{"a":1}}'
```

After:

```sh
tailor function test-run resolvers/add.ts --arg '{"a":1}'
```

## tailor-sdk-skills → tailor skills add

**Migration:** Partially automatic

Replace deprecated `tailor-sdk-skills` invocations with `tailor skills add`

Before:

```sh
npx tailor-sdk-skills
```

After:

```sh
npx @tailor-platform/sdk skills add
```

```text
The standalone tailor-sdk-skills binary is removed in v2; call the skills add
subcommand on the main tailor CLI instead. Replace any remaining
tailor-sdk-skills invocations the codemod did not rewrite with
`tailor skills add`, or `npx @tailor-platform/sdk skills add` when the
invocation runs through a package runner (npx, bunx, pnpm/yarn dlx, npm exec)
— those resolve a package name, and `npx tailor` reaches an unrelated
`tailor` package on npm.
```

## Unify TailorUser/TailorActor/TailorActorType/TailorInvoker → TailorPrincipal

**Migration:** Partially automatic

Rename TailorUser/TailorActor/TailorActorType/TailorInvoker to TailorPrincipal, drop unauthenticatedTailorUser, rename resolver body `user` to `caller`, and rename TailorDB callback `user` to `invoker`

Type references unify under `TailorPrincipal`:

Before:

```ts
import type { TailorUser } from "@tailor-platform/sdk";
```

After:

```ts
import type { TailorPrincipal } from "@tailor-platform/sdk";
```

The resolver body `user` becomes `caller`:

Before:

```ts
body: ({ input, user }) => user.id,
```

After:

```ts
body: ({ input, caller }) => caller.id,
```

```text
Finish the cases the codemod left for manual migration:
- Rename user -> caller in resolver bodies the codemod skipped because a `caller`
  binding already exists or renaming would shadow/collide with another value.
- Replace member-access on the removed unauthenticatedTailorUser (e.g.
  unauthenticatedTailorUser.id); the codemod only replaced standalone references
  with null and left member access to surface a type error.
- Review helper adapters that still accept or read `context.user`; v2 resolver
  context uses nullable `caller` and `invoker`, so project-specific helper
  semantics for anonymous callers and command invokers must be chosen explicitly.
- Review `caller?.` values passed to APIs that require non-null values. If the
  resolver requires authentication, throw or otherwise narrow before the call;
  if anonymous callers are allowed, keep the nullable flow explicit.
Use TailorPrincipal for the unified user/actor/invoker type.
```

## AttributeMap → Attributes

**Migration:** Partially automatic

Rename auth attribute module augmentation and related SDK type names from `AttributeMap` to `Attributes`

Module augmentation uses `Attributes`:

Before:

```ts
declare module "@tailor-platform/sdk" {
  interface AttributeMap {
    role: string;
  }
}
```

After:

```ts
declare module "@tailor-platform/sdk" {
  interface Attributes {
    role: string;
  }
}
```

```text
In Tailor SDK v2, the auth attribute type API is renamed from `AttributeMap`
to `Attributes`; related SDK types are renamed to `UserAttributes` and
`InferredAttributes`. The codemod rewrites SDK imports, re-exports,
namespace-qualified references, import() type references, and module
augmentations. Review any remaining matches manually and leave unrelated
local names or deploy/proto wire field names unchanged.
```

## tailor-sdk apply → tailor-sdk deploy

**Migration:** Automatic

Rewrite `tailor-sdk apply` invocations in package.json scripts, shell scripts, CI configs, and docs to the canonical v2 `tailor-sdk deploy` command

Before:

```sh
tailor-sdk apply --profile prod
```

After:

```sh
tailor-sdk deploy --profile prod
```

## v2 CLI rename

**Migration:** Partially automatic

Rewrite `tailor-sdk crash-report` to `tailor-sdk crashreport` and `--machineuser` to `--machine-user` across package.json scripts, shell scripts, CI configs, and docs

Before:

```sh
tailor-sdk crash-report list
tailor-sdk login --machineuser
```

After:

```sh
tailor-sdk crashreport list
tailor-sdk login --machine-user
```

```text
Apply the v2 CLI renames the codemod did not reach (only `tailor-sdk`-prefixed
invocations are rewritten): `tailor-sdk crash-report` -> `tailor-sdk crashreport`
and the `--machineuser` option -> `--machine-user`. Leave unrelated commands that
happen to use `--machineuser` alone.
```

## SDK environment variable rename

**Migration:** Partially automatic

Rewrite unambiguous removed SDK environment variable names to their v2 `TAILOR_*` names and flag generic names for manual review

Before:

```sh
TAILOR_PLATFORM_SDK_BUILD_ONLY=true tailor-sdk deploy
```

After:

```sh
TAILOR_DEPLOY_BUILD_ONLY=true tailor-sdk deploy
```

Before:

```ts
const token = process.env.TAILOR_TOKEN;
```

After:

```ts
const token = process.env.TAILOR_PLATFORM_TOKEN;
```

```text
Review any remaining removed SDK environment variable names after the codemod
runs. The codemod intentionally leaves generic names such as `LOG_LEVEL`,
`PLATFORM_URL`, and `PLATFORM_OAUTH2_CLIENT_ID` for manual review because
they can configure non-SDK tools. Replace only actual SDK usages with their
v2 names. If a remaining match is an unrelated local identifier, fixture
label, or historical documentation that intentionally does not configure the
SDK, leave it unchanged.
```

## auth.invoker("name") → "name"

**Migration:** Partially automatic

Replace statically identified SDK `auth.invoker("name")` option values with the bare `"name"` string while preserving the `authInvoker` key for SDK versions before the option rename.

Before:

```ts
createResolver({ authInvoker: auth.invoker("manager") });
```

After:

```ts
createResolver({ authInvoker: "manager" });
```

```text
In Tailor SDK v2 the auth.invoker() helper is removed; an invoker is now the
machine user name passed directly as a string. The codemod already rewrote the
statically identified SDK option form authInvoker: auth.invoker("name") to authInvoker: "name". These files still contain
auth.invoker(...) calls that need manual review.

For each remaining auth.invoker(<expr>) call:
1. Replace the whole call with <expr> only where the target option expects a
   machine user name string; platform/runtime authInvoker payloads still expect
   the object form.
2. Keep the authInvoker key when targeting SDK versions before the invoker
   option rename; later v2 targets run a separate codemod for that key rename.
3. After removing every auth.invoker usage in a file, delete the now-unused auth
   import (keeping it pulls Node-only config modules into runtime bundles); leave
   the import if auth is still referenced elsewhere.

Do not change behavior beyond the auth.invoker() removal.
```

## auth.invoker("name") → invoker: "name"

**Migration:** Partially automatic

Rename statically identified SDK `authInvoker` options to `invoker`, replace `auth.invoker("name")` there with the bare `"name"` string, and drop the `auth` import when no other reference remains. Ambiguous workflow `.start()` calls are left for manual review. The `auth.invoker()` helper is removed in v2 because importing `auth` from `tailor.config.ts` into runtime files pulls Node-only modules into the bundle.

Before:

```ts
createResolver({ invoker: auth.invoker("manager") });
```

After:

```ts
createResolver({ invoker: "manager" });
```

```text
In Tailor SDK v2 the auth.invoker() helper is removed; an invoker is now the
machine user name passed directly as a string. The codemod already rewrote the
statically identified SDK option form authInvoker: auth.invoker("name") to invoker: "name" and renamed supported authInvoker option keys. These files still contain
auth.invoker(...) calls or authInvoker keys that need manual review.

For each remaining auth.invoker(<expr>) call:
1. Replace the whole call with <expr> only where the target option expects a
   machine user name string; platform/runtime authInvoker payloads still expect
   the object form.
2. Rename remaining authInvoker option keys to invoker only for SDK resolver,
   executor, workflow.start(), or startWorkflow() options. Keep platform/runtime
   payload keys such as tailor.workflow.startWorkflow(..., { authInvoker: ... }).
3. After removing every auth.invoker usage in a file, delete the now-unused auth
   import (keeping it pulls Node-only config modules into runtime bundles); leave
   the import if auth is still referenced elsewhere.

Do not change behavior beyond the SDK option rename and auth.invoker() removal.
```

## auth.getConnectionToken() → runtime authconnection

**Migration:** Partially automatic

The deprecated `auth.getConnectionToken()` helper returned by `defineAuth()` is removed in v2. Use `authconnection.getConnectionToken(...)` from `@tailor-platform/sdk/runtime` in resolvers, executors, and workflows instead.

Before:

```ts
import { auth } from "../tailor.config";

const token = await auth.getConnectionToken("google");
```

After:

```ts
import { authconnection } from "@tailor-platform/sdk/runtime";

const token = await authconnection.getConnectionToken("google");
```

```text
In Tailor SDK v2 the auth.getConnectionToken() helper returned by defineAuth()
is removed. Runtime code should call authconnection.getConnectionToken(...) from
@tailor-platform/sdk/runtime instead of importing auth from tailor.config.ts.

For each getConnectionToken usage where <receiver> is a defineAuth() result
imported from tailor.config.ts:
1. Replace <receiver>.getConnectionToken(<expr>) calls with
   authconnection.getConnectionToken(<expr>).
2. Update non-call references, including <receiver>.getConnectionToken,
   <receiver>["getConnectionToken"], and destructuring from <receiver>, to
   reference authconnection instead.
3. Add or reuse `import { authconnection } from "@tailor-platform/sdk/runtime"`.
4. Remove the auth import from tailor.config.ts only when no other auth reference
   remains in the file.

Leave usages unchanged when the receiver is already the runtime authconnection
wrapper or global tailor.authconnection.
```

## Runtime subpath imports use namespace objects

**Migration:** Partially automatic

Rewrite `@tailor-platform/sdk/runtime/*` namespace-star and flat value imports to self-named namespace imports, and aggregate `file.deleteFile` calls to `file.delete`. `TailorContextAPI` and `TailorWorkflowAPI` now describe SDK wrappers; direct platform globals use `PlatformContextAPI` and `PlatformWorkflowAPI`.

Before:

```ts
import * as iconv from "@tailor-platform/sdk/runtime/iconv";
iconv.convert(value, "UTF-8", "Shift_JIS");
```

After:

```ts
import { iconv } from "@tailor-platform/sdk/runtime/iconv";
iconv.convert(value, "UTF-8", "Shift_JIS");
```

Before:

```ts
import { get } from "@tailor-platform/sdk/runtime/aigateway";
const gateway = await get("main");
```

After:

```ts
import { aigateway } from "@tailor-platform/sdk/runtime/aigateway";
const gateway = await aigateway.get("main");
```

Before:

```ts
import { file } from "@tailor-platform/sdk/runtime";
await file.deleteFile("ns", "Doc", "blob", "record-id");
```

After:

```ts
import { file } from "@tailor-platform/sdk/runtime";
await file.delete("ns", "Doc", "blob", "record-id");
```

```text
In Tailor SDK v2, runtime subpath modules export only a self-named namespace
object (for example, `iconv` from `@tailor-platform/sdk/runtime/iconv`).
Default and flat value imports such as
`import { get } from "@tailor-platform/sdk/runtime/aigateway"` are removed.
The codemod rewrites straightforward namespace-star imports and flat named value
imports. It also rewrites direct `file.deleteFile` calls on the aggregate runtime
namespace to `file.delete`. Destructured aggregate `deleteFile` references require
manual migration. Review any remaining runtime imports manually, especially when
a local binding or nested scope shadows an imported value, or when
type-position namespace member references need explicit top-level type imports.
For direct platform globals, replace `TailorContextAPI` and `TailorWorkflowAPI`
type references with `PlatformContextAPI` and `PlatformWorkflowAPI` respectively.
```

## Tailordb → tailordb (lowercase ambient namespace)

**Migration:** Partially automatic

Rewrite references to the removed capital-cased `Tailordb` ambient namespace (`Tailordb.QueryResult`, `Tailordb.CommandType`, `Tailordb.Client`, `typeof Tailordb.Client`) to the lowercase `tailordb.*` namespace exposed by `@tailor-platform/sdk/runtime/globals`. Because v2 no longer activates ambient declarations automatically, each file that contains `tailordb.*` references after the rewrite must also add `import "@tailor-platform/sdk/runtime/globals"`.

Before:

```ts
const command: Tailordb.CommandType = "SELECT";
```

After:

```ts
import "@tailor-platform/sdk/runtime/globals";
const command: tailordb.CommandType = "SELECT";
```

```text
The capital-cased Tailordb ambient namespace is removed in v2; use the lowercase
tailordb.* namespace from @tailor-platform/sdk/runtime/globals. The codemod rewrites
the known members (QueryResult, CommandType, Client). Rewrite any other remaining
Tailordb.* reference to its tailordb.* equivalent (and confirm the member still
exists on the lowercase namespace).
Also add `import "@tailor-platform/sdk/runtime/globals"` at the top of each file
that contains any tailordb.* type reference — v2 no longer activates ambient
declarations automatically on SDK import.
```

## db.type() → db.table()

**Migration:** Partially automatic

Rename TailorDB schema builder calls from `db.type()` to `db.table()`. TailorDB schema definitions now use table terminology in SDK projects.

Before:

```ts
import { db } from "@tailor-platform/sdk";

export const user = db.type("User", {
  name: db.string(),
});
```

After:

```ts
import { db } from "@tailor-platform/sdk";

export const user = db.table("User", {
  name: db.string(),
});
```

```text
In Tailor SDK v2, TailorDB schema definitions use db.table(...) instead of
db.type(...). The codemod rewrites member accesses on db imported from
@tailor-platform/sdk, including aliases such as `import { db as schema }`.
It flags destructured builder aliases such as `const { type } = db` and
local builder aliases such as `const schema = db`, `schema = db`, or
`function make(schema = db) { ... }` for manual review because the local
alias may require call-site renaming.
Review any remaining db.type references and rename SDK TailorDB schema builder
calls to db.table. Leave unrelated local objects with a .type() method unchanged.
```

## TailorDB forward relation names derive from field names

**Migration:** Partially automatic

Review TailorDB relations that omit `toward.as`. Their forward GraphQL field names now derive from the relation field name with a trailing `ID`, `Id`, or `id` removed, instead of from the target table name.

Preserve the v1 GraphQL field name by making it explicit:

Before:

```ts
ownerId: db.uuid().relation({
  type: "n-1",
  toward: { type: user },
}),
```

After:

```ts
ownerId: db.uuid().relation({
  type: "n-1",
  toward: { table: user, as: "user" },
}),
```

```text
Tailor SDK v2 derives a default forward GraphQL relation name from the source
field name by removing a trailing ID, Id, or id. V1 derived it from the target
table name. Review each reported non-self relation that omits toward.as.

If consumers must keep using the v1 GraphQL field name, inspect the v1 schema and
copy that exact field name into toward.as. Otherwise, update GraphQL operations
and consumer code to use the new field-based name. No change is needed when the old
and new names are identical. Relations with a guaranteed non-empty toward.as,
self-relations, and keyOnly relations are unchanged. For an empty or dynamic
toward.as, determine whether its runtime value can be falsy; if so, treat the
relation as using the default name.

A relation field without a trailing ID, Id, or id would default to its own scalar
field name and therefore conflict. Give that relation an explicit toward.as.
```

## executeScript arg JSON.stringify → value

**Migration:** Partially automatic

Unwrap `JSON.stringify(...)` passed as the `executeScript` `arg` option. In v2 `arg` takes a JSON-serializable value and is serialized internally, so a pre-stringified argument double-encodes.

Before:

```ts
await executeScript({ ...opts, arg: JSON.stringify({ a: 1 }) });
```

After:

```ts
await executeScript({ ...opts, arg: { a: 1 } });
```

```text
In Tailor SDK v2 the executeScript() arg option takes a JSON-serializable value
and is serialized internally, so a pre-stringified argument double-encodes. The
codemod already rewrote the direct form arg: JSON.stringify(X) to arg: X. Review
the executeScript calls in these files for cases it could not rewrite — where the
arg value is reached indirectly, for example:
- a variable holding a JSON.stringify(...) result (const s = JSON.stringify(x); ... arg: s)
- JSON.stringify(x, null, 2) or another multi-argument form
- an options object built or spread dynamically

For each such call, pass the underlying value directly as arg (drop the
JSON.stringify wrapper) so executeScript serializes it once. Leave calls that
already pass a plain value unchanged.
```

## defineIdp publishUserEvents → publishEvents

**Migration:** Partially automatic

Rename the `defineIdp` option `publishUserEvents` to `publishEvents`, matching the field name that TailorDB tables, resolvers, and workflows already use.

Before:

```ts
import { defineIdp } from "@tailor-platform/sdk";

export const idp = defineIdp("my-idp", {
  clients: ["my-client"],
  publishUserEvents: true,
});
```

After:

```ts
import { defineIdp } from "@tailor-platform/sdk";

export const idp = defineIdp("my-idp", {
  clients: ["my-client"],
  publishEvents: true,
});
```

A shorthand option keeps reading the same local:

Before:

```ts
defineIdp("my-idp", { clients, publishUserEvents });
```

After:

```ts
defineIdp("my-idp", { clients, publishEvents: publishUserEvents });
```

```text
In Tailor SDK v2, the IdP option `publishUserEvents` is renamed to
`publishEvents`, so all four services that publish events use one field name.
The codemod rewrites the option key on `defineIdp` calls whose callee resolves
to the SDK export, including aliased and namespace imports, and rewrites a
shorthand `{ publishUserEvents }` to `{ publishEvents: publishUserEvents }` so
it keeps reading the same local.

Also review, and migrate by hand:
- An options object built in a variable or spread into the call — the codemod
  only rewrites object literals passed directly to `defineIdp`.
- A computed key (e.g. `[key]: value`) that resolves to `publishUserEvents`.
- Type annotations or interfaces that declare the option themselves.
- A file where a local declaration shadows the `defineIdp` import; the codemod
  skips it because the call may not be the SDK export.
```

## defineWaitPoint/defineWaitPoints → createWaitPoint/createWaitPoints

**Migration:** Partially automatic

Rename `defineWaitPoint` and `defineWaitPoints` to `createWaitPoint` and `createWaitPoints`. The functions create runtime instances with `.wait()` / `.resolve()` methods, so the `create*` prefix is used consistently.

Before:

```ts
import { defineWaitPoints } from "@tailor-platform/sdk";

export const { approval } = defineWaitPoints((define) => ({
  approval: define<{ message: string }, { approved: boolean }>(),
}));
```

After:

```ts
import { createWaitPoints } from "@tailor-platform/sdk";

export const { approval } = createWaitPoints((define) => ({
  approval: define<{ message: string }, { approved: boolean }>(),
}));
```

## workflow.triggerWorkflow/triggerJobFunction/resumeWorkflow → startWorkflow/execJobFunction/resumeWorkflowExecution

**Migration:** Partially automatic

Rename tailor.workflow call sites from the pre-alignment triggerWorkflow/triggerJobFunction/resumeWorkflow names to the canonical startWorkflow/execJobFunction/resumeWorkflowExecution names, on both the ambient tailor.workflow global and a workflow value imported from @tailor-platform/sdk/runtime(/workflow). For a renamed triggerWorkflow call, also renames a literal `invoker` option key to `authInvoker` — startWorkflow's options expect the platform shape directly, unlike the removed triggerWorkflow wrapper, which converted invoker to authInvoker internally.

Before:

```ts
import { workflow } from "@tailor-platform/sdk/runtime";

await workflow.triggerWorkflow("myWorkflow", { data: "value" });
```

After:

```ts
import { workflow } from "@tailor-platform/sdk/runtime";

await workflow.startWorkflow("myWorkflow", { data: "value" });
```

A literal invoker option is renamed to authInvoker:

Before:

```ts
await workflow.triggerWorkflow("myWorkflow", { data: "value" }, { invoker: myInvoker });
```

After:

```ts
await workflow.startWorkflow("myWorkflow", { data: "value" }, { authInvoker: myInvoker });
```

```text
The pre-alignment tailor.workflow names triggerWorkflow, triggerJobFunction, and
resumeWorkflow are removed from the SDK's type surface in v2; use the canonical
startWorkflow, execJobFunction, and resumeWorkflowExecution names instead. The
codemod rewrites direct member-access call sites on the ambient tailor.workflow
global and on a workflow value imported from @tailor-platform/sdk/runtime or
@tailor-platform/sdk/runtime/workflow (including aliased imports). It skips a
file entirely when a local declaration shadows the workflow import or the
ambient tailor name, to avoid rewriting an unrelated same-named value — review
those manually.

For a renamed triggerWorkflow call, the codemod also renames a literal invoker
option key (including shorthand { invoker }) to authInvoker, since startWorkflow
expects the platform's authInvoker shape directly while triggerWorkflow's removed
wrapper converted invoker to authInvoker internally.

Also review, and migrate by hand:
- Destructured references (e.g. const { triggerWorkflow } = workflow) — the
  codemod only rewrites direct member-access calls.
- Imported TriggerWorkflowOptions / TriggerJobFunctionOptions types — rename
  them to StartWorkflowOptions / ExecJobFunctionOptions.
- An invoker option passed via a variable or spread (not a literal object) —
  the codemod only inspects literal object arguments; rename the invoker key
  to authInvoker in the options object's own definition.
- A renamed triggerJobFunction call whose target is another workflow job —
  rewrite it further to that job's own .start() method (e.g. worker.start(args)).
  Calling execJobFunction directly is not detected as a build-time dependency
  and fails the build.
```

## workflow.startJobFunction → execJobFunction

**Migration:** Partially automatic

`tailor.workflow.startJobFunction` and the `StartJobFunctionOptions` type are removed in v2. Use the canonical `execJobFunction` / `ExecJobFunctionOptions`: `Exec*` blocks and returns the job's result, while `Start*` returns only an execution ID. The codemod rewrites member-access call sites on the ambient `tailor.workflow` global and on a `workflow` value imported from @tailor-platform/sdk/runtime(/workflow), and renames `StartJobFunctionOptions` imports along with the type references that resolve to them.

Before:

```ts
import { workflow } from "@tailor-platform/sdk/runtime";

const result = workflow.startJobFunction("myJob", { data: "value" });
```

After:

```ts
import { workflow } from "@tailor-platform/sdk/runtime";

const result = workflow.execJobFunction("myJob", { data: "value" });
```

```text
startJobFunction is removed from the SDK's workflow runtime surface in v2;
execJobFunction is the canonical name for a blocking job call that returns the
job's result. The codemod rewrites direct member-access calls on the ambient
tailor.workflow global and on a workflow value imported from
@tailor-platform/sdk/runtime or @tailor-platform/sdk/runtime/workflow (including
aliased imports), and renames the StartJobFunctionOptions type. It skips a file
entirely when a local declaration shadows the workflow import or the ambient
tailor name, to avoid rewriting an unrelated same-named value.

Also review, and migrate by hand:
- Destructured references (e.g. const { startJobFunction } = workflow) — the
  codemod only rewrites direct member-access calls.
- mockWorkflow().startJobFunction in tests — assert on the execJobFunction vi.fn
  instead; the alias was the same mock function.
- A file that already imports ExecJobFunctionOptions alongside the removed type —
  rename the remaining references by hand and drop the duplicate specifier.
- A renamed call whose target is another workflow job — rewrite it further to
  that job's own .start() method (e.g. worker.start(args)). Calling
  execJobFunction directly is not detected as a build-time dependency and fails
  the build.
```

## openDownloadStream → downloadStream

**Migration:** Manual

The deprecated `openDownloadStream` file-streaming API is removed in v2. Use `downloadStream` for streamed file downloads. The generated file utilities now emit `downloadFileStream` (which calls `downloadStream` and returns `FileDownloadStreamResponse`) instead of the removed `openFileDownloadStream` helper.

Before:

```ts
const res = await openDownloadStream(namespace, typeName, fieldName, recordId);
```

After:

```ts
const res = await downloadStream(namespace, typeName, fieldName, recordId);
```

```text
The openDownloadStream file-streaming API is removed in v2. Replace every call to
openDownloadStream with downloadStream (same arguments). If you used the generated
openFileDownloadStream helper, switch to downloadFileStream, which calls
downloadStream and returns FileDownloadStreamResponse.
```

## Ambient runtime globals are opt-in

**Migration:** Partially automatic

Importing `@tailor-platform/sdk` no longer activates the ambient `tailor.*` / `tailordb.*` global declarations. The codemod rewrites simple direct `new tailor.idp.Client(...)` calls to the typed `idp.Client` wrapper from `@tailor-platform/sdk/runtime`; broader runtime global usage remains review-only. Only if you relied on the ambient globals directly, add `import "@tailor-platform/sdk/runtime/globals"`. (The capital-cased `Tailordb.*` namespace is removed separately — see the `Tailordb → tailordb` codemod.)

Preferred: switch to the typed wrappers from `@tailor-platform/sdk/runtime` and drop the ambient globals:

Before:

```ts
const client = new tailor.idp.Client();
```

After:

```ts
import { idp } from "@tailor-platform/sdk/runtime";
const client = new idp.Client({ namespace: "my-namespace" });
```

Fallback: only if you must keep referencing the bare `tailor.*` names, opt into the global declarations:

Before:

```ts
const client = new tailor.idp.Client();
```

After:

```ts
import "@tailor-platform/sdk/runtime/globals";
const client = new tailor.idp.Client();
```

```text
The v2 SDK no longer enables ambient Tailor runtime globals from
`@tailor-platform/sdk`. For each flagged file that uses `tailor.*`,
`tailordb.*`, or Tailor runtime error globals, prefer migrating to the
typed wrappers from `@tailor-platform/sdk/runtime`. The codemod already
rewrites direct `new tailor.idp.Client(...)` calls to `new idp.Client(...)`
when the file has no conflicting `tailor` or `idp` binding. For any remaining
`tailor.idp.Client` references, either resolve the binding collision and use
`idp.Client`, or keep the ambient global deliberately.

Only when the file must keep referencing the bare `tailor.*` names directly,
opt into the global declarations instead by adding one of these:
- per-file: `import "@tailor-platform/sdk/runtime/globals";`
- project-wide: `"types": ["@tailor-platform/sdk/runtime/globals"]` in
  the relevant tsconfig compilerOptions

Leave files unchanged when the matching name is local, imported from another
module, or appears only in comments or prose strings. Embedded code strings
that use runtime globals are review-only findings; do not insert imports inside
string literals.
```

## Workflow job start() and start tests

**Migration:** Manual

Workflow job `.start()` (previously `.trigger()`) now aligns with the platform runtime: it returns the job result directly instead of a Promise wrapper, and tests no longer run job bodies locally. Mock start responses with `mockWorkflow()` (`setJobHandler` / `enqueueResult`, assert via `startedJobs`), or use `runWorkflowLocally()` for a full-chain local run.

Tests must mock the workflow runtime instead of running bodies locally:

Before:

```ts
const result = await orderJob.start({ id });
expect(result.status).toBe("done");
```

After:

```ts
using wf = mockWorkflow();
wf.setJobHandler((jobName) => (jobName === "order-job" ? { status: "done" } : null));
const result = await orderJob.start({ id });
expect(result.status).toBe("done");
```

```text
Workflow job .start() now uses the platform workflow runtime instead of running
the job body locally. In tests, acquire `using wf = mockWorkflow()` and provide
start responses (setJobHandler / enqueueResult), or use runWorkflowLocally() for a
full-chain local run; an unmocked start now throws. Outside tests, treat the
start result as the job output directly (no Promise wrapper to unwrap).
```

## Workflow.trigger()/WorkflowJob.trigger() → .start()

**Migration:** Manual

Rename `Workflow.trigger()` (returned by `createWorkflow()`) and `WorkflowJob.trigger()` (returned by `createWorkflowJob()`) to `.start()`, aligning the SDK's ergonomic verb with the platform's `start*` RPC vocabulary. No codemod ships for this rename: distinguishing a workflow/job `.trigger()` call from an unrelated object's own `.trigger()` method requires resolving the receiver back to a `createWorkflow`/`createWorkflowJob` result across files, which the SDK's own CLI bundler already does for build-time rewriting. Reusing that logic in a standalone script is a nontrivial lift, and — unlike the bundler, which fails loudly when it cannot rewrite a call — a codemod false positive would silently rewrite an unrelated `.trigger()` call with no error. For the call-site volume this rename typically involves, manual review guided by the prompt below is the safer trade-off.

Before:

```ts
const inventory = checkInventory.trigger({ orderId: input.orderId });
const workflowRunId = await orderProcessingWorkflow.trigger(args, { invoker: "manager" });
```

After:

```ts
const inventory = checkInventory.start({ orderId: input.orderId });
const workflowRunId = await orderProcessingWorkflow.start(args, { invoker: "manager" });
```

```text
In Tailor SDK v2, the ergonomic .trigger() method on a createWorkflow() or
createWorkflowJob() result is renamed to .start(). This is unrelated to the
separate tailor.workflow.triggerWorkflow/triggerJobFunction/resumeWorkflow removal
(see the workflow-trigger-rename codemod) — this rename targets the SDK's own
ergonomic wrapper, not the low-level platform call.

For each flagged `.trigger(` call in these files:
1. Confirm the receiver is a workflow or job object — typically a local const
   assigned from createWorkflow(...)/createWorkflowJob(...), a named import of one,
   or the default import of a workflow module. Skip receivers that are unrelated
   objects with their own .trigger() method (state machines, event emitters, etc.).
2. Rename the call from .trigger(...) to .start(...); the argument list is unchanged.
3. Update any mock/test code that reads WorkflowJob['trigger'] / Workflow['trigger']
   as a type, or that mocks the ergonomic method via a wrapper — for example,
   `wf.job(definition)` / `wf.workflow(definition)` from mockWorkflow() now return a
   mock of the `.start` method.
4. Update prose/docs/comments that say "trigger the workflow/job" to "start" only
   where they describe this SDK verb specifically, not unrelated event terminology.
```

## tailor-sdk binary → tailor

**Migration:** Partially automatic

Rename the CLI binary from `tailor-sdk` to `tailor` in package.json scripts, shell scripts, CI workflows, source files, generated declaration comments, and documentation. Does not rename `.tailor-sdk` directory paths or the `create-tailor-sdk` scaffolding package. Note: v2 also changes the default generated output directory from `.tailor-sdk/` to `.tailor/` and the setup lock file from `.github/tailor-sdk.lock` to `.github/tailor.lock`. Run `mv .tailor-sdk .tailor` to migrate the generated output directory (preserves auth connection state and other local files). Run `git mv .github/tailor-sdk.lock .github/tailor.lock` if the old lock file exists; without it `tailor setup check` will treat all managed workflows as missing. Exact ignore-file entries for `.tailor-sdk/` are handled by the generated-output ignore codemod. If your CI workflows were generated by `tailor setup`, re-run `tailor setup` afterwards so they pin tailor-platform/actions v2 — the v1 actions invoke the removed `tailor-sdk` bin.

Before:

```sh
tailor-sdk deploy
npx tailor-sdk@latest login
```

After:

```sh
tailor deploy
npx @tailor-platform/sdk@latest login
```

```text
Rename any remaining `tailor-sdk` binary invocations to `tailor`. Only rewrite
the binary name — leave `.tailor-sdk` directory paths and `create-tailor-sdk`
package references unchanged.
```

## .tailor-sdk ignore entries → .tailor

**Migration:** Automatic

Rewrite exact ignore-file entries for the v1 generated output directory from `.tailor-sdk` to the v2 `.tailor` directory. Other `.tailor-sdk` paths and prose are left unchanged.

Before:

```gitignore
.tailor-sdk/
```

After:

```gitignore
.tailor/
```

## ValidateFn simplification and type-level validate

**Migration:** Manual

Field-level `ValidateFn` is simplified from `(args: { value, data, invoker }) => boolean` to `(args: { value }) => string | void` — the function now returns the error message directly instead of a separate `[fn, message]` tuple. The `ValidateConfig` tuple form and `Validators<F>` record syntax on `db.type().validate()` are removed. Type-level validation uses `db.type().validate((args, issues) => void)` with `{ newRecord, oldRecord, invoker }` args and an `issues(field, message)` callback for cross-field rules.

Field-level validate: return an error message string instead of a boolean (tuple form removed):

Before:

```ts
.validate(
  [({ value }) => value.length > 5, "Name must be longer than 5 characters"],
)
```

After:

```ts
.validate(({ value }) =>
  value.length <= 5 ? "Name must be longer than 5 characters" : undefined,
)
```

Type-level validate: per-field record syntax replaced by a single function with `issues()` callback:

Before:

```ts
.validate({
  name: [({ value }) => value.length > 5, "Name must be longer than 5"],
})
```

After:

```ts
.validate(({ newRecord }, issues) => {
  if (newRecord.name && newRecord.name.length <= 5) {
    issues("name", "Name must be longer than 5");
  }
})
```

```text
The v2 SDK simplifies field validation and introduces type-level validation.

Field-level `.validate()` changes:
- Signature: `(args: { value, data, invoker }) => boolean` → `(args: { value }) => string | void`
- The function now returns the error message string directly (or undefined/void to pass)
  instead of returning a boolean with the message in a separate tuple.
- The `[fn, errorMessage]` tuple form (`ValidateConfig`) is removed.
- `data` and `invoker` are no longer available in field-level validators.
  Use type-level `.validate()` for cross-field or invoker-dependent rules.

Type-level `.validate()` on `db.type()` changes:
- Old: `.validate({ fieldName: fn | [fn, msg] | fn[] })` (per-field record, `Validators<F>` type)
- New: `.validate((args, issues) => void)` (single function, `TypeValidateFn<F>` type)
- Args: `{ newRecord, oldRecord, invoker }` — `newRecord` is the record after hooks run
- Call `issues(field, message)` to report validation errors; `field` supports dotted paths
- Move per-field validators that need `data`/`invoker` to the type-level function

For each remaining `ValidateConfig`, `Validators<`, or old-signature `.validate()` usage:
1. Rewrite field-level validators to return the error string directly
2. Move cross-field / invoker-dependent validators to the type-level function
3. Remove unused `ValidateConfig` / `Validators` type imports
```

## TailorDB hook redesign: field-level args and type-level hooks

**Migration:** Manual

Field-level `HookFn` args change from `{ value, data, invoker }` to create `{ input, invoker, now }` / update `{ input, oldValue, invoker, now }` — `value` is renamed to `input`, matching the `input` arg on type-level hooks (same pre-hook data, narrowed to one field); `data` (the full record) is removed; `oldValue` (previous field value) is added for update hooks only; `now` (operation timestamp) is shared across all hooks. Type-level hooks on `db.type().hooks()` change from per-field mapping `{ fieldName: { create, update } }` (`Hooks<F>`) to a single `{ create, update }` object (`TypeHook<F>`) — create hooks take `{ input, invoker, now }`, update hooks take `{ input, oldRecord, invoker, now }` (oldRecord is always non-null). Both return partial field overrides.

Field-level hooks: `value` renamed to `input`, `data` replaced by `oldValue` and `now`; use `now` instead of `new Date()`:

Before:

```ts
db.datetime().hooks({
  create: ({ value }) => value ?? new Date(),
  update: () => new Date(),
})
```

After:

```ts
db.datetime().hooks({
  create: ({ input, now }) => input ?? now,
  update: ({ now }) => now,
})
```

Type-level hooks: per-field mapping replaced by single create/update functions:

Before:

```ts
.hooks({
  fullAddress: {
    create: ({ data }) => `${data.postalCode} ${data.address}`,
    update: ({ data }) => `${data.postalCode} ${data.address}`,
  },
})
```

After:

```ts
.hooks({
  create: ({ input }) => ({
    fullAddress: `${input.postalCode} ${input.address}`,
  }),
  update: ({ input }) => ({
    fullAddress: `${input.postalCode} ${input.address}`,
  }),
})
```

```text
The v2 SDK redesigns TailorDB hooks at both field and type levels.

Field-level `.hooks()` on individual fields:
- Create args: `{ value, data, invoker }` → `{ input, invoker, now }` (no `oldValue`)
- Update args: `{ value, data, invoker }` → `{ input, oldValue, invoker, now }`
- `value` is renamed to `input`, matching the type-level hook's `input` arg — both are
  the same pre-hook data, at different granularity
- `data` (full record) is removed; update hooks get `oldValue` (previous field value) instead
- `now` provides the operation timestamp — use `now` instead of `new Date()`
- If a field-level hook needs the full record (other fields), move it to a type-level hook

Type-level `.hooks()` on `db.type()`:
- Old: `.hooks({ fieldName: { create: fn, update: fn } })` (per-field mapping, `Hooks<F>` type)
- New: `.hooks({ create: fn, update: fn })` (single object, `TypeHook<F>` type)
- Each function: `({ input, oldRecord, invoker, now }) => ({ fieldName: value, ... })`
- `input` is the pre-hook input (may have nullish values for optional/defaulted fields)
- Create hooks do not receive `oldRecord`; update hooks receive `oldRecord` (always non-null)
- Return an object with only the fields to override; unmentioned fields are unchanged

Migration steps for each `.hooks()` call on a `db.type()`:
1. If the old per-field hooks only use `value`/`invoker` and don't reference `data`,
   convert them to field-level hooks with the new args (`value` → `input`, plus `oldValue`, `now`)
2. If the old hooks reference `data` (cross-field access), convert to a type-level hook
   using `input`/`oldRecord`
3. Remove unused `Hooks<F>` / `HookFn<>` type imports
```

## `db.<namespace>.erdSite` → `tailordbErdPlugin({ sites })`

**Migration:** Partially automatic

Move the TailorDB `erdSite` setting from `db.<namespace>` in tailor.config.ts into `tailordbErdPlugin({ sites })` from `@tailor-platform/sdk-plugin-tailordb-erd`, registered via definePlugins(). The core config schema no longer accepts `erdSite`; the `tailor tailordb erd` commands read the target static website from the plugin configuration and validate each site name against `staticWebsites`. Install `@tailor-platform/sdk-plugin-tailordb-erd` as a dev dependency: the migrated config imports it, so config loading fails with a module-not-found error until it is installed.

Before:

```ts
export default defineConfig({
  db: {
    tailordb: {
      files: ["./tailordb/*.ts"],
      erdSite: "my-erd-site",
    },
  },
});
```

After:

```ts
import { tailordbErdPlugin } from "@tailor-platform/sdk-plugin-tailordb-erd";

export default defineConfig({
  db: {
    tailordb: {
      files: ["./tailordb/*.ts"],
    },
  },
});

export const plugins = definePlugins(
  tailordbErdPlugin({ sites: { tailordb: "my-erd-site" } }),
);
```

```text
In Tailor SDK v2 the TailorDB `erdSite` setting is removed from the core config
schema; the ERD deploy target is configured on the ERD CLI plugin instead. The
codemod rewrites literal `db.<namespace>.erdSite` entries inside top-level
defineConfig() calls into a `tailordbErdPlugin({ sites: { <namespace>: <value> } })`
argument of definePlugins(), importing it from @tailor-platform/sdk-plugin-tailordb-erd.

First, for every config that now registers tailordbErdPlugin, make sure
@tailor-platform/sdk-plugin-tailordb-erd is installed as a dev dependency — the
migrated config imports it, so config loading fails with ERR_MODULE_NOT_FOUND
until it is installed.

For any remaining `erdSite` config keys the codemod did not rewrite — a db config
built dynamically or passed via a variable, quoted or computed keys, spread
properties, a defineConfig() call inside a factory function, or a file that
already registers tailordbErdPlugin — move the namespace → static-website-name
mapping into tailordbErdPlugin({ sites }) and delete the `erdSite` key. For
factory-built configs, keep any referenced parameters or locals in scope when
moving the value to the module-level definePlugins() export. Each site name
must match a static website defined in staticWebsites. Leave unrelated
identifiers that merely contain the name (e.g. a defineStaticWebSite variable
named erdSite) unchanged.
```

## generate --watch flag removed

**Migration:** Manual

Review and remove `tailor generate --watch` / `-W` invocations and the `watch` option on `GenerateOptions`. The flag, its dependency watcher, and the self-restart-on-change logic are removed; `generate` now always performs a single generation pass.

The --watch/-W flag no longer exists; re-run generate after each change:

Before:

```sh
tailor generate --watch
```

After:

```sh
tailor generate
```

```text
Tailor SDK v2 removes the `generate --watch` (`-W`) flag along with the
dependency watcher and self-restart logic that powered it. `tailor generate`
now always runs a single generation pass and exits.

For each flagged `tailor generate ... --watch` / `-W` invocation (package.json
scripts, shell scripts, CI configs, or docs), drop the flag and re-run
`tailor generate` after each change instead. If automatic regeneration on file
change is still needed, wrap the command with a general-purpose file watcher
(e.g. `chokidar-cli`, `nodemon`) at the project level.

For programmatic use of `generate()` from `@tailor-platform/sdk/cli`, remove the
`watch` field from the `GenerateOptions` argument — the function now performs a
single generation pass and resolves once it completes.
```

## Generated seed exec.mjs → tailor seed CLI plugin

**Migration:** Partially automatic

`seedPlugin` no longer generates the `exec.mjs` seed runner. Seeding and validation move to the `tailor seed` commands provided by the `@tailor-platform/sdk-plugin-seed` CLI plugin: install it as a devDependency, replace `node <distPath>/exec.mjs` invocations with `tailor seed apply` and `node <distPath>/exec.mjs validate` with `tailor seed validate`, and delete the stale generated `<distPath>/exec.mjs` file. Seed data and schema generation (`data/*.jsonl`, `data/*.schema.ts`) is unchanged, and the `tailor seed apply` options mirror the old script (`--machine-user`, `--namespace`, `--skip-idp`, `--truncate`, `--yes`, entity-name arguments), plus a new `--upsert` flag to update existing rows instead of failing on duplicate ids.

Before:

```jsonc
"seed": "node ./seed/exec.mjs",
"seed:validate": "node ./seed/exec.mjs validate"
```

After:

```jsonc
"seed": "tailor seed apply",
"seed:validate": "tailor seed validate"
```

```text
seedPlugin no longer generates the exec.mjs seed runner in v2. The tailor seed
CLI plugin (@tailor-platform/sdk-plugin-seed) replaces it:

- Install @tailor-platform/sdk-plugin-seed as a devDependency next to
  @tailor-platform/sdk.
- Replace `node <distPath>/exec.mjs [options] [types...]` invocations with
  `tailor seed apply [options] [entities...]` (same options: --machine-user/-m,
  --namespace/-n, --skip-idp, --truncate, --yes, and entity-name arguments,
  plus a new --upsert flag to update existing rows instead of failing on
  duplicate ids).
- Replace `node <distPath>/exec.mjs validate [path]` with
  `tailor seed validate [path]`.
- Rewrite `fork("<distPath>/exec.mjs", ...)` call sites (test setup files
  typically fork the runner and await a hand-rolled Promise around
  `child.on("close", ...)`). The plugin is a CLI-dispatched binary rather
  than a forkable JS module, so call it synchronously instead —
  `execSync("npx @tailor-platform/sdk seed apply", { env, stdio: "inherit" })` — keeping
  the original `env` and `stdio` forwarding, and unwind the surrounding
  Promise wrapper (drop the now-unused `await`, and the `async` keyword when
  nothing else in the function awaits). Note that `execSync` throws on a
  nonzero exit, replacing the wrapper's explicit reject.
- Delete the stale generated `<distPath>/exec.mjs` file; keep the data/
  directory (JSONL data and generated schemas) as-is. Nothing removes it
  automatically, and a leftover runner keeps working while no longer being
  regenerated.
```

## @tailor-platform/sdk/test global mocks → @tailor-platform/sdk/vitest

**Migration:** Manual

The global platform mocks exported from `@tailor-platform/sdk/test` (`setupTailordbMock`, `setupWorkflowMock`, `setupWaitPointMock`, `setupInvokerMock`, `setupTailorErrorsMock`) and the bundled-output helper `createImportMain` are removed in v2. Use the `tailor-runtime` environment from `@tailor-platform/sdk/vitest` together with `mockTailordb` / `mockWorkflow`: the environment injects `TailorErrors` for you, `setWaitHandler` / `setResolveHandler` replace the wait-point stubs, and the invoker is driven through `globalThis.tailor.context.getInvoker` (or passed directly to `.body()` when testing the TypeScript source). No codemod ships for this migration: it replaces per-test global stubs with a Vitest environment plus disposable mocks, which changes the Vitest config, the setup shape, and the assertions of every affected test. The other `@tailor-platform/sdk/test` exports (`createTailorDBHook`, `createStandardSchema`, `unauthenticatedTailorUser`) are unchanged.

Job mocks move from a global stub to a disposable mock:

Before:

```ts
import { setupWorkflowMock } from "@tailor-platform/sdk/test";

const { startedJobs } = setupWorkflowMock(() => ({ ok: true }));
```

After:

```ts
import { mockWorkflow } from "@tailor-platform/sdk/vitest";

using wf = mockWorkflow();
wf.setJobHandler(() => ({ ok: true }));
// wf.startedJobs replaces the returned startedJobs array
```

```text
The global platform mocks from @tailor-platform/sdk/test are removed in v2.
Migrate each affected test to the tailor-runtime Vitest environment:

1. Add the environment for the test files that need platform globals — set
   environment: "tailor-runtime" in the Vitest project config, or add the
   // @vitest-environment tailor-runtime docblock to the file. The environment
   ships in @tailor-platform/sdk/vitest and installs TailorErrors and the base
   tailor/tailordb globals, so setupTailorErrorsMock has no replacement — delete it.
2. Replace setupTailordbMock(resolver) with using db = mockTailordb() and
   configure query results on that mock; read its recorded calls instead of the
   returned executedQueries / createdClients arrays.
3. Replace setupWorkflowMock(handler) with using wf = mockWorkflow() plus
   wf.setJobHandler(handler) (or wf.enqueueResult(...) for order-based results),
   and read wf.startedJobs.
4. Replace setupWaitPointMock({ onWait, onResolve }) with the same mockWorkflow()
   handle: wf.setWaitHandler / wf.setResolveHandler, asserting on wf.waitCalls /
   wf.resolveCalls.
5. Replace setupInvokerMock(invoker) with
   vi.spyOn(globalThis.tailor.context, "getInvoker").mockReturnValue(raw) for a
   bundled test, or pass invoker directly to .body() when unit-testing a
   resolver/executor/workflow job against the TypeScript source.
6. Drop createImportMain and the tests that import bundled output through it.
   Bundling integrity is the SDK's responsibility: unit-test the TypeScript
   source and cover deployed behavior with E2E tests instead.

See the SDK testing guide for the full environment setup.
```

## Programmatic CLI name options → workflow/executor definitions

**Migration:** Manual

The name-keyed option types exported from `@tailor-platform/sdk/cli` — `GetWorkflowOptions`, `StartWorkflowOptions`, `ListWorkflowExecutionsOptions`, `GetExecutorOptions`, `TriggerExecutorOptions`, `ListExecutorJobsOptions`, `GetExecutorJobOptions`, `WatchExecutorJobOptions` — are removed in v2, together with the function overloads that accepted them. Pass the workflow or executor definition itself instead: `{ workflow: myWorkflow, invoker: "admin" }` / `{ executor: myExecutor }`, matching the `*TypedOptions` shape that types `arg` and `payload` from the definition. No codemod ships for this migration: rewriting a name string into a definition requires importing the module that defines the workflow or executor, which a source-local transform cannot resolve.

Before:

```ts
import { startWorkflow } from "@tailor-platform/sdk/cli";

const { executionId } = await startWorkflow({ name: "user-sync", machineUser: "admin" });
```

After:

```ts
import { startWorkflow } from "@tailor-platform/sdk/cli";
import userSync from "./workflows/userSync";

const { executionId } = await startWorkflow({ workflow: userSync, invoker: "admin" });
```

Executor commands take the executor definition:

Before:

```ts
const result = await watchExecutorJob({ executorName: "daily-sync", jobId });
```

After:

```ts
const result = await watchExecutorJob({ executor: dailySync, jobId });
```

```text
The programmatic CLI functions in @tailor-platform/sdk/cli no longer accept a
workflow or executor name; they take the definition object instead. For each
flagged call site:

1. Import the workflow or executor definition — the module whose default export
   is createWorkflow(...) or whose export is createExecutor(...) with that name.
2. Replace name: "my-workflow" with workflow: myWorkflow, and
   executorName: "my-executor" with executor: myExecutor. For
   listWorkflowExecutions, workflowName becomes workflow.
3. startWorkflow's machine user moves from machineUser to the required
   invoker, typed against the machine users declared in tailor.config.ts.
4. Replace imported option types with the *TypedOptions equivalent
   (e.g. GetWorkflowOptions → GetWorkflowTypedOptions<typeof myWorkflow>).
   Note that arg (startWorkflow) and payload (triggerExecutor) are now typed
   from the definition, so a mistyped argument becomes a type error.

When the name is only known at runtime (read from argv or an environment
variable), the CLI command itself — `tailor workflow start <name>` /
`tailor executor trigger <name>` — remains the name-keyed entry point.
```

## tailor.d.ts Env uses value types instead of literal values

**Migration:** Manual

The `Env` interface in `tailor.d.ts` is generated from the type of each `defineConfig({ env })` value (`string`, `number`, or `boolean`) instead of the value itself, so the generated file no longer carries whatever the config resolved to when it was generated. Keys that aren't valid TypeScript identifiers are quoted, which previously produced a file that failed to parse. Run `tailor generate` to refresh the file, then widen any code that depended on the old literal types. If a `tailor.d.ts` you already committed contains a sensitive value, treat that value as exposed and rotate it; keep secrets in Secret Manager rather than `env`.

An env value can no longer stand in for a literal union; narrow it explicitly:

Before:

```ts
const stage: "production" | "staging" = env.STAGE;
```

After:

```ts
const stage = env.STAGE === "staging" ? "staging" : "production";
```

```text
Tailor SDK v2 generates the `Env` interface in `tailor.d.ts` from the type of
each `defineConfig({ env })` value (`string`, `number`, `boolean`) instead of
the resolved value, so `Env` properties no longer carry literal types.

Run `tailor generate` first to refresh `tailor.d.ts`, then review the places
that depended on the old literal types:

- An env value assigned or passed where a literal union is required, e.g.
  `const stage: "production" | "staging" = env.STAGE`. Narrow it with a
  comparison or a validation helper instead of relying on the declared type.
- A generic argument, conditional type, or template-literal type parameterized
  by an env value.
- `as const` / `satisfies` assertions that assumed one specific literal.

Plain comparisons (`env.STAGE === "production"`) and arithmetic on numeric env
values keep working and need no change. Do not restore the old behavior by
editing `tailor.d.ts`: it is generated and will be overwritten, and embedding
env values there is what leaked configured secrets into version control.
```

## Behavioral changes (no migration required)

These v2 changes alter runtime or CLI behavior; no source change is needed.

### publishEvents recomputed from the executors in each deploy

An unset `publishEvents` is recomputed on every `deploy` from the executors taking part in the run, in both directions: adding a subscribing trigger turns publishing on, and removing the last one turns it back off. Previously a workflow or job kept publishing once it had been enabled, so a workflow whose subscribing trigger is already gone stops publishing on the next `deploy` — declare `publishEvents: true` on it if something outside this project consumes those events. `deploy` also stops instead of applying when a subscription cannot be satisfied: when a trigger names a resource no config in the run declares, when a workflow or job combines `publishEvents: false` with a subscribing trigger, and when a config that resolves without an `id` subscribes across configs. Each of those errors names the resource and both ways to resolve it.

### CLI tokens stored in the OS keyring

CLI login tokens are stored in the OS keyring by default when available, falling back to the platform config file when it is not. No source change is required; re-login if you need tokens moved into the keyring.

### CLI users keyed by subject ID

The CLI stores human users by their stable subject ID instead of email (email is kept for display). Legacy email-keyed entries are migrated automatically on the next login or token refresh. No source change is required.

### function logs require a content hash for source mapping

`tailor function logs` maps stack traces against the function bundle only when the execution recorded a `contentHash`. Executions without one now show raw stack traces instead of mapped frames. No source change is required.

### `db.fields.timestamps()`: `updatedAt` becomes required

The `updatedAt` field from `db.fields.timestamps()` changes from optional to required (non-null): it defaults to the current time and keeps refreshing automatically on every update, though a value you provide explicitly is still respected. Applying this change to a table that already has rows with `updatedAt: null` makes `deploy` fail with `field "updatedAt" cannot be updated from non-required to required when records with null values exist`. Backfill those rows first, e.g. `UPDATE <table> SET "updatedAt" = "createdAt" WHERE "updatedAt" IS NULL` for each affected table — see [TailorDB migrations](../services/tailordb-migration.md#performance-and-large-tables) for splitting a large backfill across primary-key ranges if a single `UPDATE` times out.

### Node.js minimum version raised to 22.15.0

v2 requires Node.js **22.15.0** or later. This is the first version that includes `module.registerHooks()`, which the SDK uses to register its TypeScript loader hook synchronously in the main thread. The actual floor is now **22.18.0**: Node 22.15.0–22.17.x has a bug that crashes `tailor seed validate` when requiring `node:`-scheme-only builtins such as `node:sqlite`, fixed upstream by [nodejs/node#58612](https://github.com/nodejs/node/pull/58612) in 22.18.0. No source change is required; ensure your environment runs Node.js 22.18.0+.

### Legacy bundle artifact cleanup removed from deploy

`tailor deploy` no longer deletes on-disk bundle artifacts (`.entry.js` files, workflow-job bundles, and the `hooks-validate-scripts/` directory) left in the SDK output directory (`.tailor` by default) by SDK versions that predate the current in-memory bundling approach. Current bundlers no longer write these files. No source change is required; if such stale files remain from a very old SDK version, delete only those specific files/directories manually — do not delete the output directory itself, since it also holds deploy state (e.g. `secrets-state/`, `*.context.json`) that existing secrets and Auth Connections depend on.

### First v2 deploy to a v1-deployed environment needs migration sync

The pre-v2 CLI never wrote a script hash into deployed schemas, so the first `tailor deploy` against an environment last deployed with it reports `Remote schema drift detected` with every scripted type showing `has no script hash on remote`. Run `tailor tailordb migration sync <current migration number>` once for that environment to write the missing hashes, then `tailor deploy` as usual. Preview/PR workspaces don't hit this, since they're built with v2 from the start. No source change is required.

---

---
url: https://docs.tailor.tech/sdk/migration/v3.md
---
# Migrating to v3

Run the codemods, then finish anything reported as not migrated automatically:

```sh
npx @tailor-platform/sdk-codemod --from <current-version> --to <target-version>
```

## workflow.execJobFunction (imported) removed — use job.start()

**Migration:** Manual

`execJobFunction` on the `workflow` value imported from @tailor-platform/sdk/runtime(/workflow) is removed in v3. Calling it directly from a workflow job body to reach another job is not detected as a build-time dependency and has no working use; the target job's own `.start()` method is the only supported way to call it. This does not affect the ambient `tailor.workflow.execJobFunction` global — that's what `.start()` itself compiles down to at build time, and it remains fully supported.

Before:

```ts
import { workflow } from "@tailor-platform/sdk/runtime";

await workflow.execJobFunction("worker", { id: 1 });
```

After:

```ts
import { worker } from "./jobs/worker";

await worker.start({ id: 1 });
```

```text
workflow.execJobFunction — the value imported from
@tailor-platform/sdk/runtime or @tailor-platform/sdk/runtime/workflow — is
removed in v3. Replace each call with the target job's own .start() method:
import the WorkflowJob the call names and call <job>.start(args, options)
instead of workflow.execJobFunction("<job-name>", args, options).

This only removes the re-export from @tailor-platform/sdk/runtime. It does
not affect the ambient tailor.workflow.execJobFunction global, which stays
fully supported and is what .start() itself compiles down to at build time.
This codemod does not rewrite ambient tailor.workflow.execJobFunction(...)
call sites, since removing the import re-export does not affect them — but
if such a call site sits inside workflow job source and calls another job
by name, a separate build-time check already rejects it; migrate that call
to the target job's own .start() method too.

If the job name passed to execJobFunction is not a string literal (a truly
dynamic dispatch), there is currently no supported replacement — .start()
only targets a statically known job. Flag this case for a human instead of
guessing a rewrite.
```

## function test-run → function run

**Migration:** Partially automatic

Rename `tailor function test-run` invocations to `tailor function run`. `test-run` remains as a deprecated alias until it is removed in v3.

Before:

```sh
tailor function test-run resolvers/add.ts --arg '{"a":1,"b":2}'
```

After:

```sh
tailor function run resolvers/add.ts --arg '{"a":1,"b":2}'
```

```text
The `tailor function test-run` subcommand is renamed to `tailor function run`;
the old name is removed in v3. Replace any remaining `function test-run`
invocations the codemod did not rewrite (e.g. wrapped across lines or invoked
through a package runner such as `npx @tailor-platform/sdk`) with
`function run`. Leave prose that merely mentions the old subcommand name
unchanged unless it documents a command to type.
```

## setup branch --branch → --target

**Migration:** Partially automatic

Rename the `--branch` option of `tailor setup branch` invocations to `--target`. `--branch` remains as a deprecated alias until it is removed in v3. The `--branch` option of `setup tag`, `setup preview`, and `setup coordinate` is unchanged.

Before:

```sh
tailor setup branch --name my-app-stg --branch main
```

After:

```sh
tailor setup branch --name my-app-stg --target main
```

```text
The `--branch` option of `tailor setup branch` is renamed to `--target`;
the old spelling is removed in v3. Replace any remaining `--branch` options of
`setup branch` invocations the codemod did not rewrite (e.g. wrapped across
lines or invoked through a package runner such as `npx @tailor-platform/sdk`)
with `--target`. Do not touch the `--branch` option of `setup tag`,
`setup preview`, or `setup coordinate`, which keeps its name, and leave prose
that merely mentions the option unchanged unless it documents a command to type.
```

## relation() toward.type → toward.table

**Migration:** Partially automatic

Rename the `.relation()` option `toward.type` to `toward.table`, matching the `db.type()` → `db.table()` rename. The relation's own `type` (its cardinality, e.g. `"n-1"`) is unchanged — only the target-table reference nested under `toward` moves.

Before:

```ts
customerId: db.uuid().relation({
  type: "n-1",
  toward: { type: customer },
}),
```

After:

```ts
customerId: db.uuid().relation({
  type: "n-1",
  toward: { table: customer },
}),
```

```text
In Tailor SDK v3, `.relation()`'s `toward.type` option is renamed to
`toward.table` (it names a target table, not a TypeScript/GraphQL type).
Rename any remaining `toward.type` the codemod did not rewrite (e.g. a
`toward` object reached through a shared variable, spread, or computed
key) to `toward.table`. Do not touch the relation's own outer `type`
property, which is the relation's cardinality (e.g. "n-1", "1-1",
"keyOnly") and keeps its name.
```

---

---
url: https://docs.tailor.tech/sdk/plugin/custom.md
---
# Custom Plugins (Beta)

> **Beta Feature**: The custom plugin API is in beta and may change in future releases.

Create your own plugins by implementing the `Plugin` interface.

## Requirements

**Plugins must use default export**:

```typescript
// plugin.ts
const myPlugin: Plugin = {
  id: "@my-company/my-plugin",
  // ...
};

export default myPlugin; // Required: must be default export
```

This is required so that other plugins and generation-time hooks can use plugin-generated TailorDB tables via `getGeneratedTable()`.

## Plugin Interface

```typescript
interface Plugin<TableConfig = unknown, PluginConfig = unknown> {
  readonly id: string;
  readonly description: string;
  readonly importPath?: string;
  readonly tableConfigRequired?: boolean | ((pluginConfig?: PluginConfig) => boolean);
  readonly pluginConfig?: PluginConfig;

  // Definition-time hooks
  onTableLoaded?(
    context: PluginTableProcessContext<TableConfig, PluginConfig>,
  ): TablePluginOutput | Promise<TablePluginOutput>;
  onNamespaceLoaded?(
    context: PluginNamespaceProcessContext<PluginConfig>,
  ): PluginOutput | Promise<PluginOutput>;

  // Generation-time hooks
  onTailorDBReady?(
    context: TailorDBReadyContext<PluginConfig>,
  ): GeneratorResult | Promise<GeneratorResult>;
  onResolverReady?(
    context: ResolverReadyContext<PluginConfig>,
  ): GeneratorResult | Promise<GeneratorResult>;
  onExecutorReady?(
    context: ExecutorReadyContext<PluginConfig>,
  ): GeneratorResult | Promise<GeneratorResult>;
}
```

| Property              | Required                         | Description                                                                                      |
| --------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------ |
| `id`                  | Yes                              | Unique plugin identifier (e.g., `"@my-company/soft-delete"`)                                     |
| `description`         | Yes                              | Human-readable description                                                                       |
| `importPath`          | When using definition-time hooks | Path resolvable from `tailor.config.ts` directory. Used for import statements in generated code. |
| `tableConfigRequired` | No                               | Whether per-table config is required when attaching via `.plugin()`. Default: optional.          |
| `pluginConfig`        | No                               | Plugin-level config passed via `definePlugins()`. Set via factory function.                      |

## Hook Reference

### onTableLoaded

**Trigger**: Called once for each TailorDB table that has `.plugin({ pluginId: config })` attached.

**Context** (`PluginTableProcessContext`):

| Field          | Type              | Description                                |
| -------------- | ----------------- | ------------------------------------------ |
| `table`        | `TailorAnyDBType` | The TailorDB table being processed         |
| `tableConfig`  | `TableConfig`     | Per-table config from `.plugin()`          |
| `pluginConfig` | `PluginConfig`    | Plugin-level config from `definePlugins()` |
| `namespace`    | `string`          | Namespace of the TailorDB table            |

**Returns** (`TablePluginOutput`):

| Field       | Type                                            | Description                                            |
| ----------- | ----------------------------------------------- | ------------------------------------------------------ |
| `tables`    | `Record<string, TailorAnyDBType>`               | Additional TailorDB tables to generate (keyed by kind) |
| `resolvers` | `PluginGeneratedResolver[]`                     | Additional resolvers to generate                       |
| `executors` | `PluginGeneratedExecutor[]`                     | Additional executors to generate                       |
| `extends`   | `{ fields?: Record<string, TailorAnyDBField> }` | Fields to add to the source table                      |

Tables in `tables` are validated as complete TailorDB table definitions before registration.
Fields in `extends.fields` are validated as part of the resulting source table. You can return a
table builder directly or a structural copy such as `{ ...db.table(...) }`; a copy is accepted as
long as it retains valid table schema properties. Malformed output stops the build with an error
that identifies the plugin and relevant table output, without partially registering tables from
that source table's plugin processing.

**Use cases**:

* Generate derived tables (e.g., archive tables, history tables) from user-defined tables
* Add fields to existing tables (e.g., `deletedAt` for soft delete)
* Generate executors triggered by record events on the source table

```typescript
onTableLoaded(context) {
  const { table, tableConfig, namespace } = context;
  return {
    tables: { archive: db.table(`Deleted_${table.name}`, { ... }) },
    extends: { fields: { deletedAt: db.datetime({ optional: true }) } },
    executors: [{ name: `${table.name}-on-delete`, resolve: async () => await import("./on-delete"), context: { sourceTable: table, namespace } }],
  };
},
```

### onNamespaceLoaded

**Trigger**: Called once per namespace for plugins that do not require a source table.

**Context** (`PluginNamespaceProcessContext`):

| Field          | Type           | Description                                |
| -------------- | -------------- | ------------------------------------------ |
| `pluginConfig` | `PluginConfig` | Plugin-level config from `definePlugins()` |
| `namespace`    | `string`       | Target namespace                           |

**Returns** (`PluginOutput`):

Same as `TablePluginOutput` but without `extends` (namespace plugins cannot extend a source table).

Tables in `tables` undergo the same validation and support structural copies. If any returned
table is malformed, the build stops before namespace-generated tables are registered and the
error identifies the plugin and relevant table output.

**Use cases**:

* Generate tables that don't derive from a specific user table (e.g., audit log, settings table)

```typescript
onNamespaceLoaded(context) {
  return {
    tables: { auditLog: db.table("AuditLog", { action: db.string(), ... }) },
  };
},
```

### onTailorDBReady

**Trigger**: Called once after all TailorDB tables are loaded and auth is resolved.

**Context** (`TailorDBReadyContext`):

| Field          | Type                      | Description                                                     |
| -------------- | ------------------------- | --------------------------------------------------------------- |
| `tailordb`     | `TailorDBNamespaceData[]` | All namespaces with tables, source info, and plugin attachments |
| `auth`         | `GeneratorAuthInput?`     | Auth configuration (machine users, OAuth2 clients, etc.)        |
| `baseDir`      | `string`                  | Output directory for generated files                            |
| `configPath`   | `string`                  | Path to `tailor.config.ts`                                      |
| `pluginConfig` | `PluginConfig`            | Plugin-level config from `definePlugins()`                      |

`TailorDBNamespaceData` contains:

| Field               | Type                                       | Description                           |
| ------------------- | ------------------------------------------ | ------------------------------------- |
| `namespace`         | `string`                                   | Namespace name                        |
| `tables`            | `Record<string, TailorDBType>`             | All finalized tables in the namespace |
| `sourceInfo`        | `ReadonlyMap<string, TypeSourceInfoEntry>` | Source file info for each table       |
| `pluginAttachments` | `ReadonlyMap<string, PluginAttachment[]>`  | Plugin configs attached to each table |

**Returns** (`GeneratorResult`):

| Field    | Type                                                   | Description              |
| -------- | ------------------------------------------------------ | ------------------------ |
| `files`  | `Array<{ path, content, skipIfExists?, executable? }>` | Files to write to disk   |
| `errors` | `string[]?`                                            | Error messages to report |

**Use cases**:

* Generate table definitions (e.g., Kysely types, enum constants)
* Generate seed data scaffolding from table schemas
* Generate table lists or metadata files

```typescript
onTailorDBReady(ctx) {
  const allTables = ctx.tailordb.flatMap((ns) =>
    Object.values(ns.tables).map((table) => table.name),
  );
  return {
    files: [{ path: `${ctx.baseDir}/tables.ts`, content: `export const tables = ${JSON.stringify(allTables)};\n` }],
  };
},
```

### onResolverReady

**Trigger**: Called once after all resolvers are loaded, for plugins that do not implement `onExecutorReady`.

**Context** (`ResolverReadyContext`):

All fields from `TailorDBReadyContext`, plus:

| Field       | Type                      | Description                         |
| ----------- | ------------------------- | ----------------------------------- |
| `resolvers` | `ResolverNamespaceData[]` | All namespaces with their resolvers |

`ResolverNamespaceData` contains:

| Field       | Type                       | Description                    |
| ----------- | -------------------------- | ------------------------------ |
| `namespace` | `string`                   | Namespace name                 |
| `resolvers` | `Record<string, Resolver>` | All resolvers in the namespace |

**Returns**: `GeneratorResult` (same as `onTailorDBReady`)

**Use cases**:

* Generate API client code from resolver definitions
* Generate documentation that includes resolver endpoints

```typescript
onResolverReady(ctx) {
  const resolverNames = ctx.resolvers.flatMap((ns) =>
    Object.values(ns.resolvers).map((r) => r.name),
  );
  return {
    files: [{ path: `${ctx.baseDir}/api.ts`, content: generateApiClient(resolverNames) }],
  };
},
```

### onExecutorReady

**Trigger**: Called once after all executors are loaded.

**Context** (`ExecutorReadyContext`):

All fields from `ResolverReadyContext`, plus:

| Field       | Type                       | Description                            |
| ----------- | -------------------------- | -------------------------------------- |
| `executors` | `Record<string, Executor>` | All executors (keyed by executor name) |

**Returns**: `GeneratorResult` (same as `onTailorDBReady`)

**Use cases**:

* Generate dashboards or reports that need the full application topology
* Generate configuration files that reference all services

```typescript
onExecutorReady(ctx) {
  const summary = {
    tables: ctx.tailordb.flatMap((ns) => Object.keys(ns.tables)),
    resolvers: ctx.resolvers.flatMap((ns) => Object.keys(ns.resolvers)),
    executors: Object.keys(ctx.executors),
  };
  return {
    files: [{ path: `${ctx.baseDir}/app-summary.json`, content: JSON.stringify(summary, null, 2) }],
  };
},
```

## Hook Scheduling Rules

Each generation-time hook runs at its own pipeline phase, regardless of what other hooks the same plugin implements:

| Hook              | Runs after       | Data provided                                   |
| ----------------- | ---------------- | ----------------------------------------------- |
| `onTailorDBReady` | TailorDB loaded  | `tailordb` + `auth`                             |
| `onResolverReady` | Resolvers loaded | `tailordb` + `resolvers` + `auth`               |
| `onExecutorReady` | Executors loaded | `tailordb` + `resolvers` + `executors` + `auth` |

A plugin implementing multiple hooks (e.g., both `onTailorDBReady` and `onResolverReady`) will have each hook called at its natural phase. This ensures that files generated by `onTailorDBReady` are available when resolvers are loaded, before `onResolverReady` runs.

## Import Types

All context and result types are exported from `@tailor-platform/sdk`:

```typescript
import type {
  Plugin,
  PluginTableProcessContext,
  TablePluginOutput,
  PluginOutput,
  TailorDBReadyContext,
  ResolverReadyContext,
  ExecutorReadyContext,
  TailorDBNamespaceData,
  ResolverNamespaceData,
  GeneratorResult,
} from "@tailor-platform/sdk";
```

## getGeneratedTable Helper

The SDK provides an async `getGeneratedTable()` helper function to retrieve plugin-generated TailorDB tables. This enables plugins and other tools to work with tables generated by plugins.

```typescript
import { join } from "node:path";
import { getGeneratedTable } from "@tailor-platform/sdk/plugin";
import { customer } from "./tailordb/customer";

const configPath = join(import.meta.dirname, "./tailor.config.ts");

// Table-attached plugin
const DeletedCustomer = await getGeneratedTable(
  configPath,
  "@example/soft-delete",
  customer,
  "archive",
);

// Namespace plugin (pass null as sourceTable)
const AuditLog = await getGeneratedTable(configPath, "@example/audit-log", null, "auditLog");
```

**Parameters:**

* `configPath`: Path to `tailor.config.ts` (absolute or relative to cwd)
* `pluginId`: The plugin's unique identifier (e.g., `"@example/soft-delete"`)
* `sourceTable`: The TailorDB table that the plugin is attached to (`null` for namespace plugins)
* `kind`: The generated table kind (e.g., `"archive"`, `"auditLog"`)

**How it works:**

1. Loads and caches the config from the given path
2. Finds the plugin by ID from `definePlugins()` exports
3. Auto-resolves the namespace from config
4. Calls the plugin's `onTableLoaded()` or `onNamespaceLoaded()` method
5. Caches the result to avoid redundant processing
6. Returns the generated table matching the specified kind

## Examples

### Definition-time Plugin (Soft Delete)

A plugin that adds soft delete functionality via `onTableLoaded`:

```typescript
// plugins/soft-delete/plugin.ts
import { db } from "@tailor-platform/sdk";
import type { Plugin, PluginTableProcessContext, TablePluginOutput } from "@tailor-platform/sdk";

interface SoftDeleteTableConfig {
  archiveReason?: boolean;
  retentionDays?: number;
}

interface SoftDeletePluginConfig {
  archiveTablePrefix?: string;
  defaultRetentionDays?: number;
  requireTableConfig?: boolean;
}

function processSoftDelete(
  context: PluginTableProcessContext<SoftDeleteTableConfig, SoftDeletePluginConfig>,
): TablePluginOutput {
  const { table, tableConfig, pluginConfig, namespace } = context;
  const prefix = pluginConfig?.archiveTablePrefix ?? "Deleted_";

  // Generate archive table
  const archiveTable = db
    .table(`${prefix}${table.name}`, {
      originalId: db.uuid().description("ID of the deleted record"),
      originalData: db.string().description("JSON snapshot of deleted record"),
      deletedAt: db.datetime().description("When the record was deleted"),
      deletedBy: db.uuid().description("User who deleted the record"),
      ...(tableConfig.archiveReason && {
        reason: db.string({ optional: true }).description("Reason for deletion"),
      }),
      ...db.fields.timestamps(),
    })
    .description(`Archive for deleted ${table.name} records`);

  // Extend source table with deletedAt field
  const extendFields = {
    deletedAt: db.datetime({ optional: true }).description("Soft delete timestamp"),
  };

  return {
    tables: { archive: archiveTable },
    extends: { fields: extendFields },
    executors: [
      {
        name: `${table.name.toLowerCase()}-on-delete`,
        resolve: async () => await import("./executors/on-delete"),
        context: {
          sourceTable: table,
          archiveTable,
          namespace,
        },
      },
    ],
  };
}

function createSoftDeletePlugin(
  pluginConfig?: SoftDeletePluginConfig,
): Plugin<SoftDeleteTableConfig, SoftDeletePluginConfig> {
  return {
    id: "@example/soft-delete",
    description: "Adds soft delete with archive functionality",
    importPath: "./plugins/soft-delete",
    pluginConfig,
    tableConfigRequired: (config) => config?.requireTableConfig === true,
    onTableLoaded: processSoftDelete,
  };
}

export default createSoftDeletePlugin();
```

#### Executor with Context

```typescript
// plugins/soft-delete/executors/on-delete.ts
import { createExecutor, recordDeletedTrigger } from "@tailor-platform/sdk";
import type { TailorAnyDBType } from "@tailor-platform/sdk";
import { withPluginContext } from "@tailor-platform/sdk/plugin";
import { getDB } from "generated/tailordb";

interface SoftDeleteContext {
  sourceTable: TailorAnyDBType;
  archiveTable: TailorAnyDBType;
  namespace: string;
}

export default withPluginContext((ctx: SoftDeleteContext) => {
  const { sourceTable, archiveTable, namespace } = ctx;

  return createExecutor({
    name: `${sourceTable.name.toLowerCase()}-on-delete`,
    description: `Archives deleted ${sourceTable.name} records`,
    trigger: recordDeletedTrigger({ type: sourceTable }),
    operation: {
      kind: "function",
      body: async ({ oldRecord, user }) => {
        const db = getDB(namespace as "tailordb");
        await db
          .insertInto(archiveTable.name)
          .values({
            originalId: oldRecord.id,
            originalData: JSON.stringify(oldRecord),
            deletedAt: new Date(),
            deletedBy: user?.id ?? "system",
          })
          .execute();
      },
    },
  });
});
```

#### Usage

```typescript
// tailor.config.ts
import { definePlugins } from "@tailor-platform/sdk";
import softDeletePlugin from "./plugins/soft-delete";

export const plugins = definePlugins(
  softDeletePlugin({
    archiveTablePrefix: "Deleted_",
    defaultRetentionDays: 90,
  }),
);

// tailordb/customer.ts
export const customer = db
  .table("Customer", {
    name: db.string(),
    email: db.string(),
  })
  .plugin({
    "@example/soft-delete": {
      archiveReason: true,
    },
  });
```

### Generation-only Plugin (Table List)

A plugin that only uses `onTailorDBReady` to generate output files:

```typescript
import type { Plugin, GeneratorResult } from "@tailor-platform/sdk";

const tableListPlugin: Plugin = {
  id: "@example/table-list",
  description: "Generates a list of all TailorDB table names",

  onTailorDBReady(ctx): GeneratorResult {
    const allTables = ctx.tailordb.flatMap((ns) =>
      Object.values(ns.tables).map((table) => ({
        name: table.name,
        fieldCount: Object.keys(table.fields).length,
        namespace: ns.namespace,
      })),
    );
    const content = `// Generated table list\nexport const tables = ${JSON.stringify(allTables, null, 2)} as const;\n`;
    return {
      files: [{ path: `${ctx.baseDir}/tables.ts`, content }],
    };
  },
};
```

### Hybrid Plugin (Definition + Generation)

A plugin that uses both definition-time and generation-time hooks:

```typescript
const plugin: Plugin = {
  id: "@example/hybrid",
  description: "Generates derived tables and produces output files",
  importPath: "./plugins/hybrid",

  // Definition-time: Generate additional tables from attached source tables
  onTableLoaded(context) {
    return { tables: { derived: createDerivedTable(context.table) } };
  },

  // Generation-time: Generate output files from all finalized tables
  onTailorDBReady(ctx) {
    const allTables = ctx.tailordb.flatMap((ns) =>
      Object.values(ns.tables).map((table) => table.name),
    );
    return {
      files: [{ path: `${ctx.baseDir}/output.ts`, content: generateCode(allTables) }],
    };
  },
};
```

## Adding Type Safety

### Plugin-level type safety (TableConfig / PluginConfig)

Use TypeScript type parameters on `Plugin<TableConfig, PluginConfig>` to get type-safe config
in `onTableLoaded` and `onNamespaceLoaded` methods:

```typescript
interface MyTableConfig {
  archiveReason?: boolean;
}

interface MyPluginConfig {
  prefix?: string;
}

const plugin: Plugin<MyTableConfig, MyPluginConfig> = {
  id: "@example/my-plugin",
  // ...
  onTableLoaded(context) {
    // context.tableConfig is MyTableConfig
    // context.pluginConfig is MyPluginConfig
  },
};
```

### Per-table `.plugin()` type safety (declaration merging)

To enable type checking when users attach plugins via `.plugin()`, provide a declaration merge
for the `PluginConfigs` interface. Plugin authors should ship this in their package's type definitions:

```typescript
// your-plugin/types.d.ts (shipped with your plugin package)
export {}; // required: a top-level import/export makes this file augment
// the module below instead of replacing its other exports

declare module "@tailor-platform/sdk" {
  interface PluginConfigs<Fields extends string> {
    "@example/soft-delete": {
      archiveReason?: boolean;
      retentionDays?: number;
    };
  }
}
```

The `Fields` type parameter provides field names from the table being configured, enabling field-aware configurations:

```typescript
export {};

declare module "@tailor-platform/sdk" {
  interface PluginConfigs<Fields extends string> {
    "@example/i18n": {
      labels: Partial<Record<Fields, { ja: string; en: string }>>;
    };
  }
}
```

### Injecting fields into the attached table's type (declaration merging)

A plugin that adds fields to a table via `onTableLoaded`'s `extends.fields` (see
[onTableLoaded](#ontableloaded) above) can also make those fields show up on the table's own
static type right away, computed from the literal per-table config passed to `.plugin()`. Provide
a declaration merge for the `PluginFieldExtensions` interface, keyed by the same `id` used in
`PluginConfigs`:

```typescript
// your-plugin/types.d.ts (shipped with your plugin package)
import type { TailorDBField } from "@tailor-platform/sdk";

declare module "@tailor-platform/sdk" {
  interface PluginConfigs<Fields extends string> {
    "@example/lifecycle": {
      transitions: Record<string, { from: readonly string[]; to: string }>;
    };
  }

  interface PluginFieldExtensions<Fields extends string, Config> {
    "@example/lifecycle": Config extends {
      transitions: infer T extends Record<string, { from: readonly string[]; to: string }>;
    }
      ? {
          status: TailorDBField<
            { type: "enum"; array: false },
            T[keyof T]["from"][number] | T[keyof T]["to"]
          >;
        }
      : never;
  }
}
```

With this in place, the table returned by `.plugin()` already has the derived field. The status enum
includes every state that appears anywhere in `transitions` — both a `from` state that a transition
never produces (like the initial `"PENDING"` below) and every `to` state:

```typescript
import { db } from "@tailor-platform/sdk";

const approvalRequest = db.table("ApprovalRequest", { title: db.string() }).plugin({
  "@example/lifecycle": {
    transitions: {
      approve: { from: ["PENDING"], to: "APPROVED" },
      reject: { from: ["PENDING"], to: "REJECTED" },
    },
  },
});
// approvalRequest's type now includes status: "PENDING" | "APPROVED" | "REJECTED"
```

The type registered in `PluginFieldExtensions` must describe only the fields being added — it is
merged into the table's existing fields, not a replacement for them. A field name that collides
with an existing field, with a file key declared via `.files()`, or with a field injected by
another plugin attached in the same `.plugin()` call, is a type error at the call site — regardless
of whether `.files()` or `.plugin()` was called first. `tailor generate` also rejects the same
collision at runtime, as a backstop for any case a table's static type doesn't otherwise catch.

This only affects the table's static type. The corresponding field exists on the table's
generated schema, and on the table object's own `fields`, only after `tailor generate` actually
applies `extends.fields`. Before that, reading an injected field directly off the table
(`table.fields.status`) returns `undefined`, and `pickFields(["status"])` throws — call these only
with the table's originally declared fields, not ones a plugin injects.

To keep the declared type and the runtime implementation in sync, give `Plugin`'s optional third
type parameter the same shape and use it inside `onTableLoaded`:

```typescript
import { db, type Plugin, type TailorDBField } from "@tailor-platform/sdk";

const lifecyclePlugin: Plugin<
  LifecycleTableConfig,
  LifecyclePluginConfig,
  { status: TailorDBField<{ type: "enum"; array: false }, "PENDING" | "APPROVED" | "REJECTED"> }
> = {
  id: "@example/lifecycle",
  description: "Derives a status field from a transitions map",
  onTableLoaded(context) {
    return { extends: { fields: { status: db.enum(["PENDING", "APPROVED", "REJECTED"]) } } };
  },
};
```

### Resolving plugin-level config from a `Plugin[]` array (declaration merging)

`PluginConfig` is already available inside your own plugin's hooks via `context.pluginConfig`.
If other code instead needs to look up your plugin's config from a `Plugin[]` array by `id` —
without importing your plugin's config type — register it on the `PluginConfigRegistry`
interface. Plugin authors should ship this in their package's type definitions:

```typescript
// your-plugin/types.d.ts (shipped with your plugin package)
export {}; // required: a top-level import/export makes this file augment
// the module below instead of replacing its other exports

declare module "@tailor-platform/sdk/plugin" {
  interface PluginConfigRegistry {
    "@example/soft-delete": {
      archiveTablePrefix?: string;
    };
  }
}
```

This only registers the type; it does not provide a function to read it. Callers resolve a
registered config from `Plugin[]` using the public `Plugin` and `PluginConfigRegistry` types:

```typescript
import type { Plugin } from "@tailor-platform/sdk";
import type { PluginConfigRegistry } from "@tailor-platform/sdk/plugin";

function resolvePluginConfig<Id extends keyof PluginConfigRegistry>(
  plugins: readonly Plugin[],
  id: Id,
): PluginConfigRegistry[Id] | undefined {
  return plugins.find((p) => p.id === id)?.pluginConfig as PluginConfigRegistry[Id] | undefined;
}
```

An `id` that isn't registered fails to compile, instead of silently resolving to `unknown`.

---

---
url: https://docs.tailor.tech/sdk/services/aigateway.md
---
# AI Gateway

AI Gateway provides a unified endpoint for accessing a range of large language models 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 models
* 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", {});

export default defineConfig({
  name: "my-app",
  aiGateways: [aiGateway],
});
```

## Options

### authNamespace

The auth namespace used to resolve request tokens against your workspace's auth configuration. Optional — when omitted, it defaults to your application's own Auth service (local or external, the name passed to `defineAuth()`), which is what most AI Gateways need. Omitting it without an Auth service configured is rejected by `deploy`/`generate`, asking you to either define one or set `authNamespace` explicitly:

```typescript
import { defineAIGateway, defineAuth, defineConfig } from "@tailor-platform/sdk";

const auth = defineAuth("my-auth", {
  // ...auth configuration...
});

const aiGateway = defineAIGateway("my-aigateway", {}); // defaults to "my-auth"

export default defineConfig({
  name: "my-app",
  auth,
  aiGateways: [aiGateway],
});
```

Type-checked and autocompleted against your own Auth service name via the generated `tailor.d.ts` (the `AuthNamespaceNameRegistry` interface). Run `tailor generate` (or `deploy`) after defining an Auth service to refresh it. Before the first generate run, `authNamespace` accepts any string.

To authenticate against a **different** application's Auth service, reference it as an [external resource](../configuration.md#external-resources) in your own config — `authNamespace` then defaults to it like any other Auth service:

```typescript
import { defineAIGateway, defineConfig } from "@tailor-platform/sdk";

const aiGateway = defineAIGateway("my-aigateway", {}); // defaults to "shared-auth"

export default defineConfig({
  name: "my-app",
  auth: { name: "shared-auth", external: true },
  aiGateways: [aiGateway],
});
```

An `authNamespace` that doesn't match any auth namespace in your workspace surfaces only at runtime, as `401 Unauthorized` on every request to the gateway.

### 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", {
  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 omitted: defaults to this app's own Auth service, declared below.
  cors: [website.url],
});

const auth = defineAuth("my-auth", {
  // ...auth configuration...
});

export default defineConfig({
  name: "my-app",
  auth,
  staticWebsites: [website],
  aiGateways: [aiGateway],
});
```

## Runtime Usage

Resolvers, executors, and workflow jobs can resolve a gateway's platform-assigned URL by name via `aigateway.get()`. The name is type-checked and autocompleted against the AI Gateways defined in `aiGateways`:

```typescript
import { aigateway } from "@tailor-platform/sdk/runtime";

const { url } = await aigateway.get("my-aigateway");

// await aigateway.get("unknown"); // Type error — only "my-aigateway" is allowed
```

Type narrowing is provided by the generated `tailor.d.ts` (the `AIGatewayNameRegistry` interface). Run `tailor generate` (or `deploy`) after defining new AI Gateways to refresh it. Before the first generate run, `get()` accepts any string.

The same URL is also shown by `tailor show`, which lists the URL of each AI Gateway defined in `aiGateways` once it has been deployed.

---

---
url: https://docs.tailor.tech/sdk/services/auth.md
---
# Auth

Auth is a service for configuring authentication and authorization in your Tailor Platform application.

## Overview

Auth provides:

* User profile mapping to TailorDB tables
* Machine users for service-to-service authentication
* OAuth 2.0 client configuration
* Identity provider integration
* Auth connections for external OAuth2 provider integration

For the official Tailor Platform documentation, see [Auth Guide](/guides/auth/overview).

## Configuration

Configure Auth service using `defineAuth()`:

**Definition Rules:**

* **One auth per application**: Each application can have exactly one Auth service
* **Configuration location**: Define in `tailor.config.ts` using `defineAuth()` and reference directly in the config's `auth` field
* **`userProfile` and `machineUserAttributes` are mutually exclusive**: Specifying both fails at deploy/generate time with ``Specify either `userProfile` or `machineUserAttributes`, not both.``

```typescript
import { defineAuth } from "@tailor-platform/sdk";
import { user } from "./tailordb/user";

const auth = defineAuth("my-auth", {
  userProfile: {
    type: user,
    usernameField: "email",
    attributes: { role: true },
  },
  // Optional when you don't define userProfile:
  // machineUserAttributes: {
  //   role: t.string(),
  // },
  machineUsers: {
    "admin-machine-user": {
      attributes: { role: "ADMIN" },
    },
  },
  oauth2Clients: {
    "my-oauth2-client": {
      redirectURIs: ["https://example.com/callback"],
      grantTypes: ["authorization_code", "refresh_token"],
    },
  },
  connections: {
    "google-connection": {
      type: "oauth2",
      providerUrl: "https://accounts.google.com",
      issuerUrl: "https://accounts.google.com",
      clientId: process.env.GOOGLE_CLIENT_ID!,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
    },
  },
  idProvider: idp.provider("my-provider", "my-client"),
});

export default defineConfig({
  auth,
});
```

## User Profile

Maps authenticated identities to a TailorDB table:

```typescript
userProfile: {
  type: user,              // TailorDB table for user records
  usernameField: "email",  // Field used as username (must be unique)
  attributes: {
    role: true,            // Enable 'role' as a user attribute
  },
},
```

Example TailorDB table for user profile:

```typescript
// tailordb/user.ts
import { db } from "@tailor-platform/sdk";

export const user = db.table("User", {
  email: db.string().unique(), // usernameField must have unique constraint
  role: db.enum(["admin", "user"]),
  ...db.fields.timestamps(),
});
```

**type**: The TailorDB table that stores user records.

**namespace** (optional): The TailorDB namespace where the user table is defined. Usually auto-resolved from your `db` configuration, so you don't need to specify it. Required only when multiple TailorDB namespaces exist and the table lives in an external TailorDB:

```typescript
userProfile: {
  namespace: "external-ns", // Explicitly specify the namespace
  type: user,
  usernameField: "email",
},
```

**usernameField**: The field in the TailorDB table 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 table 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

In addition to `attributes` (key-value map), you can configure `attributeList` to expose UUID-type fields as an ordered list. This is useful for referencing related records by their IDs.

```typescript
userProfile: {
  type: user,
  usernameField: "email",
  attributes: { role: true },
  attributeList: ["organizationId", "teamId"],
},
```

**attributeList**: An array of field names from the TailorDB table. These fields will be exposed as an ordered list of UUIDs. Only UUID-type fields (non-array) can be included in the attribute list.

Example TailorDB table with UUID fields for attribute list:

```typescript
// tailordb/user.ts
import { db } from "@tailor-platform/sdk";

export const user = db.table("User", {
  email: db.string().unique(),
  role: db.enum(["admin", "user"]),
  organizationId: db.uuid(), // Can be used in attributeList
  teamId: db.uuid(), // Can be used in attributeList
  ...db.fields.timestamps(),
});
```

The `attributeList` values are accessible via the runtime principal's `attributeList` as a tuple:

```typescript
// In a resolver
body: (context) => {
  const [organizationId, teamId] = context.caller?.attributeList ?? [];
},

// In TailorDB hooks
.hooks({
  field: {
    create: ({ invoker }) => invoker?.attributeList[0] ?? null, // First UUID from list
  },
})
```

## Machine User Attributes (without userProfile)

When you want to use machine users without defining a `userProfile`, define `machineUserAttributes` instead. These attributes are used for:

* type-safe `machineUsers[*].attributes`
* runtime principal `attributes` typing (via `tailor.d.ts`)

```typescript
import { defineAuth, t } from "@tailor-platform/sdk";

export const auth = defineAuth("my-auth", {
  machineUserAttributes: {
    role: t.string(),
    isActive: t.bool(),
    tags: t.string({ array: true }),
  },
  machineUsers: {
    "admin-machine-user": {
      attributes: { role: "ADMIN", isActive: true, tags: ["root"] },
    },
  },
});
```

To update types in `tailor.d.ts`, run:

```bash
tailor generate
```

## Machine Users

Service accounts for automated access without user interaction:

```typescript
machineUsers: {
  "admin-machine-user": {
    attributes: { role: "ADMIN" },
  },
  "readonly-machine-user": {
    attributes: { role: "READER" },
  },
},
```

**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
body: (context) => {
  const role = context.caller?.attributes.role;
},
```

**attributeList**: Values for fields enabled in `userProfile.attributeList`. Must be an array of valid UUIDs in the same order as declared in userProfile:

```typescript
// userProfile with attributeList
userProfile: {
  type: user,
  usernameField: "email",
  attributes: { role: true },
  attributeList: ["organizationId", "teamId"],
},
machineUsers: {
  "admin-machine-user": {
    attributes: { role: "ADMIN" },
    attributeList: [
      "550e8400-e29b-41d4-a716-446655440000",
      "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    ],
  },
},
```

These values are accessible via the runtime principal's `attributeList`:

```typescript
// In a resolver
body: (context) => {
  const [organizationId, teamId] = context.caller?.attributeList ?? [];
},

// In TailorDB hooks
.hooks({
  field: {
    create: ({ invoker }) => invoker?.attributes.role === "ADMIN" ? "default" : null,
  },
})

// In TailorDB validate
.validate({
  field: [
    ({ invoker }) => invoker?.attributes.role === "ADMIN",
    "Only admins can set this field",
  ],
})
```

Machine users are useful for:

* CI/CD pipelines
* Background jobs
* Service-to-service communication
* E2E testing

Get a machine user token using the CLI:

```bash
tailor machineuser token <name>
```

### Specifying a machine user invoker

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
export const auth = defineAuth("my-auth", {
  machineUsers: {
    "admin-machine-user": {
      attributes: { role: "ADMIN" },
    },
  },
  // ... other config
});
```

```typescript
// resolvers/start-workflow.ts
import { createResolver, t } from "@tailor-platform/sdk";
import myWorkflow from "../workflows/my-workflow";

export default createResolver({
  name: "startMyWorkflow",
  operation: "mutation",
  input: {
    id: t.string(),
  },
  body: async ({ input }) => {
    // Start workflow with machine user permissions
    const workflowRunId = await myWorkflow.start(
      { id: input.id },
      { invoker: "admin-machine-user" },
    );
    return { workflowRunId };
  },
  output: t.object({
    workflowRunId: t.string(),
  }),
});
```

Type narrowing is provided by the generated `tailor.d.ts` (the `MachineUserNameRegistry` interface). Run `tailor generate` (or `deploy`) after defining new machine users to refresh it.

## OAuth 2.0 Clients

Configure OAuth 2.0 clients for third-party applications:

```typescript
oauth2Clients: {
  "my-oauth2-client": {
    redirectURIs: [
      "https://example.com/callback",
      `${website.url}/callback`,  // Type-safe URL from StaticWebsite
    ],
    description: "My OAuth2 client",
    grantTypes: ["authorization_code", "refresh_token"],
    accessTokenLifetimeSeconds: 3600,    // 1 hour
    refreshTokenLifetimeSeconds: 604800, // 7 days
    requireDpop: true,                   // Require DPoP for this client
  },
},
```

**redirectURIs**: Allowed redirect URIs after authentication.

**description**: Optional description of the client.

**grantTypes**: Supported OAuth 2.0 grant types:

* `authorization_code` - Standard OAuth 2.0 authorization code flow
* `refresh_token` - Allow refreshing access tokens

**accessTokenLifetimeSeconds**: Optional access token lifetime in seconds. Minimum: 60 seconds, Maximum: 86400 seconds (1 day). If not specified, uses platform default.

**refreshTokenLifetimeSeconds**: Optional refresh token lifetime in seconds. Minimum: 60 seconds, Maximum: 604800 seconds (7 days). If not specified, uses platform default.

**requireDpop**: Optional boolean to require DPoP (Demonstrating Proof of Possession) for this client. When set to `true`, the client must use DPoP tokens for authentication. If not specified, DPoP is not required.

Get OAuth2 client credentials using the CLI:

```bash
tailor oauth2client get <name>
```

## Identity Provider

Connect to an external identity provider:

```typescript
idProvider: idp.provider("my-provider", "my-client"),
```

See [IdP](idp) for configuring identity providers.

## Auth Connections

Auth connections enable OAuth2 authentication with external providers (Google, Microsoft 365, QuickBooks, etc.) for application-to-application flows. Functions can access connection tokens at runtime via `authconnection.getConnectionToken()` (from `@tailor-platform/sdk/runtime`).

For the official Tailor Platform documentation, see [AuthConnection Guide](/guides/auth/authconnection).

> \[!NOTE]
> Deploy updates connections **in-place**, preserving the OAuth token. If the connection requires re-authorization after an update, the deploy will warn you:
>
> ```bash
> tailor authconnection authorize --name <connection-name>
> # Or via the Console:
> tailor authconnection open
> ```

### Setup Flow

Setting up an auth connection requires two steps:

1. **Create** the connection (registers the OAuth2 provider credentials)
2. **Authorize** the connection (runs the OAuth2 flow to obtain and store tokens)

Both steps are needed regardless of whether you manage connections via config or CLI.

### Configuration

Define connections in `defineAuth()`:

```typescript
import { defineAuth } from "@tailor-platform/sdk";

export const auth = defineAuth("my-auth", {
  // ... other auth config
  connections: {
    "google-connection": {
      type: "oauth2",
      providerUrl: "https://accounts.google.com",
      issuerUrl: "https://accounts.google.com",
      clientId: process.env.GOOGLE_CLIENT_ID!,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
    },
  },
});
```

After `tailor deploy`, authorize the connection:

```bash
tailor authconnection authorize --name google-connection \
  --scopes "openid,profile,email"
```

The authorize command opens a browser for the OAuth2 flow. The authorization code is sent to the platform, which exchanges it for tokens using the client secret registered in the connection config.

### Connection Config Fields

| Field          | Type     | Required | Description                                 |
| -------------- | -------- | -------- | ------------------------------------------- |
| `type`         | `string` | Yes      | Connection type. Currently only `"oauth2"`. |
| `providerUrl`  | `string` | Yes      | OAuth2 provider URL.                        |
| `issuerUrl`    | `string` | Yes      | OAuth2 issuer URL for JWT validation.       |
| `clientId`     | `string` | Yes      | OAuth2 client ID.                           |
| `clientSecret` | `string` | Yes      | OAuth2 client secret.                       |
| `authUrl`      | `string` | No       | Override for the authorization endpoint.    |
| `tokenUrl`     | `string` | No       | Override for the token endpoint.            |

### Retrieving Connection Tokens

Use `authconnection.getConnectionToken()` from `@tailor-platform/sdk/runtime` to retrieve connection tokens at runtime. The connection name is type-checked and autocompleted against the connections defined in `defineAuth()`'s `connections`:

```typescript
import { authconnection } from "@tailor-platform/sdk/runtime";

// In a resolver, executor, or workflow:
const tokens = await authconnection.getConnectionToken("google-connection");
const response = await fetch("https://www.googleapis.com/...", {
  headers: { Authorization: `Bearer ${tokens.access_token}` },
});

// authconnection.getConnectionToken("unknown"); // Type error — only "google-connection" is allowed
```

Type narrowing is provided by the generated `tailor.d.ts` (the `ConnectionNameRegistry` interface). Run `tailor generate` (or `deploy`) after defining new connections to refresh it. Before the first generate, or when `connections` is not defined in `defineAuth()`, `getConnectionToken()` accepts any string — this also supports connections managed entirely via the CLI.

This keeps runtime files independent from `tailor.config.ts`.

See [Built-in Interfaces](/guides/function/builtin-interfaces.html#auth-connection) for the full runtime API.

### CLI Management

Auth connections can also be managed via the CLI:

```bash
# Open the connections page in the Console (recommended for creating connections/tokens)
tailor authconnection open

# Authorize (opens browser for OAuth2 flow)
tailor authconnection authorize --name google-connection

# List all connections
tailor authconnection list

# Revoke a connection
tailor authconnection revoke --name google-connection
```

Connection creation and updates are handled by `tailor deploy` via the config. Deploy updates connections in-place, preserving the authorized token, and warns you if an update requires re-authorization (see the note above).

See [Auth Resource Commands](../cli/auth) for full CLI documentation.

## Before Login Hook

Run custom logic before a user logs in. This is useful for JIT (Just-In-Time) user provisioning — automatically creating or updating user records when a user authenticates for the first time.

```typescript
import { defineAuth } from "@tailor-platform/sdk";
import { user } from "./tailordb/user";

export const auth = defineAuth("my-auth", {
  userProfile: {
    type: user,
    usernameField: "email",
  },
  machineUsers: {
    "hook-invoker": {
      attributes: { role: "ADMIN" },
    },
  },
  hooks: {
    beforeLogin: {
      handler: async ({ claims, idpConfigName, env }) => {
        // Provision or update user based on IdP claims
        // `env` exposes the variables defined in `defineConfig({ env })`
      },
      invoker: "hook-invoker",
    },
  },
});
```

**handler**: An async function that receives `{ claims, idpConfigName, env }` and is called before each login. `claims` contains the token claims from the identity provider, `idpConfigName` is the name of the IdP configuration used for authentication, and `env` exposes the environment variables defined in `defineConfig({ env })` (the same values available via `context.env` in resolvers).

**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:

```bash
# Auth connections
tailor authconnection authorize --name <name>
tailor authconnection list
tailor authconnection revoke --name <name>

# List machine users
tailor machineuser list

# Get machine user token
tailor machineuser token <name>

# List OAuth2 clients
tailor oauth2client list

# Get OAuth2 client credentials
tailor oauth2client get <name>
```

See [Auth Resource Commands](../cli/auth) for full documentation.

---

---
url: https://docs.tailor.tech/sdk/services/executor.md
---
# Executor

Executors are event-driven handlers that automatically trigger in response to data changes, schedules, or external events.

## Overview

Executors provide:

* Automatic triggers on record changes (create, update, delete)
* Scheduled execution via cron expressions
* Incoming webhook handlers
* Post-resolver execution hooks
* Multiple operation types (functions, webhooks, GraphQL, workflows)

For the official Tailor Platform documentation, see [Executor Guide](/guides/executor/overview).

## Creating an Executor

Define executors in files matching glob patterns specified in `tailor.config.ts`.

**Definition Rules:**

* **One executor per file**: Each file must contain exactly one executor definition
* **Export method**: Must use `export default`
* **Uniqueness**: Executor names must be unique globally across your entire application

```typescript
import { createExecutor, recordCreatedTrigger, t } from "@tailor-platform/sdk";
import { user } from "../tailordb/user";

export default createExecutor({
  name: "user-welcome",
  description: "Send welcome email to new users",
  trigger: recordCreatedTrigger({
    type: user,
    condition: ({ newRecord }) => !!newRecord.email && newRecord.isActive,
  }),
  operation: {
    kind: "function",
    body: async ({ newRecord }) => {
      // Send welcome email logic here
    },
  },
});
```

### Disabling an Executor

Set `disabled: true` to deploy an executor without letting it run. The definition stays deployed, and the platform skips dispatching jobs to it.

```typescript
export default createExecutor({
  name: "user-welcome-paused",
  disabled: true,
  trigger: recordCreatedTrigger({ type: user }),
  operation: { kind: "function", body: async () => {} },
});
```

A disabled executor does not count as a subscriber when `deploy` resolves `publishEvents` on the resource its trigger names. Publishing is not enabled on that resource's behalf, and an explicit `publishEvents: false` on it is not rejected. If the resource was publishing only for this executor, the next `deploy` turns publishing back off — so disabling the last subscriber of a shared table changes that table for every config that reads its events.

The trigger is still deployed, so it must still name a resource the deploy declares; a disabled executor whose trigger names nothing fails the deploy exactly as an enabled one does.

## Trigger Types

### Record Triggers

Fire when records are created, updated, or deleted:

* `recordCreatedTrigger()`: Fires when a new record is created
* `recordUpdatedTrigger()`: Fires when a record is updated
* `recordDeletedTrigger()`: Fires when a record is deleted

Each trigger can include an optional filter function:

```typescript
recordUpdatedTrigger({
  type: order,
  condition: ({ newRecord, oldRecord }) =>
    newRecord.status === "completed" && oldRecord.status !== "completed",
});
```

### Schedule Trigger

Fires on a cron schedule:

```typescript
scheduleTrigger({ cron: "*/5 * * * *" }); // Every 5 minutes
scheduleTrigger({ cron: "0 9 * * 1" }); // Every Monday at 9am
scheduleTrigger({ cron: "0 0 1 * *" }); // First day of every month
scheduleTrigger({ cron: "0 * * * *", timezone: "Asia/Tokyo" });
```

### Incoming Webhook Trigger

Fires when an external webhook is received:

```typescript
type WebhookRequest = {
  body: WebhookPayload;
  headers: Record<string, string>;
};

incomingWebhookTrigger<WebhookRequest>();
```

You can customize the HTTP response returned to the webhook caller:

```typescript
// Response body only (shorthand)
incomingWebhookTrigger<WebhookRequest>({
  response: (args) => ({ challenge: args.body.challenge }),
});

// Response body with custom status code
incomingWebhookTrigger<WebhookRequest>({
  response: {
    body: (args) => ({ challenge: args.body.challenge }),
    statusCode: 201,
  },
});
```

If `body` is set without `statusCode`, the platform uses 200. If neither is set, the platform returns 204.

### Resolver Executed Trigger

Fires when a resolver is executed:

```typescript
resolverExecutedTrigger({
  resolver: createOrderResolver,
  condition: ({ result, error }) => !error && result?.order?.id,
});
```

### IdP User Triggers

Fire when IdP users are created, updated, or deleted:

* `idpUserCreatedTrigger()`: Fires when a new IdP user is created
* `idpUserUpdatedTrigger()`: Fires when an IdP user is updated
* `idpUserDeletedTrigger()`: Fires when an IdP user is deleted

```typescript
idpUserCreatedTrigger();
```

When the project defines multiple IdPs, pass `idp` to target a specific one. The name is type-narrowed via the generated `IdpName` type:

```typescript
idpUserCreatedTrigger({ idp: "my-idp" });
```

Omitting `idp` is allowed only when the project has exactly one IdP; otherwise `deploy` fails with an error listing the configured IdPs.

These triggers require the IdP to publish user lifecycle events. `deploy` enables `publishEvents` automatically on each IdP targeted by an `idpUser` trigger taking part in the same run, and turns it back off once no such trigger remains; set the value explicitly on `defineIdp()` to pin it. See [IdP service - publishEvents](idp.md#publishevents).

### Auth Access Token Triggers

Fire on auth access token lifecycle events:

* `authAccessTokenIssuedTrigger()`: Fires when a new access token is issued
* `authAccessTokenRefreshedTrigger()`: Fires when an access token is refreshed
* `authAccessTokenRevokedTrigger()`: Fires when an access token is revoked

```typescript
authAccessTokenIssuedTrigger();
```

### Workflow Execution Triggers

Fire when a workflow execution changes state. Use the single-event helpers or `workflowExecutionTrigger()` for multiple events:

```typescript
import { createExecutor, workflowExecutionTrigger } from "@tailor-platform/sdk";
import orderWorkflow from "../workflows/order";

export default createExecutor({
  name: "order-workflow-finished",
  trigger: workflowExecutionTrigger({
    workflow: orderWorkflow,
    events: ["completed", "retried"],
  }),
  operation: {
    kind: "function",
    body: async (args) => {
      if (args.event === "completed" && !args.success) {
        console.error(args.error);
      }
    },
  },
});
```

The available workflow events are `started`, `completed`, `retried`, `resumed`, `wait_started`, and `wait_resolved`. To observe job-level events, use `workflowJobExecutionStartedTrigger()`, `workflowJobExecutionCompletedTrigger()`, `workflowJobExecutionWaitStartedTrigger()`, `workflowJobExecutionWaitResolvedTrigger()`, or `workflowJobExecutionTrigger()`.

`completed` events include `success`; when it is `false`, `error` contains the failure message. A job released from a wait point emits `wait_resolved` instead of `completed`.

These triggers require the workflow to publish execution events. `deploy` enables `publishEvents` automatically on each targeted workflow, and on every job of a workflow targeted by a `workflowJobExecution*` trigger, and turns it back off once no such trigger remains; set the value explicitly to pin it. See [Workflow service - Execution Events](workflow.md#execution-events).

### Multi-Event Triggers

Handle multiple event types in a single executor using multi-event trigger factories. These accept an `events` array of short event names:

#### `recordTrigger()`

```typescript
import { createExecutor, recordTrigger } from "@tailor-platform/sdk";
import { user } from "../tailordb/user";

export default createExecutor({
  name: "user-changed",
  trigger: recordTrigger({
    type: user,
    events: ["created", "updated"],
  }),
  operation: {
    kind: "function",
    body: async (args) => {
      if (args.event === "created") {
        console.log("User created:", args.newRecord.name);
      }
      if (args.event === "updated") {
        console.log("User updated:", args.oldRecord.name, "->", args.newRecord.name);
      }
    },
  },
});
```

#### `idpUserTrigger()`

```typescript
idpUserTrigger({ events: ["created", "deleted"] });
```

In multi-IdP projects, add `idp` to target a specific IdP:

```typescript
idpUserTrigger({ events: ["created", "deleted"], idp: "my-idp" });
```

#### `authAccessTokenTrigger()`

```typescript
authAccessTokenTrigger({ events: ["issued", "revoked"] });
```

#### `workflowExecutionTrigger()` and `workflowJobExecutionTrigger()`

```typescript
workflowExecutionTrigger({ workflow: orderWorkflow, events: ["started", "completed"] });
workflowJobExecutionTrigger({ workflow: orderWorkflow, events: ["started", "wait_resolved"] });
```

The `event` field on args matches the short event name, enabling type narrowing. Record triggers use names such as `"created"`, auth token triggers use `"issued"`, and workflow triggers use `"started"`, `"completed"`, and `"wait_resolved"`. The `rawEvent` field contains the full event type string (e.g., `"tailordb.type_record.created"`).

## Operation Types

### Function Operation

Execute JavaScript/TypeScript functions:

```typescript
createExecutor({
  operation: {
    kind: "function",
    body: async ({ newRecord, env }) => {
      console.log(`New record created in ${env.bar}:`, newRecord);
    },
  },
});
```

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

For long-running operations, use `jobFunction` which runs asynchronously and supports extended execution times. See [Job Function Operation](/guides/executor/job-function-operation) for details.

```typescript
import { createExecutor, scheduleTrigger } from "@tailor-platform/sdk";
import { getDB } from "../generated/tailordb";

export default createExecutor({
  name: "daily-report-generator",
  description: "Generate daily reports",
  trigger: scheduleTrigger({ cron: "0 0 * * *" }),
  operation: {
    kind: "jobFunction",
    body: async () => {
      const db = getDB("tailordb");
      // Long-running report generation logic
      const records = await db.selectFrom("Order").selectAll().execute();
      // Process records...
    },
  },
});
```

### Webhook Operation

Call external webhooks with dynamic data:

```typescript
createExecutor({
  operation: {
    kind: "webhook",
    url: ({ typeName }) => `https://api.example.com/webhooks/${typeName}`,
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": { vault: "api-keys", key: "external-api" },
    },
    requestBody: ({ newRecord }) => ({
      id: newRecord.id,
      timestamp: new Date(),
      data: newRecord,
    }),
  },
});
```

### GraphQL Operation

Execute GraphQL queries and mutations:

```typescript
createExecutor({
  operation: {
    kind: "graphql",
    appName: "my-app",
    query: `
      mutation UpdateUserStatus($id: ID!, $status: String!) {
        updateUser(id: $id, input: { status: $status }) {
          id
          status
          updatedAt
        }
      }
    `,
    variables: ({ newRecord }) => ({
      id: newRecord.userId,
      status: "active",
    }),
  },
});
```

### Workflow Operation

Trigger workflows from executors. See [Workflow documentation](workflow) for how to define workflows.

```typescript
import { createExecutor, recordCreatedTrigger } from "@tailor-platform/sdk";
import { order } from "../tailordb/order";
import processOrderWorkflow from "../workflows/process-order";

export default createExecutor({
  name: "order-processor",
  description: "Process new orders via workflow",
  trigger: recordCreatedTrigger({ type: order }),
  operation: {
    kind: "workflow",
    workflow: processOrderWorkflow,
    args: ({ newRecord }) => ({
      orderId: newRecord.id,
      customerId: newRecord.customerId,
    }),
  },
});
```

You can also pass static arguments:

```typescript
createExecutor({
  operation: {
    kind: "workflow",
    workflow: dailyReportWorkflow,
    args: { reportType: "summary" },
  },
});
```

`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`, `function`, `jobFunction`, 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";

export default createExecutor({
  name: "scheduled-cleanup",
  trigger: scheduleTrigger({ cron: "0 0 * * *" }),
  operation: {
    kind: "graphql",
    query: `mutation { cleanupOldRecords { count } }`,
    invoker: "batch-processor",
  },
});
```

The machine user is resolved in your application's auth namespace — the name of your Auth service, local or external. `webhook` is the only operation kind that does not accept `invoker`, since it calls an external URL rather than acting inside your workspace.

Without an `invoker`, the operation runs as whoever raised the trigger event, or anonymously when there is no such principal — as with a `schedule` trigger. Declare an `invoker` whenever the operation needs an identity of its own.

## Event Payloads

Each trigger type provides specific context data in the callback functions.

### Record Event Payloads

Record triggers receive context based on the operation type:

#### Created Event

```typescript
interface RecordCreatedContext<T> {
  event: "created"; // Short event name for type narrowing
  rawEvent: "tailordb.type_record.created"; // Full event type string
  workspaceId: string; // Workspace identifier
  appNamespace: string; // Application/namespace name
  typeName: string; // TailorDB table name
  newRecord: T; // The newly created record
}
```

#### Updated Event

```typescript
interface RecordUpdatedContext<T> {
  event: "updated";
  rawEvent: "tailordb.type_record.updated";
  workspaceId: string;
  appNamespace: string;
  typeName: string;
  oldRecord: T; // Previous record state
  newRecord: T; // Current record state
}
```

#### Deleted Event

```typescript
interface RecordDeletedContext<T> {
  event: "deleted";
  rawEvent: "tailordb.type_record.deleted";
  workspaceId: string;
  appNamespace: string;
  typeName: string;
  oldRecord: T; // The deleted record
}
```

**Usage Example:**

```typescript
import { createExecutor, recordUpdatedTrigger, t } from "@tailor-platform/sdk";
import { order } from "../tailordb/order";

export default createExecutor({
  name: "order-status-changed",
  trigger: recordUpdatedTrigger({
    type: order,
    condition: ({ oldRecord, newRecord }) => oldRecord.status !== newRecord.status,
  }),
  operation: {
    kind: "function",
    body: async ({ oldRecord, newRecord, typeName }) => {
      console.log(`${typeName} status changed:`);
      console.log(`  From: ${oldRecord.status}`);
      console.log(`  To: ${newRecord.status}`);
    },
  },
});
```

### Schedule Event Payload

Schedule triggers receive minimal context:

```typescript
interface ScheduleContext {
  scheduledTime: string; // ISO 8601 timestamp
}
```

### Incoming Webhook Payload

Webhook triggers receive HTTP request data:

```typescript
interface WebhookContext<T = unknown> {
  body: T; // Parsed request body
  headers: Record<string, string>; // Request headers
  method: "POST" | "GET" | "PUT" | "DELETE"; // HTTP method
  rawBody: string; // Raw request body as string
}
```

**Usage Example:**

```typescript
import { createExecutor, incomingWebhookTrigger } from "@tailor-platform/sdk";

interface StripeWebhook {
  type: string;
  data: { object: { id: string; amount: number } };
}

export default createExecutor({
  name: "stripe-webhook",
  trigger: incomingWebhookTrigger<{
    body: StripeWebhook;
    headers: { "stripe-signature": string };
  }>(),
  operation: {
    kind: "function",
    body: async ({ body, headers }) => {
      const signature = headers["stripe-signature"];
      console.log(`Received ${body.type} event`);
      // Process webhook...
    },
  },
});
```

**With custom response:**

```typescript
export default createExecutor({
  name: "slack-challenge",
  trigger: incomingWebhookTrigger<{
    body: { challenge: string; type: string };
    headers: Record<string, string>;
  }>({
    response: (args) => ({ challenge: args.body.challenge }),
  }),
  operation: {
    kind: "function",
    body: async ({ body }) => {
      console.log(`Received ${body.type} event`);
    },
  },
});
```

### Resolver Executed Payload

Resolver triggers receive the resolver's result or error:

```typescript
interface ResolverExecutedContext<TResult> {
  workspaceId: string; // Workspace identifier
  appNamespace: string; // Application/namespace name
  resolverName: string; // Name of the executed resolver
  result?: TResult; // Return value (on success)
  error?: string; // Error message (on failure)
}
```

**Usage Example:**

```typescript
import { createExecutor, resolverExecutedTrigger } from "@tailor-platform/sdk";
import { createOrderResolver } from "../resolvers/create-order";

export default createExecutor({
  name: "order-created-notification",
  trigger: resolverExecutedTrigger({
    resolver: createOrderResolver,
    condition: ({ result, error }) => !error && !!result?.order,
  }),
  operation: {
    kind: "function",
    body: async ({ result, resolverName }) => {
      console.log(`${resolverName} completed successfully`);
      console.log(`Order ID: ${result.order.id}`);
    },
  },
});
```

### IdP User Event Payload

IdP user triggers receive user context:

```typescript
interface IdpUserContext {
  event: "created" | "updated" | "deleted"; // Short event name
  rawEvent: string; // Full event type (e.g., "idp.user.created")
  namespaceName: string; // IdP namespace name
  userId: string; // The affected user ID
}
```

### Auth Access Token Event Payload

Auth access token triggers receive token context:

```typescript
interface AuthAccessTokenContext {
  event: "issued" | "refreshed" | "revoked"; // Short event name
  rawEvent: string; // Full event type (e.g., "auth.access_token.issued")
  namespaceName: string; // Auth namespace name
  userId: string; // The user associated with the token
}
```

### Workflow Execution Event Payload

Workflow execution triggers receive execution context:

```typescript
interface WorkflowExecutionContext {
  workspaceId: string; // Workspace identifier
  env: TailorEnv; // Environment variables from tailor.config.ts
  actor: TailorActor | null; // Principal that triggered the workflow
  workflowId: string; // Workflow resource ID
  workflowName: string; // Workflow name
  workflowExecutionId: string; // Workflow execution ID
  event: "started" | "completed" | "retried" | "resumed" | "wait_started" | "wait_resolved";
  rawEvent: string; // Full event type
}
```

Completed events narrow on `success`. Failed executions include `error`; retried executions include `retryCount` and `retryAfter`.

```typescript
body: async (args) => {
  if (args.event === "completed" && !args.success) {
    console.error(args.error);
  }
};
```

### Workflow Job Execution Event Payload

Workflow job execution triggers include every `WorkflowExecutionContext` field above, plus job-specific fields:

```typescript
interface WorkflowJobExecutionContext {
  workflowJobExecutionId: string; // Job execution ID
  jobFunctionName: string; // Name passed to createWorkflowJob
  event: "started" | "completed" | "wait_started" | "wait_resolved";
  rawEvent: string; // Full event type
}
```

`wait_started` events include `waitKey`, plus JSON-serialized `waitPayload` when the wait point recorded one; `wait_resolved` events include `waitKey`.

---

---
url: https://docs.tailor.tech/sdk/services/http-adapter.md
---
# HTTP Adapter

HTTP adapters expose REST-style HTTP endpoints on your application by translating each request into a GraphQL query and (optionally) reshaping the GraphQL response back into an HTTP response.

## Overview

Each HTTP adapter is a single file that declares:

* A `pathPattern` (which methods it handles is derived from the `input` keys)
* An `input` object keyed by lowercase HTTP method (`get`, `post`, `put`, `patch`, `delete`) — each value is a function that converts an incoming HTTP request into a GraphQL request (`query`, `variables`, `operationName`). `query` can be a GraphQL string or a generated `TypedDocumentNode`.
* An optional `output` function — **shared across all methods** — that converts the GraphQL response into an HTTP response (`statusCode`, `headers`, `body`)

Adapters are deployed together with your application. When a request arrives under the `/api/` prefix and matches an adapter, the handler for the request method runs server-side.

For the official Tailor Platform documentation — including the exact URL routing, request/response body limits, execution timeouts, and CORS handling — see https://docs.tailor.tech/.

## Requirements

* Each adapter file must `export default` the result of `createHttpAdapter`; files matched by the glob without one (e.g. shared helpers) are ignored
* `name` must match `^[a-z0-9][a-z0-9-]{1,61}[a-z0-9]$` and be unique across all adapters
* `input` must declare at least one method handler
* All handlers **must be synchronous** — `async`/`await` is rejected at build time

## Constraints

Handlers run server-side and **must be synchronous**: `async`/`await`, Promises, `fetch`, Node APIs (`fs`, `path`, `crypto`, …), and top-level `await` are not available. `async`/`await` and Node built-in imports are rejected at build time. Each adapter's built output (including imported helpers) is capped at 256 KB, with a warning above 64 KB.

Request/response body size, execution timeout, and other limits are enforced by the platform — see the platform documentation linked above.

## Configuration

Add an `httpAdapter` entry to `defineConfig`:

```typescript
// tailor.config.ts
import { defineConfig } from "@tailor-platform/sdk";

export default defineConfig({
  name: "my-app",
  httpAdapter: {
    files: ["adapters/**/*.ts"],
  },
});
```

## Defining an Adapter

```typescript
// adapters/user.ts
import { createHttpAdapter } from "@tailor-platform/sdk";

export default createHttpAdapter({
  name: "user",
  pathPattern: "/users/*",
  input: {
    get: (req) => ({
      query: `query GetUser($id: ID!) { user(id: $id) { id name email } }`,
      variables: { id: req.path.split("/")[2] },
    }),
    post: (req) => ({
      query: `mutation CreateUser($input: CreateUserInput!) { createUser(input: $input) { id } }`,
      variables: { input: JSON.parse(req.body) },
    }),
  },
  output: (resp) => ({
    statusCode: 200,
    headers: { "content-type": "application/json" },
    body: JSON.stringify(resp.data ?? null),
  }),
});
```

A request to `GET /api/users/abc-123` invokes the `get` handler, runs the resulting GraphQL query against your application's GraphQL endpoint (with the caller's auth context preserved), then invokes `output(resp)` to produce the HTTP response. A `POST /api/users/...` would instead invoke the `post` handler with the same shared `output`.

If `output` is omitted, the raw GraphQL response is returned as JSON.

### Typed GraphQL Documents

`input` handlers can return generated `TypedDocumentNode` values instead of query strings. The SDK uses the document's variables type for `variables`, and passes the document's result type to `output` as `resp.data`.

```typescript
import { GetUserDocument } from "../generated/graphql";

get: (req) => ({
  query: GetUserDocument,
  variables: { id: req.path.split("/")[2] ?? "" },
});
```

When multiple methods return different typed documents, `resp.data` is the union of those result types because `output` is shared across the adapter. If a method returns a plain string query, its result type is `unknown`. When extracting an input handler and annotating it separately, pass the document type to `HttpAdapterInputFn` so required variables stay typed.

### Optional fields

Beyond `name`, `pathPattern`, `input`, and `output`, two optional fields control deploy-time behavior:

* `enabled` (default `true`) — set to `false` to deploy the adapter in a disabled state without removing its file. A disabled adapter is uploaded but not served.
* `priority` (non-negative integer, default `0`) — when multiple adapters' `pathPattern`s match the same request path, the adapter with the **lowest** `priority` value wins.

### Why is `output` shared instead of per-method?

`input` and `output` run **in isolation** and cannot share any state; `output` only receives the GraphQL response (not the original request or method). `output` is primarily intended for reshaping the response format (e.g. JSON to XML) — method-specific processing is expected to be handled on the `input`/resolver side. For per-method response shaping, discriminate inside `output` based on the response data shape.

## Path Pattern

`pathPattern` is matched against the request path **after** the `/api/` prefix.

* Literal segments must match exactly
* A `*` in the middle of the pattern matches exactly one path segment (`/users/*/items`)
* A trailing `*` matches the remaining path (`/users/*`)

Exact matching semantics (trailing-slash handling, percent-encoding, etc.) are defined by the platform — refer to the platform documentation for details.

## Types

The request/response shapes (`HttpAdapterRequest`, `HttpAdapterGraphQLRequest`, `HttpAdapterGraphQLResponse`, `HttpAdapterResponse`, …) are exported from `@tailor-platform/sdk`; refer to the type definitions in your editor rather than this document.

---

---
url: https://docs.tailor.tech/sdk/services/idp.md
---
# IdP (Identity Provider)

IdP is a built-in identity provider service for managing user authentication.

## Overview

The Built-in IdP provides:

* User registration and authentication
* OAuth client management
* Integration with Auth service

For the official Tailor Platform documentation, see [Identity Provider Setup](/tutorials/setup-auth/setup-identity-provider).

## Configuration

Configure the Built-in IdP using `defineIdp()`:

**Definition Rules:**

* **Multiple IdPs allowed**: You can define multiple IdP instances in your config file
* **Configuration location**: Define in `tailor.config.ts` and add to the `idp` array
* **Uniqueness**: IdP names must be unique across all IdP instances

```typescript
import { defineIdp, defineConfig } from "@tailor-platform/sdk";

const idp = defineIdp("my-idp", {
  clients: ["my-client"],
  permission: {
    create: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    read: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    update: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    delete: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    sendPasswordResetEmail: [{ conditions: [], permit: false }],
  },
});

// You can define multiple IdPs
const anotherIdp = defineIdp("another-idp", {
  clients: ["another-client"],
  permission: {
    create: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    read: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    update: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    delete: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    sendPasswordResetEmail: [{ conditions: [], permit: false }],
  },
});

export default defineConfig({
  idp: [idp, anotherIdp], // Add all IdPs to the array
});
```

## Options

### permission

Per-operation permission policies for IdP user management. Controls who can create, read, update, delete users, and send password reset emails.

```typescript
defineIdp("my-idp", {
  clients: ["my-client"],
  permission: {
    create: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    read: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    update: [
      {
        conditions: [
          [{ user: "role" }, "=", "ADMIN"],
          [{ newIdpUser: "name" }, "!=", { oldIdpUser: "name" }],
        ],
        permit: true,
      },
    ],
    delete: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    sendPasswordResetEmail: [{ conditions: [], permit: false }],
  },
});
```

**Operations:**

* `create` - Controls who can create IdP users
* `read` - Controls who can read IdP users
* `update` - Controls who can update IdP users
* `delete` - Controls who can delete IdP users
* `sendPasswordResetEmail` - Controls who can send password reset emails. Required unless `userAuthPolicy.disablePasswordAuth` is `true` or `gqlOperations.sendPasswordResetEmail` is `false` (the password-reset flow has no meaning when password authentication is off or the operation is disabled). Set `[{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }]` to allow, or `[]` to deny.
* `unenrollMfa` - Controls who can remove an enrolled MFA factor from a user. Required when `userAuthPolicy.enableMfa` is `true` unless `gqlOperations.unenrollMfa` is `false`; omit otherwise. Typically restricted to administrators.

**Policy fields:** each entry in an operation's policy array supports:

* `conditions` - Array of conditions evaluated for the policy (see Operands/Operators below)
* `permit` - Whether to allow (`true`) or deny (`false`) when the conditions match
* `description` - (Optional) Human-readable description of the policy

**Operands:**

* `{ user: "field" }` - Authenticated user's attribute. Built-in fields: `"id"` (user ID), `"_loggedIn"` (boolean, whether the user is authenticated). User-defined attributes (e.g., `"role"`) are also available when configured via `userProfile.attributes` or `machineUserAttributes` in `defineAuth()`
* `{ idpUser: "field" }` - IdP user field (for create/read/delete). Allowed values: `"id"`, `"name"`, `"disabled"`
* `{ oldIdpUser: "field" }` - Previous IdP user field value (for update only). Allowed values: `"id"`, `"name"`, `"disabled"`
* `{ newIdpUser: "field" }` - New IdP user field value (for update only). Allowed values: `"id"`, `"name"`, `"disabled"`
* Literal values: `string`, `boolean`, `string[]`, `boolean[]`

**Operators:** `"="`, `"!="`, `"in"`, `"not in"`

**Helper:** `unsafeAllowAllIdPPermission` grants full access without conditions. Intended only for development and testing.

```typescript
import { unsafeAllowAllIdPPermission } from "@tailor-platform/sdk";

defineIdp("my-idp", {
  clients: ["my-client"],
  permission: unsafeAllowAllIdPPermission,
});
```

### clients

OAuth client names that can use this IdP:

```typescript
defineIdp("my-idp", {
  clients: ["default-client", "mobile-client"],
});
```

### userAuthPolicy

User authentication policy. Controls password requirements, the identifier used for login, allowed email domains, and social login providers. Every field is optional. The boolean options default to disabled, and the password length fields default to a minimum of 6 and a maximum of 4096.

```typescript
defineIdp("my-idp", {
  clients: ["my-client"],
  userAuthPolicy: {
    useNonEmailIdentifier: false,
    allowSelfPasswordReset: true,
    passwordRequireUppercase: true,
    passwordRequireLowercase: true,
    passwordRequireNonAlphanumeric: true,
    passwordRequireNumeric: true,
    passwordMinLength: 8,
    passwordMaxLength: 128,
  },
});
```

**Login behavior:**

* `useNonEmailIdentifier` - Allow a non-email identifier (username) instead of requiring an email address. Default `false`.
* `allowSelfPasswordReset` - Show the "Forgot password?" flow so users can reset their own password. Default `false`.
* `disablePasswordAuth` - Remove password authentication entirely. Default `false`. Requires at least one social login provider to be enabled.

**Password requirements:**

* `passwordRequireUppercase` - Require at least one uppercase letter. Default `false`.
* `passwordRequireLowercase` - Require at least one lowercase letter. Default `false`.
* `passwordRequireNumeric` - Require at least one numeric character. Default `false`.
* `passwordRequireNonAlphanumeric` - Require at least one non-alphanumeric character. Default `false`.
* `passwordMinLength` - Minimum password length. Must be between 6 and 30. Default `6`.
* `passwordMaxLength` - Maximum password length. Must be between 6 and 4096. Default `4096`.

**Email domains and social login:**

* `allowedEmailDomains` - Restrict registration to these email domains. An empty list (the default) allows all domains, but a non-empty list is required when `allowGoogleOauth` or `allowMicrosoftOauth` is enabled.
* `allowGoogleOauth` - Enable the "Sign in with Google" button. Default `false`.
* `allowMicrosoftOauth` - Enable the "Sign in with Microsoft" button. Default `false`.

**MFA (TOTP):**

```typescript
import { defineIdp, defineStaticWebSite } from "@tailor-platform/sdk";

const website = defineStaticWebSite("my-frontend", { description: "App frontend" });

defineIdp("my-idp", {
  clients: ["my-client"],
  userAuthPolicy: {
    enableMfa: true,
    requireMfa: false,
    allowedReturnOrigins: [website.url, "https://admin.example.com"],
    mfaIssuer: "My App",
  },
  permission: {
    create: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    read: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    update: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    delete: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    sendPasswordResetEmail: [{ conditions: [[{ user: "_loggedIn" }, "=", true]], permit: true }],
    unenrollMfa: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
  },
});
```

* `enableMfa` - Make TOTP MFA available for users in this namespace. Default `false`. When enabled, users can register an authenticator app (Google Authenticator, 1Password, etc.) from the IdP self-service page.
* `requireMfa` - Force password-authenticated users to enroll and pass an MFA challenge on each sign-in. Default `false`. Social sign-in (`allowGoogleOauth` / `allowMicrosoftOauth`) is not affected; the upstream provider's MFA covers those sessions.
* `allowedReturnOrigins` - Origins the IdP self-service pages (such as `/mfa/settings`) are allowed to redirect back to. Each entry is either a literal origin (`https://app.example.com`, scheme + host + optional port, no path/query/fragment) or a static-website placeholder `<name>:url` (e.g. `website.url`) that the CLI resolves to the deployed website's URL at deployment time. Required when `enableMfa` is `true`.
* `mfaIssuer` - Label shown next to the user account in authenticator apps when TOTP is enrolled. Up to 64 characters. Falls back to `"Tailor Platform IdP"` when empty.

**Constraints:** the following combinations are rejected at parse time.

* `passwordMinLength` must be less than or equal to `passwordMaxLength`.
* A non-empty `allowedEmailDomains` cannot be combined with `useNonEmailIdentifier: true` (an empty list is allowed). Enabling `allowGoogleOauth` or `allowMicrosoftOauth` is likewise rejected with `useNonEmailIdentifier: true` (leaving them `false` or unset is fine).
* `allowGoogleOauth` requires a non-empty `allowedEmailDomains`.
* `allowMicrosoftOauth` requires both a non-empty `allowedEmailDomains` and `disablePasswordAuth: true`.
* `disablePasswordAuth` requires `allowGoogleOauth` or `allowMicrosoftOauth`, and cannot be combined with `allowSelfPasswordReset`.
* `requireMfa: true` requires `enableMfa: true`.
* `enableMfa: true` requires at least one entry in `allowedReturnOrigins`.
* `enableMfa: true` requires `permission` to be defined and to include an explicit `unenrollMfa` policy (an empty array `[]` to deny is fine), unless `gqlOperations.unenrollMfa` is `false` (or `gqlOperations: "query"`, which normalizes to the same), in which case the operation is turned off and the policy may be omitted.

**Runtime API:** function code can inspect and revoke a user's enrolled factor through `idp.Client`. The `User` records returned by `user`, `userByName`, `users`, `createUser`, and `updateUser` expose `mfaEnrolled` (boolean) and `mfaFactorIds` (string array), and `client.unenrollMfa({ userId, mfaFactorId })` removes a single factor. The factor ID to pass back is one of the entries in `user.mfaFactorIds`. Calling `unenrollMfa` requires the `unenrollMfa` permission above.

```typescript
import { idp } from "@tailor-platform/sdk/runtime";

const client = new idp.Client({ namespace: "my-idp" });
const user = await client.user("user-id");
if (user.mfaEnrolled) {
  for (const factorId of user.mfaFactorIds) {
    await client.unenrollMfa({ userId: user.id, mfaFactorId: factorId });
  }
}
```

### gqlOperations

Controls which GraphQL user-management operations the IdP exposes. All operations are enabled by default. Use this to turn operations off entirely, independent of the `permission` policies that decide who may call them.

```typescript
defineIdp("my-idp", {
  clients: ["my-client"],
  gqlOperations: {
    create: true,
    read: true,
    update: true,
    delete: false,
    sendPasswordResetEmail: false,
    requestMfaSettingsUrl: false,
    unenrollMfa: false,
  },
});
```

**Fields:** each field defaults to `true` (enabled). Set a field to `false` to disable that operation.

* `create` - The `_createUser` mutation.
* `read` - The `_users` and `_user` query operations.
* `update` - The `_updateUser` mutation.
* `delete` - The `_deleteUser` mutation.
* `sendPasswordResetEmail` - The `_sendPasswordResetEmail` mutation.
* `requestMfaSettingsUrl` - The `_requestMfaSettingsUrl` query that issues a self-service URL for MFA settings.
* `unenrollMfa` - The `_unenrollMfa` mutation that removes a user's enrolled MFA factor. When set to `false`, `permission.unenrollMfa` may be omitted even with `userAuthPolicy.enableMfa: true`.

**Shortcut:** pass the string `"query"` to expose a read-only IdP. It enables the queries (`read`, `requestMfaSettingsUrl`) and disables every mutation.

```typescript
defineIdp("my-idp", {
  clients: ["my-client"],
  gqlOperations: "query",
});
```

### authorization (optional, legacy)

Legacy access control field. Use `permission` instead for fine-grained per-operation control. This field is kept for backward compatibility.

```typescript
defineIdp("my-idp", {
  clients: ["default-client"],
  authorization: "loggedIn", // Only logged-in users can manage
});
```

**Values:**

* `"insecure"` - No authentication required (use only for development)
* `"loggedIn"` - Requires authenticated user
* `{ cel: "<expression>" }` - Custom authorization logic using CEL

### emailConfig

Namespace-level email configuration defaults. Per-request values take priority over these defaults.

```typescript
defineIdp("my-idp", {
  clients: ["my-client"],
  permission: {
    create: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    read: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    update: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    delete: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    sendPasswordResetEmail: [{ conditions: [], permit: false }],
  },
  emailConfig: {
    fromName: "My App",
    passwordResetSubject: "Reset your password",
  },
});
```

**Fields:**

* `fromName` - Default sender display name for emails. Empty means use mailer default.
* `passwordResetSubject` - Default subject for password reset emails. Empty means use localized default.

**Validation:** Each field must be 200 characters or less and must not contain newline characters.

### lang

UI language for the IdP-hosted pages such as the login and password reset screens.

```typescript
defineIdp("my-idp", {
  clients: ["my-client"],
  lang: "ja",
});
```

**Values:** `"en"` or `"ja"`.

### publishEvents

Publish IdP user lifecycle events (`idp.user.created`, `idp.user.updated`, `idp.user.deleted`). These events are consumed by executors that use `idpUserCreatedTrigger`, `idpUserUpdatedTrigger`, `idpUserDeletedTrigger`, or `idpUserTrigger`.

```typescript
defineIdp("my-idp", {
  clients: ["my-client"],
  publishEvents: true,
});
```

**Auto-configuration:** When `publishEvents` is omitted, `deploy` sets it from the executors taking part in the same run: `true` while one of their `idpUser` triggers targets this IdP, and `false` once none does. Removing the last such trigger turns publishing back off on the next `deploy`, as does disabling the last executor that carries one. Targeting is per-IdP: an executor specifies which IdP it subscribes to via the trigger's `idp` option (required in multi-IdP projects). Set the value explicitly to override:

* `publishEvents: true`: always publish events.
* `publishEvents: false`: never publish events. `deploy` rejects this with an error if an `idpUser` trigger taking part in the same run targets this IdP — either remove `publishEvents: false` or remove the matching trigger.

**Sharing an IdP across configs:** an executor in another config auto-enables publishing the same way, as long as both configs take part in the same `deploy` (`--config a,b`). `deploy` records that dependency, so deploying the owning config alone later asks for confirmation instead of silently turning publishing off — it fails outright in a non-interactive environment. Set `publishEvents: true` on the IdP to keep it on regardless of which configs take part.

## Using idp.provider()

The `idp.provider()` method creates a type-safe reference to the IdP for use in Auth configuration. The client name is validated at compile time against the clients defined in the IdP.

```typescript
import { defineIdp, defineAuth, defineConfig } from "@tailor-platform/sdk";
import { user } from "./tailordb/user";

const idp = defineIdp("my-idp", {
  clients: ["default-client", "mobile-client"],
  permission: {
    create: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    read: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    update: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    delete: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
    sendPasswordResetEmail: [{ conditions: [], permit: false }],
  },
});

const auth = defineAuth("my-auth", {
  userProfile: {
    type: user,
    usernameField: "email",
    attributes: { role: true },
  },
  // Type-safe: only "default-client" or "mobile-client" are allowed
  idProvider: idp.provider("my-provider", "default-client"),
});

export default defineConfig({
  idp: [idp],
  auth,
});
```

**Parameters:**

```typescript
idp.provider(
  "provider-name", // Name for the provider reference
  "client-name", // Must be one of the clients defined in the IdP
);
```

The second argument only accepts client names that were defined in the `clients` array of the IdP configuration.

---

---
url: https://docs.tailor.tech/sdk/services/resolver.md
---
# Resolver

Resolvers are custom GraphQL endpoints with business logic that execute on the Tailor Platform.

## Overview

Resolvers provide:

* Custom GraphQL queries and mutations
* Type-safe input/output schemas
* Access to TailorDB via Kysely query builder
* User context for authentication/authorization

## Comparison with Tailor Platform Pipeline Resolver

The SDK's Resolver is a simplified version of Tailor Platform's [Pipeline Resolver](/guides/resolver).

| Pipeline Resolver                        | SDK Resolver                      |
| ---------------------------------------- | --------------------------------- |
| Multiple steps with different operations | Single `body` function            |
| Declarative step configuration           | Imperative TypeScript code        |
| Built-in TailorDB/GraphQL steps          | Direct database access via Kysely |
| CEL expressions for data transformation  | Native TypeScript transformations |

### Example Comparison

**Pipeline Resolver (Tailor Platform native):**

```yaml
steps:
  - name: getUser
    operation: tailordb.query
    params:
      type: User
      filter:
        email: { eq: "{{ input.email }}" }
  - name: updateAge
    operation: tailordb.mutation
    params:
      type: User
      id: "{{ steps.getUser.id }}"
      input:
        age: "{{ steps.getUser.age + 1 }}"
```

**Resolver (SDK):**

```typescript
createResolver({
  name: "incrementUserAge",
  operation: "mutation",
  input: { email: t.string() },
  body: async (context) => {
    const db = getDB("tailordb");
    const user = await db
      .selectFrom("User")
      .selectAll()
      .where("email", "=", context.input.email)
      .executeTakeFirstOrThrow();

    await db
      .updateTable("User")
      .set({ age: user.age + 1 })
      .where("id", "=", user.id)
      .execute();

    return { oldAge: user.age, newAge: user.age + 1 };
  },
  output: t.object({ oldAge: t.int(), newAge: t.int() }),
});
```

## Creating a Resolver

Define resolvers in files matching glob patterns specified in `tailor.config.ts`.

**Definition Rules:**

* **One resolver per file**: Each file must contain exactly one resolver definition
* **Export method**: Must use `export default`
* **Uniqueness**: Resolver names must be unique per namespace

```typescript
import { createResolver, t } from "@tailor-platform/sdk";

export default createResolver({
  name: "add",
  operation: "query",
  input: {
    left: t.int(),
    right: t.int(),
  },
  body: (context) => {
    return {
      result: context.input.left + context.input.right,
    };
  },
  output: t.object({
    result: t.int(),
  }),
});
```

## Input/Output Schemas

Define input/output schemas using methods of `t` object. Basic usage and supported field types are the same as TailorDB. TailorDB-specific options (e.g., index, relation) are not supported.

You can reuse fields defined with `db` object, but note that unsupported options will be ignored:

```typescript
const user = db.table("User", {
  name: db.string().unique(),
  age: db.int(),
});

createResolver({
  input: {
    name: user.fields.name,
  },
});
```

### Custom Type Name (`typeName`)

Enum and nested object fields in input/output schemas generate protobuf type names automatically (e.g., `{ResolverName}{FieldName}`). Use `typeName()` to set a custom name:

```typescript
createResolver({
  name: "createOrder",
  operation: "mutation",
  input: {
    address: t
      .object({
        street: t.string(),
        city: t.string(),
        zip: t.string(),
      })
      .typeName("ShippingAddress"),
    status: t.enum(["pending", "confirmed", "shipped"]).typeName("OrderStatus"),
  },
  // ...
});
```

**Constraints:**

* Only available on `enum()` and `object()` fields — calling on scalar types is a compile error
* Cannot be called twice on the same field
* Can be chained with `description()`

This is useful when the same logical type appears in multiple resolvers or when you want a predictable, human-readable name in the generated GraphQL schema.

**Warning:** Do not set `typeName` to an existing TailorDB table name on an `object()` that contains enum or nested fields. Child fields without an explicit `typeName` auto-generate names using `{parentTypeName}{FieldName}`, which can collide with the TailorDB table's own enum/nested type names.

```typescript
// Collision — "Item" + "status" auto-generates "ItemStatus",
//   which collides with the TailorDB Item table's status enum
output: t
  .object({
    id: t.uuid(),
    status: t.enum(["ACTIVE", "INACTIVE"]),
  })
  .typeName("Item"),

// OK — use a distinct name that won't collide
output: t
  .object({
    id: t.uuid(),
    status: t.enum(["ACTIVE", "INACTIVE"]),
  })
  .typeName("DeactivateItemOutput"),

// OK — explicitly set typeName on child enum too
output: t
  .object({
    id: t.uuid(),
    status: t.enum(["ACTIVE", "INACTIVE"]).typeName("DeactivateItemStatus"),
  })
  .typeName("Item"),
```

## Input Validation

Add validation rules to input fields using the `validate` method:

```typescript
createResolver({
  name: "createUser",
  operation: "mutation",
  input: {
    email: t
      .string()
      .validate(
        ({ value }) => value.includes("@"),
        [({ value }) => value.length <= 255, "Email must be 255 characters or less"],
      ),
    age: t.int().validate(({ value }) => value >= 0 && value <= 150),
  },
  body: (context) => {
    // Input is validated before body executes
    return { email: context.input.email };
  },
  output: t.object({ email: t.string() }),
});
```

Validation functions receive:

* `value` - The field value being validated
* `data` - The entire input object
* `invoker` - The principal performing the operation

You can specify validation as:

* A function returning `boolean` (uses default error message)
* A tuple of `[function, errorMessage]` for custom error messages
* Multiple validators (pass multiple arguments to `validate`)

Validation runs automatically before the `body` function executes. When validation fails, individual errors are returned in the GraphQL `errors` array with field-level paths:

```json
{
  "errors": [
    {
      "message": "Value must be non-negative",
      "path": ["createUser", "age"]
    }
  ]
}
```

## Body Function

Define actual resolver logic in the `body` function. Function arguments include:

* `input` - Input data from GraphQL request
* `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 `kyselyTypePlugin`, you can use `getDB` to execute typed queries:

```typescript
import { getDB } from "../generated/tailordb";

createResolver({
  name: "getUser",
  operation: "query",
  input: {
    name: t.string(),
  },
  body: async (context) => {
    const db = getDB("tailordb");
    const result = await db
      .selectFrom("User")
      .select("id")
      .where("name", "=", context.input.name)
      .limit(1)
      .executeTakeFirstOrThrow();
    return {
      result: result.id,
    };
  },
  output: t.object({
    result: t.uuid(),
  }),
});
```

## Query vs Mutation

Use `operation: "query"` for read operations and `operation: "mutation"` for write operations:

```typescript
// Query - for reading data
createResolver({
  name: "getUsers",
  operation: "query",
  // ...
});

// Mutation - for creating, updating, or deleting data
createResolver({
  name: "createUser",
  operation: "mutation",
  // ...
});
```

## Event Publishing

Enable event publishing for a resolver to trigger executors on resolver execution:

```typescript
createResolver({
  name: "processOrder",
  operation: "mutation",
  publishEvents: true,
  // ...
});
```

**Behavior:**

* When `publishEvents: true`, resolver execution events are published
* When not specified, `deploy` sets it from the executors taking part in the same run: `true` while one of them uses this resolver with `resolverExecutedTrigger`, and `false` once none does. Removing the last such trigger turns publishing back off on the next `deploy`
* When explicitly set to `false` while an executor taking part in the same run uses this resolver, `deploy` fails

**Use cases:**

1. **Auto-detection (recommended)**: Don't set `publishEvents` - `deploy` enables it while an executor taking part in the same run needs it. An executor declared with `disabled: true` never runs, so it does not count

   ```typescript
   // publishEvents is automatically enabled because an executor uses this resolver
   export default createResolver({
     name: "processPayment",
     operation: "mutation",
     // publishEvents not set - auto-detected
     // ...
   });

   // In executor file:
   export default createExecutor({
     trigger: resolverExecutedTrigger("processPayment"),
     // ...
   });
   ```

2. **Manual enable**: Enable event publishing for external consumers or debugging

   ```typescript
   createResolver({
     name: "auditAction",
     operation: "mutation",
     publishEvents: true, // Enable even without executor triggers
     // ...
   });
   ```

3. **Explicit disable**: Disable event publishing for a resolver that doesn't need it (error if an executor taking part in the same run uses it)

   ```typescript
   createResolver({
     name: "internalHelper",
     operation: "query",
     publishEvents: false, // Explicitly disable
     // ...
   });
   ```

**Sharing a resolver across configs:** an executor in another config auto-enables publishing the same way, as long as both configs take part in the same `deploy` (`--config a,b`). `deploy` records that dependency, so deploying the owning config alone later asks for confirmation instead of silently turning publishing off — it fails outright in a non-interactive environment. Set `publishEvents: true` on the resolver to keep it on regardless of which configs take part.

## Permissions

### Access Requirement (`permission`)

By default, a resolver with no in-body check is reachable by an anonymous (unauthenticated) caller. Set `permission` to reject callers that don't match a condition, evaluated before `body` runs:

```typescript
import { createResolver, t } from "@tailor-platform/sdk";

export default createResolver({
  name: "getMyOrders",
  operation: "query",
  permission: [{ conditions: [[{ user: "_loggedIn" }, "=", true]], permit: true }],
  output: t.object({ count: t.int() }),
  body: async (context) => {
    // context.user is guaranteed to be an authenticated caller here
    return { count: 0 };
  },
});
```

`permission` uses the same `conditions`/`permit` notation as TailorDB's `.permission()` — an array of policies, restricted to `user` operands (a resolver has no associated record to compare against) with equality (`=`/`!=`) comparisons:

* `{ user: "_loggedIn" }` — whether the caller is authenticated
* `{ user: "id" }` — the caller's user ID
* `{ user: "someAttribute" }` — any string or boolean attribute enabled in `auth.userProfile.attributes` (or `auth.machineUserAttributes` for machine users); array attributes aren't supported, since conditions only compare against a single string/boolean value

Multiple conditions within the same policy's `conditions` array are combined with AND. `permit` is required, with no implicit default. At least one `permit: true` policy is required: `permission` is an allow-list, denied by default and granted only by a matching `permit: true` policy. This lets you express different eligibility paths, e.g. allowing machine-user callers unconditionally while gating regular users behind a role check:

```typescript
permission: [
  { conditions: [[{ user: "isServiceAccount" }, "=", true]], permit: true },
  { conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true },
],
```

A `permit: false` policy always denies matching callers, even ones another policy would otherwise allow. Combine it with a `permit: true` policy to carve out an explicit exception, e.g. granting access broadly but rejecting one banned role:

```typescript
permission: [
  { conditions: [[{ user: "_loggedIn" }, "=", true]], permit: true },
  { conditions: [[{ user: "role" }, "=", "BANNED"]], permit: false },
],
```

A policy array made up of only `permit: false` policies is rejected: since none of its conditions apply to a caller presenting no user attributes at all, it wouldn't actually keep anyone out who's willing to drop their credentials, so it can't stand in for an allow-list.

Besides a policy array, `permission` also accepts:

* `"allowAnonymous"` — explicitly documents that anonymous callers are allowed. Behaves the same as omitting `permission`, but records the decision so it isn't mistaken for an oversight.
* Omitted (default) — unchanged: anonymous callers can still reach the resolver.

This check is based on `context.user`, the original caller, so it still applies even when `authInvoker` swaps in a machine user for database access.

### Namespace-wide default (`defaultPermission`)

Declaring `permission` on every resolver is the only way to close a whole namespace, and one file that forgets it is enough to leave an opening. Declare `defaultPermission` on the resolver namespace in your config instead, and it applies to every resolver in that namespace:

```typescript
export default defineConfig({
  name: "my-app",
  resolver: {
    "main-resolver": {
      files: ["./src/resolver/*.ts"],
      defaultPermission: [{ conditions: [[{ user: "_loggedIn" }, "=", true]], permit: true }],
    },
  },
});
```

`defaultPermission` takes the same values as a resolver's own `permission`, including `"allowAnonymous"` — use that to record that a namespace is public by design rather than by oversight.

A resolver's own `permission` **replaces** the namespace default rather than adding to it, so a single resolver opts out of a namespace-wide requirement explicitly:

```typescript
export default createResolver({
  name: "healthCheck",
  operation: "query",
  permission: "allowAnonymous", // reachable even though the namespace requires a login
  output: t.string(),
  body: () => "ok",
});
```

When a namespace declares no `defaultPermission` and some of its resolvers declare no `permission` either, `generate` and `deploy` warn that those resolvers are reachable by anonymous callers. Declaring either one silences the warning.

## Authentication

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";

export default createResolver({
  name: "adminQuery",
  operation: "query",
  output: t.object({ result: t.string() }),
  body: async () => {
    // Executes as "batch-processor" machine user
    return { result: "ok" };
  },
  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.

**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.

---

---
url: https://docs.tailor.tech/sdk/services/secret.md
---
# Secret Manager

Secret Manager provides secure storage for sensitive values like API keys, tokens, and credentials that your application needs at runtime.

## Overview

Secret Manager provides:

* Secure storage for sensitive configuration values
* Organized secrets within named vaults
* Runtime access from executors and workflows
* CLI management for secrets lifecycle

## Concepts

### Vaults

Vaults are containers that group related secrets together. Each workspace can have multiple vaults, typically organized by purpose or environment.

```
workspace/
├── vault: api-keys
│   ├── stripe-secret-key
│   ├── sendgrid-api-key
│   └── external-service-token
└── vault: database
    ├── read-replica-password
    └── analytics-connection-string
```

### Secrets

Secrets are key-value pairs stored within a vault. Secret values are encrypted at rest and only accessible at runtime by authorized services.

## Managing Secrets

There are two ways to manage secrets: declaratively via `defineSecretManager()` in `tailor.config.ts`, or imperatively via the [CLI](#cli-management). Management is scoped per vault — **do not mix both approaches for the same vault**. When a vault is defined in config, the config becomes the source of truth: any secrets in that vault not present in the config will be deleted on `tailor deploy`.

### Declarative Configuration

Define your secrets in `tailor.config.ts` using `defineSecretManager()`. Each key is a vault name, and its value is a record of secret names to their values. These values are deployed to each vault on `tailor deploy`.

Since secret values should not be committed to source control, use environment variables:

```typescript
import { defineConfig, defineSecretManager } from "@tailor-platform/sdk";

export const secrets = defineSecretManager({
  "api-keys": {
    "stripe-secret-key": process.env.STRIPE_SECRET_KEY!,
    "sendgrid-api-key": process.env.SENDGRID_API_KEY!,
  },
  database: {
    "analytics-connection-string": process.env.ANALYTICS_DB_URL!,
  },
});

export default defineConfig({
  name: "my-app",
  secrets,
  // ...other config
});
```

The exported `secrets` object provides type-safe `get()` and `getAll()` methods for runtime access from resolvers, executors, and workflows.

### Skipping Secrets with Missing Values

In CI environments, you may not have all secret values available (e.g., secrets are already set on the platform and you don't want to duplicate them in CI environment variables). Use the `ignoreNullishValues` option to skip secrets whose values are `undefined` or `null`:

```typescript
export const secrets = defineSecretManager(
  {
    "api-keys": {
      "stripe-secret-key": process.env.STRIPE_SECRET_KEY,
      "sendgrid-api-key": process.env.SENDGRID_API_KEY,
    },
  },
  { ignoreNullishValues: true },
);
```

When `ignoreNullishValues: true`:

* Secrets with a string value are created or updated as normal
* Secrets with `undefined` or `null` values are **skipped** — they are not created, updated, or deleted
* Skipped secrets are shown in the deploy output for visibility
* Secrets removed from the config entirely are still deleted (orphan cleanup)

This allows you to set secret values once (e.g., via local `tailor deploy` or the CLI) and then deploy from CI without needing the actual values in CI environment variables.

## Using Secrets

### Runtime Access with `get()` / `getAll()`

Use the `secrets` object exported from `tailor.config.ts` to retrieve secret values at runtime. The vault and secret names are fully type-checked based on the `defineSecretManager()` configuration.

#### `get(vault, secret)`

Retrieves a single secret value.

```typescript
import { createResolver } from "@tailor-platform/sdk";
import { secrets } from "../tailor.config";

export default createResolver({
  name: "call-stripe",
  // ...
  operation: async ({ input }) => {
    const apiKey = await secrets.get("api-keys", "stripe-secret-key");
    // Use apiKey to call the Stripe API
  },
});
```

#### `getAll(vault, secrets)`

Retrieves multiple secret values at once from the same vault.

```typescript
import { createResolver } from "@tailor-platform/sdk";
import { secrets } from "../tailor.config";

export default createResolver({
  name: "send-notification",
  // ...
  operation: async ({ input }) => {
    const [apiKey, webhookSecret] = await secrets.getAll("api-keys", [
      "sendgrid-api-key",
      "stripe-secret-key",
    ]);
    // Use the retrieved secrets
  },
});
```

Both methods return `Promise<string | undefined>` (or an array of them for `getAll`).

### In Webhook Operations

Reference secrets in webhook headers using the vault/key syntax:

```typescript
import { createExecutor, recordCreatedTrigger } from "@tailor-platform/sdk";
import { order } from "../tailordb/order";

export default createExecutor({
  name: "notify-external-service",
  trigger: recordCreatedTrigger({ type: order }),
  operation: {
    kind: "webhook",
    url: "https://api.example.com/orders",
    headers: {
      "Content-Type": "application/json",
      Authorization: { vault: "api-keys", key: "external-api-token" },
      "X-API-Key": { vault: "api-keys", key: "api-secret" },
    },
    requestBody: ({ newRecord }) => ({
      orderId: newRecord.id,
      amount: newRecord.total,
    }),
  },
});
```

The secret reference format:

```typescript
{ vault: "vault-name", key: "secret-name" }
```

At runtime, these references are replaced with the actual secret values.

## CLI Management

Use the CLI to manage vaults that are **not** defined in `defineSecretManager()`. If you attempt to modify a vault that is managed by the config, the CLI will show a warning and ask for confirmation. Once confirmed, the CLI releases the vault's ownership label so it is no longer managed by config.

After ownership is released, the next `tailor deploy` will treat the vault as an unmanaged resource and prompt for confirmation before taking any action on it.

### Create a Vault

```bash
tailor secret vault create --name api-keys
```

### Add Secrets

```bash
# Create a secret
tailor secret create \
  --vault-name api-keys \
  --name stripe-secret-key \
  --value sk_live_xxxxx

# Update a secret
tailor secret update \
  --vault-name api-keys \
  --name stripe-secret-key \
  --value sk_live_yyyyy
```

## List Secrets

```bash
# List vaults
tailor secret vault list

# List secrets in a vault (values are hidden)
tailor secret list --vault-name api-keys
```

## Delete Secrets

```bash
# Delete a secret
tailor secret delete --vault-name api-keys --name old-key --yes

# Delete a vault (must be empty)
tailor secret vault delete --name old-vault --yes
```

See [Secret CLI Commands](../cli/secret) for full documentation.

---

---
url: https://docs.tailor.tech/sdk/services/staticwebsite.md
---
# Static Website

Static Website is a service for hosting static web applications on the Tailor Platform.

## Overview

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](/guides/static-website-hosting).

## Configuration

Configure static website hosting using `defineStaticWebSite()`:

**Definition Rules:**

* **Multiple websites allowed**: You can define multiple static websites in your config file
* **Configuration location**: Define in `tailor.config.ts` and add to the `staticWebsites` array
* **Uniqueness**: Website names must be unique across all static websites

```typescript
import { defineStaticWebSite, defineConfig } from "@tailor-platform/sdk";

const website = defineStaticWebSite("my-website", {
  description: "My Static Website",
});

// You can define multiple static websites
const adminWebsite = defineStaticWebSite("admin-website", {
  description: "Admin Dashboard",
});

export default defineConfig({
  staticWebsites: [website, adminWebsite], // Add all websites to the array
});
```

## Options

### description

A description of the static website:

```typescript
defineStaticWebSite("my-website", {
  description: "Frontend application for my service",
});
```

### allowedIpAddresses

Restrict access to specific IP addresses in CIDR format:

```typescript
defineStaticWebSite("my-website", {
  allowedIpAddresses: ["192.168.0.0/24", "10.0.0.0/8"],
});
```

### customDomains

Associate custom domains with the static website:

```typescript
defineStaticWebSite("my-website", {
  customDomains: ["app.example.com"],
});
```

After deploying, use `tailor staticwebsite domain get <domain>` to check domain status and retrieve the CNAME targets required for DNS configuration.

A domain can be associated with only one workspace at a time. To set custom domains only in the workspace that owns the domain, see [Multi-Environment Configuration](../multi-environment.md#settings-that-belong-to-a-single-environment).

## 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:

### CORS Settings

```typescript
const website = defineStaticWebSite("my-frontend", {
  description: "Frontend application",
});

export default defineConfig({
  cors: [website.url], // Resolved at deployment
  staticWebsites: [website],
});
```

### OAuth2 Redirect URIs

```typescript
const website = defineStaticWebSite("my-frontend", {
  description: "Frontend application",
});

const auth = defineAuth("my-auth", {
  oauth2Clients: {
    "my-client": {
      redirectURIs: [
        `${website.url}/callback`, // https://my-frontend.example.com/callback
        `${website.url}/auth/complete`, // https://my-frontend.example.com/auth/complete
      ],
      grantTypes: ["authorization_code", "refresh_token"],
    },
  },
});
```

## Complete Example

```typescript
import { defineConfig, defineAuth, defineIdp, defineStaticWebSite } from "@tailor-platform/sdk";
import { user } from "./tailordb/user";

const website = defineStaticWebSite("my-frontend", {
  description: "Frontend application",
});

const idp = defineIdp("my-idp", {
  clients: ["default-client"],
  permission: {
    create: [{ conditions: [[{ user: "_loggedIn" }, "=", true]], permit: true }],
    read: [{ conditions: [[{ user: "_loggedIn" }, "=", true]], permit: true }],
    update: [{ conditions: [[{ user: "_loggedIn" }, "=", true]], permit: true }],
    delete: [{ conditions: [[{ user: "_loggedIn" }, "=", true]], permit: true }],
    sendPasswordResetEmail: [{ conditions: [[{ user: "_loggedIn" }, "=", true]], permit: true }],
  },
});

const auth = defineAuth("my-auth", {
  userProfile: {
    type: user,
    usernameField: "email",
    attributes: { role: true },
  },
  oauth2Clients: {
    "frontend-client": {
      redirectURIs: [`${website.url}/callback`],
      grantTypes: ["authorization_code", "refresh_token"],
    },
  },
  idProvider: idp.provider("default", "default-client"),
});

export default defineConfig({
  name: "my-app",
  cors: [website.url],
  idp: [idp],
  auth,
  staticWebsites: [website],
});
```

---

---
url: https://docs.tailor.tech/sdk/services/tailordb.md
---
# TailorDB

TailorDB is a type-safe database service for defining and managing data models on the Tailor Platform.

## Overview

TailorDB provides:

* Type-safe schema definitions using TypeScript
* Automatic GraphQL API generation (CRUD operations)
* Relations between tables with automatic index and foreign key constraints
* Permission system for access control
* Field-level hooks and validations

For the official Tailor Platform documentation, see [TailorDB Guide](/guides/tailordb/overview).

## Table Definition

Define TailorDB tables in files matching glob patterns specified in `tailor.config.ts`.

**Definition Rules:**

* **Multiple tables per file**: You can define multiple TailorDB tables in a single file
* **Export method**: Use named exports (`export const`)
* **Export both value and type**: Always export both the runtime value and TypeScript type
* **Uniqueness**: Table names must be unique across all TailorDB namespaces in the application

```typescript
import { db } from "@tailor-platform/sdk";

// Export both value and type
export const user = db.table("User", {
  name: db.string(),
  email: db.string().unique(),
  age: db.int(),
  ...db.fields.timestamps(),
});
export type user = typeof user;

// You can define multiple tables in the same file
export const role = db.table("Role", {
  name: db.string().unique(),
});
export type role = typeof role;
```

Specify plural form by passing an array as first argument:

```typescript
db.table(["User", "UserList"], {
  name: db.string(),
});
```

Pass a description as second argument:

```typescript
db.table("User", "User in the system", {
  name: db.string(),
});
```

## Field Types

| Method                            | TailorDB | TypeScript     |
| --------------------------------- | -------- | -------------- |
| `db.string()`                     | String   | string         |
| `db.int()`                        | Integer  | number         |
| `db.float()`                      | Float    | number         |
| [`db.decimal()`](#decimal-fields) | Decimal  | string         |
| `db.bool()`                       | Boolean  | boolean        |
| `db.date()`                       | Date     | Date | string |
| `db.datetime()`                   | DateTime | Date | string |
| `db.time()`                       | Time     | string         |
| `db.uuid()`                       | UUID     | string         |
| [`db.enum()`](#enum-fields)       | Enum     | string         |
| [`db.object()`](#object-fields)   | Nested   | object         |

### Optional and Array Fields

```typescript
db.string({ optional: true });
db.string({ array: true });
db.string({ optional: true, array: true });
```

### Decimal Fields

Decimal fields are stored as strings to preserve precision. The optional `scale`
parameter sets the number of digits after the decimal point and must be an
integer between 0 and 12. When `scale` is omitted, the platform default of 6 is
used.

```typescript
// Default scale (6 decimal places)
db.decimal();

// Custom scale (2 decimal places)
db.decimal({ scale: 2 });

// Optional with custom scale
db.decimal({ scale: 4, optional: true });
```

Values are rounded half-up to fit the configured scale before being stored.
Negative values follow the same rule based on absolute magnitude:

| Input         | Scale | Stored       |
| ------------- | ----- | ------------ |
| `"1.234"`     | 2     | `"1.23"`     |
| `"1.235"`     | 2     | `"1.24"`     |
| `"-1.235"`    | 2     | `"-1.24"`    |
| `"1.5"`       | 0     | `"2"`        |
| `"1.123456"`  | 6     | `"1.123456"` |
| `"1.1234567"` | 6     | `"1.123457"` |

### Enum Fields

```typescript
db.enum(["red", "green", "blue"]);
db.enum([
  { value: "active", description: "Active status" },
  { value: "inactive", description: "Inactive status" },
]);
```

### Object Fields

```typescript
// Object field
db.object({
  street: db.string(),
  city: db.string(),
  country: db.string(),
});

// Object array field
db.object(
  {
    id: db.uuid(),
    name: db.string(),
    size: db.int(),
  },
  { array: true },
);

// Optional object array field
db.object(
  {
    kind: db.string(),
    days: db.int(),
  },
  { optional: true, array: true },
);
```

## Field Modifiers

### Description

```typescript
db.string().description("User's full name");
```

### Index / Unique

```typescript
db.string().index();
db.string().unique();
```

### Relations

Add a relation to field with automatic index and foreign key constraint:

```typescript
const role = db.table("Role", {
  name: db.string(),
});

const user = db.table("User", {
  name: db.string(),
  roleId: db.uuid().relation({
    type: "n-1",
    toward: { table: role },
  }),
});
```

`toward.type` is a deprecated alias for `toward.table` and will be removed in v3; `tailor upgrade` offers a codemod to rewrite it.

For one-to-one relations, use `type: "1-1"`:

```typescript
const userProfile = db.table("UserProfile", {
  userId: db.uuid().relation({
    type: "1-1",
    toward: { table: user },
  }),
  bio: db.string(),
});
```

For foreign key constraint without creating a relation, use `type: "keyOnly"`:

```typescript
const user = db.table("User", {
  roleId: db.uuid().relation({
    type: "keyOnly",
    toward: { table: role },
  }),
});
```

Create relations against different fields using `toward.key`:

```typescript
const user = db.table("User", {
  email: db.string().unique(),
});

const userProfile = db.table("UserProfile", {
  userEmail: db.string().relation({
    type: "1-1",
    toward: { table: user, key: "email", as: "user" },
  }),
});
```

`userEmail` does not end in `ID`, `Id`, or `id`, so this example specifies the forward relation
name with `toward.as`.

Customize relation names using `toward.as` / `backward` options:

```typescript
const userProfile = db.table("UserProfile", {
  userId: db.uuid().relation({
    type: "1-1",
    toward: { table: user, as: "base" },
    backward: "profile",
  }),
});
```

This generates the following GraphQL types:

```graphql
type UserProfile {
  userId: ID!
  base: User # toward.as: access User from UserProfile
}

type User {
  id: ID!
  profile: UserProfile # backward: access UserProfile from User
}
```

* `toward.as` - Customizes the field name for accessing the related table from this table
* `backward` - Customizes the field name for accessing this table from the related table

Relation names share the same GraphQL field namespace as fields, files, and other relations on
the table. The SDK rejects duplicate or empty relation names. When `toward.as` is omitted, the
default forward name comes from the relation field name with a trailing `ID`, `Id`, or `id`
removed. This lets multiple fields point to the same target table with distinct forward names:

```typescript
const post = db.table("Post", {
  authorID: db.uuid().relation({
    type: "n-1",
    toward: { table: user },
    backward: "authoredPosts",
  }),
  reviewerID: db.uuid().relation({
    type: "n-1",
    toward: { table: user },
    backward: "reviewedPosts",
  }),
});
```

These fields generate the forward names `author` and `reviewer`. A relation field without one of
the recognized ID suffixes needs an explicit `toward.as`, because its generated forward name
would conflict with the field itself.

Use `toward.as` or `backward` when a generated relation name would conflict with an existing
field, files entry, or relation on the same table.

### Hooks

Add hooks to execute functions during data creation or update.

#### Field-level Hooks

Set hooks directly on individual fields.

Create hooks receive:

* `input`: The field value from the input (null when not provided)
* `invoker`: Principal performing the operation
* `now`: Operation timestamp (`Date`), shared across all hooks in the same operation

Update hooks receive the same arguments plus:

* `oldValue`: The previous field value (null only for optional fields)

```typescript
db.string().hooks({
  create: ({ invoker }) => invoker?.id ?? "",
  update: ({ input, oldValue }) => input ?? oldValue,
});
```

Field-level hooks operate on a single field and cannot access other fields. Use table-level hooks for cross-field logic.

#### Table-level Hooks

Set hooks across multiple fields using `db.table().hooks()`. The hook returns an object with the fields to override. When both field-level and table-level hooks exist for the same field, table-level hooks take priority.

Create hooks receive:

* `input`: The submitted record data. When field-level hooks or defaults exist, `input` reflects their applied results
* `invoker`: Principal performing the operation
* `now`: Operation timestamp (`Date`), shared across all hooks in the same operation

Update hooks receive the same arguments plus:

* `oldRecord`: The existing record (non-null)

```typescript
export const customer = db
  .table("Customer", {
    firstName: db.string(),
    lastName: db.string(),
    fullName: db.string(),
  })
  .hooks({
    create: ({ input }) => ({
      fullName: `${input.firstName} ${input.lastName}`,
    }),
    update: ({ input, oldRecord }) => ({
      fullName: `${input.firstName ?? oldRecord.firstName} ${input.lastName ?? oldRecord.lastName}`,
    }),
  });
```

Use `now` to stamp several fields with the exact same instant:

```typescript
export const order = db
  .table("Order", {
    createdAt: db.datetime(),
    updatedAt: db.datetime(),
  })
  .hooks({
    create: ({ now }) => ({ createdAt: now, updatedAt: now }),
    update: ({ now }) => ({ updatedAt: now }),
  });
```

**Note:** `.hooks()` can only be called once on a table. Duplicate table-level calls fail at compile time and throw at runtime.

### Validation

Add validation rules to fields. Validators run after hooks.

**Note:** Custom validators run only when built-in type validation succeeds, so `value` always has the field's declared type. For array fields, the validator is called once with the complete array, not per element:

```typescript
// value is string[], not string
db.string({ array: true }).validate(({ value }) => value.length >= 2);
```

#### Field-level Validation

Set validators directly on individual fields. Each validator receives `{ value }` (the field value after hooks) and returns an error message string to fail, or void to pass:

```typescript
db.string().validate(
  ({ value }) => (value.includes("@") ? undefined : "Must contain @"),
  ({ value }) => (value.length >= 5 ? undefined : "Must be at least 5 characters"),
);
```

#### Table-level Validation

Set a validator across all fields using `db.table().validate()`. The validator receives `{ newRecord, oldRecord, invoker }` and an `issues()` callback to report errors per field:

```typescript
export const user = db
  .table("User", {
    name: db.string(),
    email: db.string(),
  })
  .validate(({ newRecord }, issues) => {
    if (newRecord.name.length <= 5) {
      issues("name", "Name must be longer than 5 characters");
    }
    if (!newRecord.email.includes("@")) {
      issues("email", "Must contain @");
    }
  });
```

### Defaults

Set a default value for a required field on create. The field becomes optional in the create input — the default fills in when no value is provided:

```typescript
db.int().default(0);
db.string().default("pending");
```

For datetime/date/time fields, pass `"now"` to use the operation timestamp:

```typescript
db.datetime().default("now");
```

**Note:** `.validate()` can only be called once on a table. Duplicate table-level calls fail at compile time and throw at runtime.

### Vector Search

```typescript
db.string().vector();
```

### Serial / Auto-increment

```typescript
db.int().serial({
  start: 0,
  maxValue: 100,
});

db.string().serial({
  start: 0,
  format: "CUST_%d",
});
```

### Common Fields

```typescript
export const user = db.table("User", {
  name: db.string(),
  ...db.fields.timestamps(),
});
```

`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.

## Table Modifiers

Table builder methods that set one table-level configuration can be called only once on the same table. Duplicate calls fail at compile time and throw at runtime. This applies to `.description()`, `.hooks()`, `.validate()`, `.features()`, `.indexes()`, `.files()`, `.permission()`, and `.gqlPermission()`.

Conditional assignment is still supported when only one branch calls the method:

```typescript
let user = db.table("User", {
  name: db.string(),
});

if (enableFiles) {
  user = user.files({
    avatar: "profile image",
  });
}
```

### Composite Indexes

```typescript
db.table("User", {
  firstName: db.string(),
  lastName: db.string(),
}).indexes({
  fields: ["firstName", "lastName"],
  unique: true,
  name: "user_name_idx",
});
```

### File Fields

```typescript
db.table("User", {
  name: db.string(),
}).files({
  avatar: "profile image",
});
```

### Features

```typescript
db.table("User", {
  name: db.string(),
}).features({
  aggregation: true,
  bulkUpsert: true,
});
```

#### Event Publishing

Enable event publishing for a table to trigger executors on record changes:

```typescript
db.table("User", {
  name: db.string(),
}).features({
  publishEvents: true,
});
```

**Behavior:**

* When `publishEvents: true`, record creation/update/deletion events are published
* When not specified, `deploy` sets it from the executors taking part in the same run: `true` while one of them uses this table with `recordCreatedTrigger`, `recordUpdatedTrigger`, or `recordDeletedTrigger`, and `false` once none does. Removing the last such trigger turns publishing back off on the next `deploy`
* When explicitly set to `false` while an executor taking part in the same run uses this table, `deploy` fails
* An executor declared with `disabled: true` never runs, so it does not count as using the table
* While a `deploy` applies pending migrations, every table in the migrating namespace is read-only: create, update, delete, and bulk-upsert operations are disabled while the existing read setting is preserved. Record event publishing is also switched off so a migration script's writes do not reach executors from the previous deploy. After success, the configured settings take effect. If a later migration fails, settings from the last confirmed checkpoint are restored; an uncommitted migration restores existing tables' prior settings and leaves its newly created tables restricted until a successful retry. Restoration is skipped if the checkpoint number or migration history changed concurrently, or if checkpoint ownership cannot be verified. A table left behind by a failed post-checkpoint deletion also remains read-only for manual recovery

**Use cases:**

1. **Auto-detection (recommended)**: Don't set `publishEvents` - `deploy` enables it while an executor taking part in the same run needs it

   ```typescript
   // publishEvents is automatically enabled because an executor uses this table
   export const order = db.table("Order", {
     status: db.string(),
   });

   // In executor file:
   export default createExecutor({
     trigger: recordCreatedTrigger(order),
     // ...
   });
   ```

2. **Manual enable**: Enable event publishing for external consumers or debugging

   ```typescript
   db.table("AuditLog", {
     action: db.string(),
   }).features({
     publishEvents: true, // Enable even without executor triggers
   });
   ```

3. **Explicit disable**: Disable event publishing for a table that doesn't need it (error if an executor taking part in the same run uses it)

   ```typescript
   db.table("TempData", {
     data: db.string(),
   }).features({
     publishEvents: false, // Explicitly disable
   });
   ```

**Sharing a table across configs:** an executor in another config auto-enables publishing the same way, as long as both configs take part in the same `deploy` (`--config a,b`). `deploy` records that dependency, so deploying the owning config alone later asks for confirmation instead of silently turning publishing off — it fails outright in a non-interactive environment. Set `publishEvents: true` on the table to keep it on regardless of which configs take part.

#### GraphQL Operations

Control which GraphQL operations (`create`, `update`, `delete`, `read`) are exposed for a table. All operations are enabled by default.

While a `deploy` applies pending migrations, every GraphQL operation — `create`, `update`, `delete`, `read`, and bulk upsert — is switched off across the migrating namespace, so nothing reads or writes an intermediate schema. After success, the configured operations take effect. If a later migration fails, operations from the last confirmed checkpoint are restored; an uncommitted migration restores existing tables' prior operations and leaves its newly created tables restricted until a successful retry. Restoration is skipped if the checkpoint number or migration history changed concurrently.

```typescript
db.table("Order", {
  status: db.string(),
}).features({
  gqlOperations: {
    delete: false, // Disable the delete mutation
  },
});
```

Use the `"query"` alias to disable all mutations at once (read-only table: `create`/`update`/`delete` false, `read` true):

```typescript
db.table("AuditLog", {
  action: db.string(),
}).features({
  gqlOperations: "query",
});
```

**Namespace-level default**

Set a default for every table in a TailorDB namespace in `tailor.config.ts`. A table'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 table in this namespace
    },
  },
});
```

This default is re-evaluated on every `tailor deploy`, so changing it also updates tables 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.

#### `pickFields(keys, options)`

Select specific fields and optionally modify their properties:

```typescript
const user = db.table("User", {
  id: db.uuid(),
  name: db.string(),
  email: db.string().unique(),
  ...db.fields.timestamps(),
});

// Pick id, createdAt, and updatedAt, making them optional
user.pickFields(["id", "createdAt", "updatedAt"], { optional: true });
```

Available options:

| Option     | Effect                                |
| ---------- | ------------------------------------- |
| `optional` | Makes the selected fields optional    |
| `array`    | Makes the selected fields array types |

**Note:** The `array` option cannot change fields with custom validation — their validators expect the original value shape. Define a new field with a matching validator instead.

#### `omitFields(keys)`

Return all fields except the specified ones:

```typescript
// All fields except id, createdAt, and updatedAt
user.omitFields(["id", "createdAt", "updatedAt"]);
```

#### Common Pattern: Input Schema Composition

The typical use case is combining `pickFields` and `omitFields` with spread syntax to build input schemas where identifiers are optional but other fields remain required:

```typescript
import { createResolver, t } from "@tailor-platform/sdk";
import { user } from "../tailordb/user";

export default createResolver({
  name: "createUser",
  operation: "mutation",
  input: {
    // 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) => {
    // ...
    return { id: "..." };
  },
});
```

This is also used in seed data schemas:

```typescript
import { t } from "@tailor-platform/sdk";
import { invoice } from "../../tailordb/invoice";

const schemaType = t.object({
  ...invoice.pickFields(["id", "createdAt", "updatedAt"], { optional: true }),
  ...invoice.omitFields(["id", "createdAt", "updatedAt", "invoiceNumber", "sequentialId"]),
});
```

### Permissions

Configure Permission and GQLPermission. For details, see the [TailorDB Permission documentation](/guides/tailordb/permission).

**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 table 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 table only needs record-level permission.

```typescript
db.table("User", {
  name: db.string(),
  role: db.enum(["admin", "user"]).index(),
})
  .permission({
    create: [[{ user: "role" }, "=", "admin"]],
    read: [
      [{ user: "role" }, "=", "admin"],
      [{ record: "id" }, "=", { user: "id" }],
    ],
    update: [[{ user: "role" }, "=", "admin"]],
    delete: [[{ user: "role" }, "=", "admin"]],
  })
  .gqlPermission([
    { conditions: [[{ user: "role" }, "=", "admin"]], actions: "all" },
    { conditions: [[{ user: "role" }, "=", "user"]], actions: ["read"] },
  ]);
```

#### Development/Test Helpers

For local development, prototyping, or testing, the SDK provides helper constants that grant full access without conditions:

```typescript
import {
  db,
  unsafeAllowAllTypePermission,
  unsafeAllowAllGqlPermission,
} from "@tailor-platform/sdk";

db.table("User", {
  name: db.string(),
})
  .permission(unsafeAllowAllTypePermission)
  .gqlPermission(unsafeAllowAllGqlPermission);
```

**Warning**: Do not use `unsafeAllowAllTypePermission` or `unsafeAllowAllGqlPermission` in production environments as they effectively disable authorization checks.

## Migrations

When you change a TailorDB table definition, the SDK can generate a migration that captures the diff and, for breaking changes, runs a data transformation script during `tailor deploy`. See the [TailorDB Migrations guide](tailordb-migration) for the full workflow, configuration, supported change types, team coordination, and troubleshooting.

For the CLI command reference, see [`tailordb migration`](../cli/tailordb.md#tailordb-migration).

---

---
url: https://docs.tailor.tech/sdk/services/tailordb-migration.md
---
# TailorDB Migrations

> **Beta:** The `tailordb migration` command and the migration runtime are beta features. They may introduce breaking changes in future releases. The CLI emits a beta warning on every invocation.

The migration system tracks changes to your TailorDB table definitions over time and applies them to deployed workspaces with optional data transformation scripts.

For the CLI command reference, see [`tailordb migration`](../cli/tailordb.md#tailordb-migration). This document covers concepts, workflows, and operational guidance.

## Overview

**Key Properties**

* **Local snapshot–based diff detection** — each migration is generated by diffing your current table definitions against the previous snapshot stored in `migrations/<NNNN>/`.
* **Transaction-wrapped data migrations** — each `migrate.ts` script runs inside a database transaction on the platform; if the script throws, all changes in that migration roll back.
* **Automatic execution during `apply`** — `tailor deploy` detects pending migrations, runs the two-stage table update (pre-migration → script → post-migration), and updates the migration checkpoint label.
* **Type-safe scripts** — the generated `db.ts` provides Kysely types that reflect the schema state **before** the migration runs, so transformations are written against the actual data shape.

**Files in `migrations/`**

```
migrations/
├── 0000/                    # Initial schema snapshot
│   └── schema.json
├── 0001/                    # First change
│   ├── diff.json            # Field-level diff from 0000
│   ├── migrate.ts           # Data migration script (auto-generated for breaking changes; can be added manually via `migration script`)
│   └── db.ts                # Kysely types for the script (pre-migration shape)
├── 0002/
│   └── diff.json            # No script — non-breaking changes only
└── ...
```

`0000` always contains a full snapshot. `0001` and onward contain a diff plus, optionally, a script and its types (auto-generated for breaking changes, or added manually via `tailordb migration script` for warning-tier changes). **Commit the entire `migrations/` directory to version control.**

## Initial Setup

### New project

When you start with no `migrations/` directory:

1. Add the `migration` block to `tailor.config.ts` (see [Configuration](#configuration)).
2. Define your initial tables in `tailordb/`.
3. Generate the initial migration:
   ```bash
   tailor tailordb migration generate
   ```
   This creates `migrations/0000/schema.json` from your current tables.
4. Run `tailor deploy`. The migration label is set to `0000` on the deployed namespace.

### Adding migrations to an existing project

If you already have a deployed workspace whose schema matches your local table definitions:

1. Add the `migration` block to `tailor.config.ts`.
2. Run `tailor tailordb migration generate` to create `0000/schema.json` from current local tables.
3. Run `tailor deploy`. Because remote schema already matches, no script runs; only the migration label is set.

If your local tables and remote schema have **diverged**, reconcile them before introducing migrations — either update local tables to match remote, or accept that the first non-`0000` migration will reflect that gap.

### Resetting

`tailor tailordb migration generate --init` deletes the existing `migrations/` directory and creates `0000` from the current local tables. Use it only before the project is deployed. For a deployed migration history, use [`migration rebaseline`](#re-baselining-a-deployed-migration-history), which verifies the history and connected workspace before replacing any files.

## Migration Workflow

A typical change cycle:

1. **Modify a table definition.**

   ```typescript
   // tailordb/user.ts
   export const user = db.table("User", {
     name: db.string(),
     email: db.string(), // ← new required field
     ...db.fields.timestamps(),
   });
   ```

2. **Generate the migration.**

   ```bash
   tailor tailordb migration generate --name "add email to user"
   ```

   Output:

   ```
   Generated migration 0001
     Diff file: ./migrations/0001/diff.json
     Migration script: ./migrations/0001/migrate.ts
     DB types: ./migrations/0001/db.ts
   ```

   If `EDITOR` or `VISUAL` is set, `migrate.ts` opens automatically.

3. **Edit `migrate.ts`** to populate data for the new required field:

   ```typescript
   import type { Transaction } from "./db";

   export async function main(trx: Transaction): Promise<void> {
     await trx
       .updateTable("User")
       .set({ email: "default@example.com" })
       .where("email", "is", null)
       .execute();
   }
   ```

4. **Apply.**
   ```bash
   tailor deploy
   ```
   The pre-migration phase relaxes the new field to optional, the script runs and populates values, then the post-migration phase enforces `required: true`.

### Warnings and optional migration scripts

Some non-breaking changes can still cause data loss — most notably removing a field (`field_removed`) or removing a table (`table_removed`). `migration generate` reports these as **warnings**:

```
Warning: data loss possible:

  - User.legacyParentId: Field removed (existing data will no longer be accessible through the schema after the post-migration phase)
```

No `migrate.ts` is generated automatically because the schema change itself is non-breaking, but the existing data is no longer accessible through the active schema after the post-migration phase. The platform may retain a removed field's underlying stored value, so do not rely on removal to clear data before reusing the same field name. If you need to preserve, transform, or clear that data first, add a script with:

```bash
tailor tailordb migration script 0002
```

This writes `migrations/0002/migrate.ts` and `migrations/0002/db.ts` next to the existing `diff.json` (add `--with-test` to also scaffold a `migrate.test.ts` — see [Testing Migrations Locally](#testing-migrations-locally)). The removed field stays readable inside `migrate.ts` because the pre-migration phase keeps it on the table until the script finishes (see [Per-migration phases](#per-migration-phases)). The next `tailor deploy` runs the script automatically — `migrate.ts` is executed whenever the file exists on disk, regardless of whether the diff itself required it.

If the data loss is intentional and no script is needed, record that decision the same way as for breaking changes (see [Breaking changes without a script](#breaking-changes-without-a-script)):

```bash
tailor tailordb migration script 0002 --no-script --reason "column no longer needed, data can be dropped"
```

In an interactive session, `migration generate` offers to record the reason on the spot when it detects warnings. The acknowledgment is stored in `diff.json`, so it is reviewable in the PR, and it satisfies `migration validate --strict` — useful for enforcing in CI that destructive changes are explicitly acknowledged before merge (see [Schema verification](#schema-verification)).

### Renaming a field

Renaming a field in a table definition looks like a removal plus an addition to the diff engine. Left as-is, that combination silently drops the old field's data: the removal is only a warning, so nothing forces a data copy.

To prevent that, when `migration generate` finds a removed field and an added field in the same table whose stored values can be copied without changing their meaning, it asks whether the change is a rename. Serial fields are never rename candidates, and an enum field only qualifies when it keeps every value of the removed field:

```
? User.fullName was removed and displayName was added with a compatible type. Was it renamed to displayName? (Y/n)
```

In non-interactive environments (or with `--yes`), no prompt is shown and the command fails while a rename candidate is left unresolved — writing it as remove + add would silently drop the field's data at deploy. Resolve every candidate explicitly: pass the rename, or confirm a genuine removal with `--drop`:

```bash
tailor tailordb migration generate --rename "User.fullName:displayName"
tailor tailordb migration generate --drop "User.fullName"
```

Repeat `--rename` and `--drop` for multiple fields. A `--rename` that does not match a compatible removed + added pair, or a `--drop` that does not match a removed field, fails with an error.

A confirmed rename is recorded as a single `field_renamed` change and treated as **breaking**, so a migration script is required. The generated `migrate.ts` copies the old field into the new one with a single set-based update, and the generated `db.ts` exposes both the old field (readable) and the new field (writable). The copy intentionally overwrites every row without checking for existing values: values of removed fields are retained in storage, so a stale value could otherwise resurface under the new name later. If the new field adds a unique constraint, the script also includes a duplicate-resolution block to run before the constraint is enforced.

During deploy, the pre-migration phase keeps the old field and adds the new field with its constraints relaxed, the script copies the data, and the post-migration phase drops the old field and enforces the new field's constraints — all within a single `tailor deploy`.

If you decline the prompt (or confirm the removal with `--drop`), the change stays a plain removal + addition with the usual data-loss warning.

Renaming a member inside a **nested field** is not detected, and it is quieter: `User.address.zip` → `zipCode` becomes a single `field_modified` on `address` with no breaking change, no warning, and no generated script, so the member's values are not carried over. Copy them with a custom `tailordb migration script` if they must survive.

### Renaming a table

Renaming a whole table is detected the same way: when `migration generate` finds a removed table and an added table with a matching shape, it asks whether the change is a rename:

```
? User was removed and Person was added with a compatible schema. Was it renamed to Person? (Y/n)
```

In non-interactive environments the command fails while a candidate is left unresolved, exactly like field renames. Resolve it with the table forms of the same flags (a value without a `.` targets a table):

```bash
tailor tailordb migration generate --rename "User:Person"
tailor tailordb migration generate --drop "User"
```

Two tables qualify as a rename pair only when copying every row preserves the data: every field must keep its name, type, array-ness, required/unique constraints, foreign key target, and decimal scale; enum fields may gain values but not lose them; indexes must match. A self-referential foreign key is compared against the new table name and must be optional. Tables with serial fields (their values cannot be written by a script) or file fields (file contents are not copied) are never candidates. Name-derived and data-independent settings — `pluralForm`, description, table settings, permissions, hooks, and validations — may differ.

A confirmed rename is recorded as a single `table_renamed` change and treated as **breaking** for two reasons: existing records must be copied by the migration script, and the table's GraphQL API names (derived from the table name and `pluralForm`) change, which breaks API clients. The generated `migrate.ts` copies every row from the old table into the new one in id-ordered batches, preserving ids so stored foreign key references stay valid, and the generated `db.ts` exposes both the old table (readable) and the new table (writable). Self-referential foreign keys are inserted as null and backfilled after every row exists, so a reference to a row in a later batch cannot fail the copy.

Two caveats apply to the copy. The old table is not write-protected: rows written to it after the script's transaction commits — and before post-migration cleanup drops it — are not carried over, so pause writers to the renamed table for the duration of the deploy. And platform-managed record metadata (creation/update timestamps and actors) cannot be written by the script, so the new table's records carry the migration run's metadata instead of the original values.

Fields on other tables that reference the renamed table via `foreignKeyType` must be retargeted at the new name in the same change. That retarget is recognized as part of the rename: it is not flagged as a breaking foreign-key change and needs no reference fixup, because record ids are preserved by the copy.

During deploy, the pre-migration phase creates the new table with its full constraints while the old table stays on the namespace, the script copies the rows, and the old table is dropped in post-migration cleanup after the checkpoint advances — all within a single `tailor deploy`.

### Breaking changes without a script

Breaking changes require `migrate.ts`. If it is missing at deploy time (for example, the generated script was deleted), `tailor deploy` fails before applying the migration or anything after it. When there is genuinely nothing to migrate — say, the affected table holds no data yet — record an explicit acknowledgment instead of keeping an empty script:

```bash
tailor tailordb migration script 0002 --no-script --reason "no data yet, safe to skip"
```

This stores the reason in `migrations/0002/diff.json` (commit the change). The next `tailor deploy` applies the schema change as usual, skips only the script step, and logs the recorded reason. The command refuses to record a skip while `migrate.ts` exists — delete the script first. If `migrate.ts` is added back later, `tailor deploy` fails rather than choosing between the script and the acknowledgment; run `tailor tailordb migration script 0002` again to clear the now-stale acknowledgment from `diff.json` (the script then runs on the next deploy), or delete `migrate.ts` to keep the skip.

### Data-only migrations

Sometimes existing data must be transformed without any schema change — fixing values written by an application bug, or a one-off normalization. Create a migration that carries no schema diff and exists only to run its script:

```bash
tailor tailordb migration generate --data-only --name "normalize legacy phone numbers"
```

This writes a numbered migration with an empty `diff.json`, a `migrate.ts` skeleton, and `db.ts` typed against the current schema. Edit `migrate.ts` to implement the transformation; the next `tailor deploy` runs it like any other migration script — in a single transaction, advancing the migration checkpoint (see [Performance and Large Tables](#performance-and-large-tables) for batching patterns). Because the entry is part of the migration history, the fix is versioned, ordered relative to schema changes, and applied once per workspace.

The command requires a clean state: if the namespace has schema changes that are not yet in migration files, generate the schema migration first. With multiple namespaces, pass `--namespace` to name the target. `--data-only` cannot be combined with `--init`, `--rename`, `--drop`, or `--expand-contract`.

A data-only migration runs in **every** workspace the history is applied to, including freshly created ones. Write the script so it is safe against tables with no matching rows (a set-based `UPDATE` with a `WHERE` clause is naturally a no-op on an empty table). For a fix that should run in a single environment only, or that is too large for one transaction, run it outside the migration history instead.

## Configuration

```typescript
// tailor.config.ts
export default defineConfig({
  name: "my-app",
  db: {
    tailordb: {
      files: ["./tailordb/*.ts"],
      migration: {
        directory: "./migrations",
        // Optional. Defaults to the first machine user in auth.machineUsers.
        machineUser: "admin-machine-user",
      },
    },
  },
});
```

| Option                  | Type   | Description                                                                                               |
| ----------------------- | ------ | --------------------------------------------------------------------------------------------------------- |
| `migration.directory`   | string | Directory path for migration files. Required when migrations are enabled for the namespace.               |
| `migration.machineUser` | string | Machine user used to run migration scripts. Optional; defaults to the first entry in `auth.machineUsers`. |

## Generated Files

| File                   | When generated                                                                                                                            | Description                                                                                                              |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `0000/schema.json`     | First `migration generate`                                                                                                                | Full snapshot of all tables in the namespace.                                                                            |
| `XXXX/diff.json`       | Every subsequent migration                                                                                                                | Field-level diff against the previous snapshot.                                                                          |
| `XXXX/migrate.ts`      | Auto-generated for breaking changes and `--data-only` migrations; added manually via `tailordb migration script` for warning-tier changes | Data transformation script. The `main` export receives a Kysely `Transaction`.                                           |
| `XXXX/db.ts`           | Generated once when `migrate.ts` is created                                                                                               | Kysely types reflecting the schema **before** this migration. Exports `Database`, `Transaction`, and `MigrationContext`. |
| `XXXX/migrate.test.ts` | Added via `tailordb migration script --with-test`                                                                                         | Unit-test scaffold for `migrate.ts` (see [Testing Migrations Locally](#testing-migrations-locally)). Never deployed.     |

`db.ts` reflects the pre-migration schema because the script runs after the pre-migration phase has temporarily relaxed breaking constraints (e.g., a new `required` field is added as `optional` first), so the data being read still matches the previous shape.

### Migration file format compatibility

Migration files are versioned independently of the SDK package. This SDK writes format version `3` and reads versions `1` through `3`. It normalizes supported older formats in memory; it never rewrites applied migration files on disk.

If a future SDK can no longer replay an old migration format, re-baseline while using an SDK version that still supports the complete history, commit the new baseline, deploy it to every environment, and then upgrade the SDK. A file from a newer unsupported format instead requires upgrading the SDK first. The CLI rejects both cases with guidance rather than attempting a best-effort replay.

There is no migration-file conversion command. Keeping applied files unchanged preserves the record of what ran, while `migration rebaseline` provides the escape hatch when the supported replay window changes.

## Migration Script Anatomy

```typescript
import type { Transaction } from "./db";

export async function main(trx: Transaction): Promise<void> {
  // SELECT is supported.
  const users = await trx.selectFrom("User").select(["id", "name"]).execute();

  // Loop and transform.
  for (const u of users) {
    await trx
      .updateTable("User")
      .set({ displayName: u.name.toUpperCase() })
      .where("id", "=", u.id)
      .execute();
  }
}
```

**Worked example: backfilling a new required enum field**

Adding a required field is a breaking change, so `migration generate` scaffolds `migrate.ts`. Given this table change:

```typescript
// tailordb/user.ts
export const user = db.table("User", {
  name: db.string(),
  email: db.string(),
  role: db.enum(["MANAGER", "STAFF"]), // ← new required field
  ...db.fields.timestamps(),
});
```

existing `User` rows have no `role` value yet, so the script assigns one before the post-migration phase enforces the constraint:

```typescript
import type { Transaction } from "./db";

export async function main(trx: Transaction): Promise<void> {
  await trx.updateTable("User").set({ role: "MANAGER" }).where("role", "is", null).execute();
}
```

The `where("role", "is", null)` guard keeps the script idempotent — rows that already have a value are untouched if the script re-runs.

Reference scripts for other breaking-change patterns live in the repository's [migration fixture templates](https://github.com/tailor-platform/sdk/tree/main/example/tests/migration-fixtures/templates): backfilling fields that become required and migrating rows off a removed enum value ([0005](https://github.com/tailor-platform/sdk/blob/main/example/tests/migration-fixtures/templates/0005/migrate.ts)), and de-duplicating values before a unique constraint is added ([0006](https://github.com/tailor-platform/sdk/blob/main/example/tests/migration-fixtures/templates/0006/migrate.ts)). They show the shape of each migration, not drop-in logic — adapt them to your data (the suffix strategy in `0006`, for example, assumes the suffixed names are not already taken).

**Accessing environment variables**

The migration `main` receives an optional second argument exposing the variables defined in `defineConfig({ env })` — the same values available via `context.env` in resolvers. The `MigrationContext` type is exported from the generated `./db`:

```typescript
import type { Transaction, MigrationContext } from "./db";

export async function main(trx: Transaction, { env }: MigrationContext): Promise<void> {
  // Branch on environment-specific config resolved at deploy time
  if (env.SKIP_BACKFILL) return;

  await trx.updateTable("User").set({ stage: env.ENVIRONMENT }).execute();
}
```

The `env` values are injected at bundle time (the same mechanism as resolvers/executors/workflow jobs); `process.env` and other Node-side environment access remain unavailable at runtime. The second argument is optional — existing `main(trx)` scripts continue to work unchanged.

**Rules**

* Always use the `trx` argument for database access. Anything that bypasses `trx` is not part of the transaction and will not roll back on failure.
* Do not import resolvers, executors, or other SDK runtime services. The migration script runs as a standalone bundle on the platform with only Kysely access; SDK service helpers are not available.
* Standard Node-compatible packages are bundled. Keep dependencies minimal — every import is shipped to the platform.
* `console.log` / `console.error` output is captured and surfaced under `Logs:` in the apply output. Use it sparingly for progress markers on long-running migrations.
* The script is idempotency-friendly by default because it runs inside a transaction, but **plan for re-execution**: if a later migration in the same `apply` fails, the platform may retry the apply, and you may want your script to tolerate already-migrated rows (e.g., `where("email", "is", null)` instead of unconditional updates).

## Supported Schema Changes

| Change Type                       | Breaking? | Migration Script? | Notes                                                                                                                                                                                                                                              |
| --------------------------------- | --------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Add optional field                | No        | No                | Schema change only                                                                                                                                                                                                                                 |
| Add required field                | Yes       | Yes               | Script populates default values                                                                                                                                                                                                                    |
| Remove field                      | No        | Optional          | Warning tier — no script is auto-generated, but you can add one with `tailordb migration script` to preserve or clear data before the field leaves the active schema. The field stays readable from `migrate.ts` during Pre-migration.             |
| Rename field                      | Yes       | Yes               | Confirmed interactively at generate time or via `--rename "Table.oldField:newField"` — see [Renaming a field](#renaming-a-field). Auto-generated script copies values from the old field to the new one; both fields coexist during Pre-migration. |
| Change optional → required        | Yes       | Yes               | Script sets defaults for null values                                                                                                                                                                                                               |
| Change required → optional        | No        | No                | Schema change only                                                                                                                                                                                                                                 |
| Add index (non-unique)            | No        | No                | Schema change only                                                                                                                                                                                                                                 |
| Add unique index                  | Yes       | Yes               | Script must resolve duplicate value combinations across the index fields                                                                                                                                                                           |
| Change unique index fields        | Yes       | Yes               | Treated like adding a new unique constraint over the new field set                                                                                                                                                                                 |
| Remove index                      | No        | No                | Schema change only (removing the unique constraint from an index is also non-breaking)                                                                                                                                                             |
| Add unique constraint             | Yes       | Yes               | Script must resolve duplicate values                                                                                                                                                                                                               |
| Remove unique constraint          | No        | No                | Schema change only                                                                                                                                                                                                                                 |
| Change decimal scale              | Yes       | Yes               | Auto-generated script re-saves existing rows under the new scale. Decreasing scale rounds values half-up and can lose precision. If the same change adds a unique constraint, duplicate handling runs after re-saving.                             |
| Add enum value                    | No        | No                | Schema change only                                                                                                                                                                                                                                 |
| Remove enum value                 | Yes       | Yes               | Script migrates records with removed values                                                                                                                                                                                                        |
| Add table                         | No        | No                | Schema change only                                                                                                                                                                                                                                 |
| Remove table                      | No        | Optional          | Warning tier — no script is auto-generated, but you can add one with `tailordb migration script` to preserve data before the table leaves the active schema. The table stays readable from `migrate.ts` during Pre-migration.                      |
| Rename table                      | Yes       | Yes               | Confirmed interactively at generate time or via `--rename "OldTable:NewTable"` — see [Renaming a table](#renaming-a-table). Auto-generated script copies all rows preserving ids; both tables coexist until post-migration cleanup.                |
| Change foreign key target table   | Yes       | Yes               | Script updates references to the new target                                                                                                                                                                                                        |
| Change field type (verified pair) | Yes       | Yes               | In-place for the pairs listed under [Field type changes](#field-type-changes); review the generated normalization scaffold and customize it only when existing values need transformation                                                          |
| Change field type (other pair)    | Yes       | Yes               | Two migrations, generated together after you confirm — see [Converting a field type](#converting-a-field-type). Edit the conversion in the first; the second needs no changes.                                                                     |
| Change array → single value       | -         | -                 | **Not supported** — see [Converting a field type](#converting-a-field-type)                                                                                                                                                                        |
| Change single value → array       | -         | -                 | **Not supported** — see [Converting a field type](#converting-a-field-type)                                                                                                                                                                        |

### Field type changes

These pairs change in place, in a single migration:

| From      | To                           |
| --------- | ---------------------------- |
| `integer` | `string`, `float`, `decimal` |
| `float`   | `string`, `decimal`          |
| `decimal` | `string`, `float`            |
| `boolean` | `string`                     |
| `uuid`    | `string`                     |
| `enum`    | `string`                     |

Every pair here accepts every value its source type allows, which is what lets the change happen in one migration: the field keeps its previous type until the migration finishes, so your application can keep writing to it throughout.

Every other scalar pair needs a temporary field. Eligible fields can use the generated [expand-contract pair](#converting-a-field-type); fields the generator rejects still need the manual three-step sequence described below. Three groups are worth calling out:

* Converting to a narrower type — `string` → `integer`, `string` → `uuid`, `integer` → `boolean` and similar — is excluded because values the source type still accepts, such as `"abc"` in a `string` field, cannot be cast. Your script could clean up the rows it sees, but the field goes on accepting new uncastable values until the migration completes.
* `boolean` → `integer`, `float` → `integer`, and `string` → `date` are excluded because the stored values cannot be cast to the new type.
* `date`, `datetime`, and `time` fields are not stored in the textual form you wrote them in, so converting them to or from another type reads back as a different instant. Convert them through a temporary field where your script controls the formatting.

Converting to `decimal` reformats values to the field's scale, so `42` reads back as `42.000000`. Values with more decimal places than the scale allows are rounded half-up, so `1.1234567` becomes `1.123457` at the default scale of 6.

A `float` field that is already unique cannot convert to `decimal` in place, because rounding can turn two distinct values into the same one and the existing constraint leaves no room to resolve the collision. Use the 3-step migration for those.

### Generated normalization script for field type changes

For example, changing `User.age` from `integer` to `float` generates a `migrate.ts` that scans non-null values in batches of 100:

```typescript
import type { Transaction } from "./db";

export async function main(trx: Transaction): Promise<void> {
  // Normalize User.age from integer to float while the previous type is still active
  {
    let lastId: string | undefined;
    while (true) {
      let query = trx
        .selectFrom("User")
        .select(["id", "age"])
        .where("age", "is not", null)
        .orderBy("id", "asc")
        .limit(100);
      if (lastId) {
        query = query.where("id", ">", lastId);
      }
      const rows = await query.execute();
      if (rows.length === 0) break;

      for (const row of rows) {
        // TODO(tailor-migration-review): Remove this marker and the `never` annotation after reviewing the normalization.
        // Keep the value accepted by the active integer type and castable to float.
        const sourceValue = row.age;
        if (sourceValue === null) continue;
        const normalizedValue: never = sourceValue;
        if (Object.is(normalizedValue, sourceValue)) continue;
        await trx
          .updateTable("User")
          .set({ ["age"]: normalizedValue })
          .where("id", "=", row.id)
          .execute();
      }
      lastId = rows[rows.length - 1]!.id;
    }
  }
}
```

The generated `never` annotation intentionally causes a TypeScript error until you review the normalization. If the existing values are already suitable for the target type, remove the annotation and review marker to accept the identity transformation; it does not write any rows. If values need application-specific normalization, replace the expression and remove the annotation and marker while keeping the result valid for both the active source type and the target type. The source field contract remains active until the script finishes; for example, an `integer` → `float` script cannot write fractional values during this phase.

### Converting a field type

A field type change outside the verified in-place pairs — `string` → `integer`, for example — cannot be applied in one step, because the field would have to hold both shapes at once. `migration generate` offers to carry the values through a temporary field instead:

```
User.price changes from string to integer, which cannot be applied in one step.
? Generate two migrations to convert User.price through a temporary field? (Y/n)
```

Confirming writes two migrations:

1. **The conversion.** Adds a temporary field (`priceMigrate`), converts each stored value into it, and clears and removes the original field. Edit the conversion expression before deploying: the generated `never` annotation fails your typecheck, and `tailordb migration validate` rejects the migration while the review marker is still there.
2. **The rename.** Renames the temporary field back to `price`. Its copy script is complete, but this migration also carries every other schema change the same run picked up, so review it as you would any generated migration.

`tailor deploy` applies both. Because the conversion only touches rows whose original value is still set, a re-run resumes where it stopped rather than converting a row twice.

The original field is removed in the first migration rather than the second, because the rename needs its name free. Your script can still read it while the conversion runs.

In a non-interactive run — `--yes`, or CI — name each field explicitly:

```bash
tailor tailordb migration generate --yes --expand-contract "User.price"
```

Without the flag the command fails rather than converting anything, so a scripted run cannot start a two-migration change by accident.

> **Why the conversion clears the original field.** Removing a field from the schema does not necessarily remove its stored value. Reusing the name for an incompatible type while a stale value remains can deploy successfully and then make subsequent reads fail. Clearing the original in the same update is what prevents that, which is why the generated script writes both fields at once.

> **Writes that land while the conversion runs are not carried across.** The original field keeps its old type until the conversion finishes, so an application can still write to it after the script has read the last row — and that value is dropped with the field rather than converted. Stop writes to the field, or accept the loss, before deploying a conversion on a live workspace.

Some changes are still rejected and need a temporary field you add yourself — add the new field, write a script that fills it and clears the old one, then remove the old field and rename the temporary one in a later migration:

* Array-to-scalar and scalar-to-array, since collapsing an array has no answer the generated script could choose for you.
* A field that is unique, or that an index, relationship, permission, or table-level script names. Those keep pointing at the original name, which the conversion removes.

## Testing Pending Migrations

`tailor tailordb migration test` runs every migration pending in the source workspace against an isolated workspace. The source workspace is selected by `--workspace-id` or the active profile and is never modified.

The command performs the following sequence:

1. Reads each migration-enabled namespace's `sdk-migration` checkpoint from the source workspace and reconstructs that exact snapshot from local migration history.
2. Creates a temporary workspace in the same region, organization, and folder as the source, unless `--target-workspace-id` names an existing throwaway workspace.
3. Deploys the checkpoint snapshots and writes their checkpoint labels.
4. Loads fixture data or clones source records.
5. Runs the normal deployment pipeline, including every pending pre-migration, `migrate.ts`, and post-migration phase.
6. Optionally runs an assertion script against the migrated data.
7. Deletes an automatically-created workspace after success or failure.

Both the pre-migration and final TailorDB schemas come from committed migration snapshots. Ungenerated changes in the current table definitions are not included in the rehearsal.

Executors are omitted from the baseline deployment so loading fixture or cloned records cannot trigger current event handlers against the older schema. Auth user profiles are also deferred until the pending migrations finish, while configured machine users remain available to run seed and migration scripts. The final deployment restores the configured executors and user profiles. Static websites are deployed so configuration references to their URLs resolve, but their workspace-bound custom domains are omitted from migration-test deployments.

### Seed mode

Seed mode is the default and uses the JSONL files produced by the configured `seedPlugin`. Run `tailor generate` after adding the plugin or changing seed tables, then populate its `data/*.jsonl` files:

```bash
tailor tailordb migration test --data seed
```

Rows are loaded only for tables present in the deployed pre-migration snapshots (and current schemas without migrations), in foreign-key dependency order. Fields introduced by pending migrations, including timestamp and nested fields, are removed before insertion so current fixtures can be loaded into the baseline schema. Missing table files are treated as empty. IdP `_User` fixtures are not loaded by this command.

Use `--machine-user` to override the seed plugin's `machineUserName`, the namespace migration setting, and the first configured Auth machine user for seed and assertion execution.

### Clone mode

Clone mode copies TailorDB records from the source workspace after the identical application, namespace names, and pre-migration schemas exist in the target. For namespaces without migration history, the command reproduces the deployed source schema rather than uncommitted local table changes:

```bash
tailor tailordb migration test --data clone
```

The platform clone API is feature-gated and requires editor access to both same-region workspaces. It copies TailorDB records only: IdP users, file blobs, and metadata labels are not copied. File fields therefore retain references whose blobs are absent. The command polls the asynchronous operation and reports platform failures; if clone is unavailable, use seed mode.

The source schema is re-verified immediately before cloning; if the source workspace was deployed or otherwise changed after the test started, the command aborts instead of cloning data that no longer matches the deployed baseline.

### Assertions and retained targets

Pass a TypeScript file with `--assert`. Its exported `main` function uses the same Kysely transaction signature as `migrate.ts`, runs after all pending migrations, and must throw when an invariant fails:

```bash
tailor tailordb migration test \
  --data seed \
  --assert ./tests/assert-customer-email.ts \
  --assert-namespace tailordb
```

`--assert-namespace` is inferred when only one namespace has pending migrations and is required otherwise.

To inspect the result after a run, pass `--keep` so the automatically created workspace survives instead of being deleted, on success and on failure:

```bash
tailor tailordb migration test --keep
```

Alternatively, provide an empty designated throwaway workspace. This mode never deletes the target and requires explicit acknowledgment:

```bash
tailor tailordb migration test \
  --target-workspace-id 00000000-0000-4000-8000-000000000000 \
  --yes
```

Do not target a shared development or production workspace: baseline deployment reconciles its managed resources and schemas before the migration test runs.

## Automatic Migration Execution

When you run `tailor deploy`, the SDK detects pending migrations (anything past the current `sdk-migration` label on the deployed namespace) and runs them in order before continuing with the rest of the apply.

### Per-migration phases

For each pending migration:

1. **Pre-migration**: Schema changes that would be breaking are applied in a relaxed form first. A verified in-place field type change keeps its complete previous field contract until Post-migration, including field and table-level hooks or validators changed by the same migration. Newly-required fields are added as optional; fields whose `optional → required` transition is breaking are temporarily kept optional. Fields that are being removed in this migration are temporarily kept on the table so that `migrate.ts` can still read them (for example, to `innerJoin` through a foreign key that is about to be dropped). For a renamed field, the old field is kept and the new field is added with its constraints relaxed, so the script can read the old field and write the new one. For a renamed table, the new table is created with its full constraints while the old table stays on the namespace until post-migration cleanup, so the script can copy rows between them. Breaking table-level index changes are relaxed the same way: a newly-added unique index is withheld, and an index gaining a unique constraint (or a unique index changing its field set) keeps its previous definition, so `migrate.ts` can resolve duplicates first. Non-breaking changes that are part of the same migration are also applied here.
2. **Script execution**: If `migrate.ts` exists on disk for this migration, it is bundled and sent to the platform via the script execution API and runs as the configured machine user inside a transaction. The script is hard-required for breaking changes (`diff.requiresMigrationScript`) — deploy fails if the file is missing, unless a `--no-script` acknowledgment was recorded (see [Breaking changes without a script](#breaking-changes-without-a-script)). It is also executed when present for warning-tier diffs — see [Warnings and optional migration scripts](#warnings-and-optional-migration-scripts).
3. **Post-migration schema**: Required constraints and the target field definitions are applied. Do not assume that removing a field clears its underlying stored JSON value.
4. **Checkpoint and cleanup**: The `sdk-migration` label is bumped to this migration's number, then removed GQL permissions and tables — including the old table left behind by a rename — are deleted. Advancing the checkpoint first prevents a failed checkpoint write from requiring the SDK to recreate irreversibly deleted records.

This split is what allows existing rows to be backfilled before the database starts rejecting nulls, and what lets `migrate.ts` traverse foreign-key fields that the same migration removes.

### Schema verification

Before running migrations, `apply` performs two checks:

1. **Local schema check** — your current table definitions must match the latest snapshot in `migrations/`. If they don't, you forgot to run `migration generate`.
2. **Remote schema check** — the deployed schema is reconstructed from migration history; the actual remote schema must match. Drift here means someone applied a different set of migrations or edited the schema out-of-band.

On drift you'll see something like:

```
✖ Remote schema drift detected:
Namespace: tailordb
  Remote migration: 0007
  Differences:
  Table 'User':
    - Field 'email': required: remote=false, expected=true
```

The error also points you at `migration status`, `migration generate`, `migration sync`, and `migration set` — see [Remote schema drift detected](#remote-schema-drift-detected) for which one applies.

To run the same checks without deploying — plus migration file integrity (numbering, parseable contents, a `migrate.ts` or a recorded `--no-script` acknowledgment for every migration that requires a script, and no unresolved generated normalization review markers):

```bash
tailor tailordb migration validate
```

It reports issues per namespace, exits with a non-zero code when any check fails, and supports `--json` for machine-readable output.

With `--strict`, validation additionally fails when a migration not yet applied to the remote has data-loss warnings (see [Warnings and optional migration scripts](#warnings-and-optional-migration-scripts)) but neither a `migrate.ts` nor a recorded `--no-script` acknowledgment. The failure names the affected table and field and prints the exact command to record the acknowledgment.

To bypass both checks during deploy (not recommended outside of recovery scenarios):

```bash
tailor deploy --no-schema-check
```

### Example output

```
ℹ Found 2 pending migration(s) to execute.
ℹ Executing 2 pending migration(s)...
ℹ Using machine user: admin-machine-user for namespace 'tailordb'

✔ Migration tailordb/0002 completed successfully
✔ Migration tailordb/0003 completed successfully

✔ All migrations completed successfully.
✔ Successfully applied changes.
```

## Re-baselining a deployed migration history

`tailor tailordb migration rebaseline` collapses the complete history into a new `0000/schema.json` in the current migration format. It does not modify the deployed schema or data.

Before running it:

1. Apply the latest migration to every environment. The CLI verifies the connected workspace, but it cannot inspect other workspaces.
2. Commit or otherwise preserve the existing migration history. Files after `0000`, including `migrate.ts` and `db.ts`, disappear from the working tree; Git history retains committed files.
3. Make sure local table changes have been captured with `tailor tailordb migration generate`.

Then re-baseline one namespace:

```bash
tailor tailordb migration rebaseline --namespace tailordb
```

The command validates the migration files, verifies that replaying the latest migration exactly reproduces the local table definitions, and checks that the connected workspace is at that latest migration with no schema drift. After confirmation, it replaces the local history with the reconstructed baseline, records a new migration history ID in both `0000/schema.json` and remote metadata, and resets the connected workspace's `sdk-migration` label to `0000`. Use `--yes` only after arranging the same operational preconditions in non-interactive automation.

Commit the resulting `migrations/` change before generating any new migrations. For another environment still carrying the exact checkpoint and history ID that the new baseline replaced, the next `tailor deploy` checks whether its remote schema exactly matches the new `0000`. If it does, deploy offers to reset the checkpoint to `0000` and move the environment to the new history ID before applying any later local migrations. A markerless history is eligible only for the first rebaseline, at the exact migration recorded as replaced. Any other checkpoint or history ID is rejected without changing remote metadata, even if its schema happens to match the baseline.

Partial squashing is not supported: re-baselining always replaces the full history for one namespace.

## `migration set` Semantics

`tailor tailordb migration set <N>` updates the `sdk-migration` label on the deployed namespace's metadata. **It does not modify any data or schema.** It only changes which migrations the next `apply` will consider pending. The command also aligns the remote migration history ID with the local baseline, removing a stale ID when the local history predates re-baselining.

The migration number is validated before anything is sent to the remote: it must be a 4-digit value (e.g. `0001`) or a bare integer (e.g. `1`) within 0–9999, and must exist in the working tree's migration history, which is itself validated (a gapped history is rejected). `0` is always accepted as the baseline (even when no migrations directory exists yet), provided the history passes validation.

| Movement                         | Effect on next `apply`                                                    | Effect on data                                                |
| -------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------- |
| Forward (e.g., `0001` → `0003`)  | Migrations `0002` and `0003` are skipped — they will not run.             | None.                                                         |
| Backward (e.g., `0003` → `0001`) | Migrations `0002` and `0003` become pending and will re-execute on apply. | None directly — but the re-executed scripts may rewrite data. |

Use cases:

* **Recovery from drift** — you investigated, manually fixed the remote, and want the SDK's bookkeeping to reflect reality.
* **Re-running a faulty migration** in a development workspace — set backward, fix `migrate.ts`, apply.
* **Skipping a migration** that you know was already applied out-of-band.

`migration set` does not perform a true rollback. To undo a schema/data change in production, write a new forward migration that reverses it (see [Rollback Strategy](#rollback-strategy)).

## `migration sync` Semantics

`tailor tailordb migration sync <N>` reconstructs the schema snapshot at migration `N` from the working tree's migration history and **overwrites the remote schema to match it**, then sets the `sdk-migration` label to `N` and aligns the remote migration history ID with the local baseline. Unlike `migration set`, it changes the remote schema as well as the bookkeeping. Like `set`, it never runs `migrate.ts` scripts itself — it only changes what the next `apply` considers pending:

| Movement                         | Effect on next `apply`                                                                    | Effect on data                                                                                              |
| -------------------------------- | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Backward (e.g., `0003` → `0001`) | Migrations `0002` and `0003` become pending and re-execute, including their `migrate.ts`. | Tables absent from snapshot `0001` are deleted along with their data; re-executed scripts may rewrite data. |
| Forward (e.g., `0001` → `0003`)  | Migrations `0002` and `0003` are skipped — their `migrate.ts` scripts will not run.       | Data the skipped scripts would have migrated stays as-is.                                                   |

Before anything is sent to the remote, `sync` verifies that replaying the full migration history reproduces the current local table definitions. If it does not — because migration files were edited and no longer match, or because a schema change has not been recorded with `migration generate` yet — the command fails without touching the remote. This means a rewritten migration history is validated before it can overwrite the deployed schema.

Because syncing backward causes already-applied scripts to re-execute on the next deploy, **write `migrate.ts` scripts to be idempotent** (see [Performance and Large Tables](#performance-and-large-tables) for resumable `where` clauses).

The main use case is recovering from drift after a `deploy --no-schema-check` from an older revision: instead of checking out that revision, run `migration sync <N>` to restore the remote to a known snapshot, then `tailor deploy` to apply the remaining migrations from the working tree.

## Team Workflow and CI/CD

### Branch coordination

Migration numbers are assigned sequentially, so two developers branching off the same point and each generating `0005` will collide. Conventions that work:

* **Don't generate migrations on long-lived feature branches.** Generate them just before merge, after rebasing onto main.
* **Resolve collisions by re-generating.** If your branch has `0005` but main now has `0005` from another PR, regenerate yours as `0006` — see [Resolving a migration number conflict](#resolving-a-migration-number-conflict).
* **Treat migration files as merge-conflict-prone.** They are committed JSON and TypeScript, so review them in PRs. The `diff.json` is the source of truth — if review focuses there, regenerating after rebase is straightforward.

### Resolving a migration number conflict

When your branch and main each generated the same number, merging or rebasing stops with an add/add conflict on `migrations/0005/diff.json`. Resolve it by re-generating your migration on top of main's:

1. **Save your script edits aside.** If you customized `0005/migrate.ts`, keep a copy before touching the directory — during a rebase, `git show ORIG_HEAD:migrations/0005/migrate.ts` prints the version from your pre-rebase branch tip.
2. **Take main's `0005/` directory in full.** Accept main's version of every conflicting file. Then check for files only your side added: if your migration has a `migrate.ts` and main's does not, that file never conflicts — it silently stays next to main's `diff.json`. Delete such leftovers explicitly.
3. **Finish the rebase or merge, then re-run `migration generate`.** With main's migration now part of local history, the diff is computed against the correct base — including main's changes — and your migration lands as the next number (`0006`).
4. **Port your script.** Copy the logic saved in step 1 into the newly scaffolded `0006/migrate.ts`. For a warning-tier change, `migration generate` does not scaffold a script — recreate it first with `tailor tailordb migration script 0006`.

**When a plain rename is enough.** If the two migrations touch disjoint tables and fields, renaming your directory to the next free number (keeping main's `0005/`) can be acceptable. Run `tailor tailordb migration validate` after the rename: if it reports a mismatch, the migrations were not disjoint — discard the rename and re-generate as above. A passing check covers only the schema history, not your script: `migrate.ts` now runs after main's migration, so confirm it does not read or write tables that migration touches — when in doubt, re-generate.

### CI / CD

* For non-interactive environments, pass `--yes` to `migration generate` and `--yes` to `apply`. `apply` runs migrations automatically when the `migrations/` directory is configured.
* Run `tailor tailordb migration validate` in CI to catch uncommitted migrations, broken migration files, unreviewed generated normalization logic, and remote schema drift before deploying. It exits with a non-zero code when validation fails and supports `--json`. Add `--strict` to also require an explicit acknowledgment (a `migrate.ts` or a recorded `--no-script` reason) for every pending migration that can drop data, so destructive changes cannot merge unnoticed.
* `tailor tailordb migration status` validates file-format compatibility across the full local history, compares its history ID with the deployed namespace, and shows applied and pending migrations for a human-readable comparison. Its exit code is non-zero on incompatible files, migration history mismatches, and remote read errors, so check the output.
* Avoid running migrations in parallel against the same workspace — there is no locking. Serialize deploys per environment.

### Resetting a deployed project

Use `tailor tailordb migration rebaseline` rather than combining `migration generate --init` with a manual checkpoint change. See [Re-baselining a deployed migration history](#re-baselining-a-deployed-migration-history) for the required cross-environment coordination and verification.

## Failure Recovery

If the pre-migration phase or `migrate.ts` fails:

* **The transaction rolls back** for that migration's script. Database changes the script made are undone.
* **The pre-migration schema changes are rolled back** to the prior checkpoint: tables that already existed are restored to their previous shape, and tables the migration newly introduced are dropped. The workspace is left at its prior checkpoint and prior schema — not half-applied.
* The whole `apply` aborts and the checkpoint label is not bumped. Subsequent migrations in the same run do not execute.

The rollback is best-effort per table; if reverting a table fails, a warning is logged and the original migration error is still reported.

After a failure:

1. Read the `Logs:` block in the apply output to find the cause.
2. Fix `migrate.ts` (or the data it depends on).
3. Re-run `tailor deploy`. The same migration runs again because its label was never bumped, and the prior-checkpoint schema is a clean baseline to retry against.

If a migration **succeeds in script** but its reversible **post-migration schema update** fails (rare; usually a constraint violation the script should have prevented), the SDK makes the same best-effort restoration to the prior-checkpoint schema. The script's committed data changes remain, so write migration scripts to tolerate re-execution.

The checkpoint is advanced only after the reversible post-migration schema updates succeed. If the checkpoint write reports an error, the SDK reads it back: a matching value is treated as committed. Any other observed value leaves the post-migration schema unchanged rather than risk rolling back a concurrent deployment; a value beyond the current migration confirms a concurrent deploy, while an older or missing value means the checkpoint must be repaired before retrying. If read-back also fails, the SDK likewise leaves the post-migration schema unchanged; verify the remote checkpoint before retrying.

Removed tables are deleted only after the checkpoint is committed. If that cleanup fails, the checkpoint remains at the new migration and the SDK fails closed: the leftover table is reported as remote schema drift on the next deploy. Remove the leftover GQL permission and table manually, verify the remote schema, and then retry. The SDK does not automatically ignore or delete a same-named remote table because it cannot distinguish failed cleanup from a table recreated after cleanup completed.

## Rollback Strategy

There is no automatic down-migration. To roll back a schema/data change in production, write a new forward migration that reverses the previous one. For example, to undo a `0005` that added a required `email` field:

1. Edit your table definitions to remove the field.
2. `migration generate --name "rollback 0005 email"` produces `0006` with a removal diff.
3. Apply.

In **development workspaces**, a quicker option is to fix `0005/migrate.ts` in place, run `migration set <previous>` to re-mark it pending, and apply. Do not do this on production — it confuses migration history across environments.

## Machine User and Permissions

Migration scripts execute server-side under a machine user identity. The CLI selects the user in this priority order:

1. `db.<namespace>.migration.machineUser` if set in `tailor.config.ts`.
2. The first entry in `auth.machineUsers` otherwise.

The CLI logs the selected user before running scripts (`Using machine user: ...`).

**Permissions required**

The machine user needs read/write access to every table the migration script touches. If your migrations alter data across multiple tables, the simplest path is to give the migration user broad access (e.g., an `ADMIN` role) and restrict day-to-day machine users separately. If the user lacks permission, the script fails with a permission error in `Logs:`.

If you see `No machine user available for migration execution`, either:

* Add `machineUsers: { ... }` to your auth config and `tailor deploy` it, or
* Set `migration.machineUser` to an existing machine user name in the db config.

## Multi-Namespace Coordination

If your project defines multiple TailorDB namespaces (`db: { ns1: { ... }, ns2: { ... } }`), each has its own `migrations/` directory and its own migration label. During `apply`:

* Migrations are grouped by namespace and executed namespace by namespace.
* Within a namespace, migrations run sequentially in number order.
* There is no cross-namespace ordering guarantee. Do not write a migration in `ns1` that depends on data produced by a migration in `ns2` running first.
* Each namespace can specify its own `migration.machineUser`.

## Performance and Large Tables

The migration script runs in a single transaction. For tables with many rows:

* Prefer set-based SQL (`updateTable(...).set(...).where(...)`) over per-row loops.
* If a per-row loop is unavoidable, batch by primary key range. Avoid `OFFSET`-based pagination — it scans previously-seen rows on every page.
* Long-running transactions can hit platform timeouts and hold locks. For very large backfills, consider splitting the work across multiple migrations, each operating on a subset.
* Add `LIMIT` and resumability (idempotent `where` clauses) so a re-run after a transient failure converges.

### Migrations that take longer than a minute

Migration scripts run as workflow jobs, so they are not bound by the 60-second
limit that applies to synchronous script execution. `tailor deploy` waits for
the migration and reports its logs as usual. Execution time is still bounded —
a workflow job has its own, far longer, execution-time limit.

The script still runs in a single transaction, so the guidance above about
locks and transaction size continues to apply — prefer splitting a very large
backfill across several migrations over holding one transaction open for a
long time.

## Testing Migrations Locally

### Unit-testing migrate.ts

`main` is a plain function, so you can unit-test it with Vitest before the first deploy ever runs it. `createKyselyMock` from `@tailor-platform/sdk/vitest` compiles queries to the same SQL as the deployed migration, so a test verifies the exact statements the script issues — SQL, parameters, and order. Type the mock with the `Database` interface exported from the generated `db.ts`.

Scaffold a ready-to-fill test next to the script with:

```bash
tailor tailordb migration script 0005 --with-test
```

When `migrate.ts` already exists (the usual case for breaking changes, where `migration generate` creates it), the command adds only `migrate.test.ts`. Or write the test by hand:

```typescript
// migrations/0005/migrate.test.ts
import { createKyselyMock } from "@tailor-platform/sdk/vitest";
import { describe, expect, test } from "vitest";
import type { Database } from "./db";
import { main } from "./migrate";

describe("0005 add required email", () => {
  test("backfills null emails", async () => {
    const mock = createKyselyMock<Database>();

    await mock.withTx((trx) => main(trx));

    expect(mock.updates).toHaveLength(1);
    expect(mock.updates[0]?.updateValues()).toEqual({ email: "unknown@example.com" });
    expect(mock.updates[0]?.sql).toContain('where "email" is null');
  });
});
```

Stage the rows each query returns with `mock.enqueueResult(...)` or `mock.setQueryResolver(...)` when the script reads before writing; call `main(trx, { env: { ... } })` when the script takes a `MigrationContext`. See [Kysely-layer mock](../testing.md#kysely-layer-mock-createkyselymock) for the full mock API.

These tests need no platform connection and no `tailor-runtime` environment — they run in a plain Vitest setup. Vitest's default `include` pattern already picks up `migrations/**/migrate.test.ts`; if your config narrows `include`, add the migrations directory. The test file is ignored by `tailor deploy` and never ships to the platform.

### Executing migrate.ts against a local Postgres (PGlite)

A statement-level test verifies what the script issues, not what it does to data (e.g., whether a `where` clause matches the rows you intended). To run `main` against real rows locally, back Kysely with `@electric-sql/pglite` — an in-memory PostgreSQL — via `createKyselyPGlite` from `@tailor-platform/sdk/vitest`:

```bash
npm install -D @electric-sql/pglite
```

Create the tables the script touches (matching the shape in the generated `db.ts`), stage rows, then run the script in a transaction. Type the instance with `Unmigrated<Database>` rather than `Database`: `db.ts` types a column the migration makes required as `T | null` on read but `T` on write (and an enum it narrows as the old values on read but the new ones on write), so that `migrate.ts` cannot write what the migration is removing — which would also stop the test from staging the rows the script has to convert. `Unmigrated` lets every column be written with whatever it can still be read as; `main` still receives a `Transaction<Database>`.

```typescript
// migrations/0005/migrate.pglite.test.ts
import { PGlite } from "@electric-sql/pglite";
import { sql } from "@tailor-platform/sdk/kysely";
import { createKyselyPGlite, type Unmigrated } from "@tailor-platform/sdk/vitest";
import { afterAll, beforeAll, describe, expect, test } from "vitest";
import type { Database } from "./db";
import { main } from "./migrate";

const db = createKyselyPGlite<Unmigrated<Database>>(new PGlite());

beforeAll(async () => {
  await sql`
    CREATE TABLE "User" (
      "id" uuid PRIMARY KEY DEFAULT gen_random_uuid(),
      "name" text NOT NULL,
      "email" text,
      "createdAt" timestamptz NOT NULL,
      "updatedAt" timestamptz NOT NULL
    )
  `.execute(db);
});

afterAll(async () => {
  await db.destroy();
});

describe("0005 add required email", () => {
  test("backfills null emails and keeps existing ones", async () => {
    const now = new Date();
    await db
      .insertInto("User")
      .values([
        { name: "a", email: null, createdAt: now, updatedAt: now },
        { name: "b", email: "b@example.com", createdAt: now, updatedAt: now },
      ])
      .execute();

    await db.transaction().execute((trx) => main(trx));

    const rows = await db.selectFrom("User").select(["name", "email"]).orderBy("name").execute();
    expect(rows).toEqual([
      { name: "a", email: "unknown@example.com" },
      { name: "b", email: "b@example.com" },
    ]);
  });
});
```

Two caveats keep this from replacing a scratch workspace:

* PGlite runs full PostgreSQL, while TailorDB supports [a subset of it](/guides/function/accessing-tailordb#supported-sql-queries) — a statement that passes here can still be rejected on deploy.
* The `CREATE TABLE` statements are yours, so they can drift from the schema the platform actually has.

### Beyond unit tests

A unit test verifies which statements the script issues; a PGlite test verifies what they do to the rows you staged. Neither runs against your actual data. To cover that:

* Run `migration generate` on a clean working copy first, review `diff.json`, then run again after editing tables to ensure the diff matches what you intended.
* For non-trivial migrations, apply against a scratch workspace before promoting to staging or production.

## Environment-Specific Strategies

A migration script is a function — branching on environment (e.g., to skip a backfill in dev) is just normal TypeScript. For environment awareness, use the `env` values defined in `defineConfig({ env })`, exposed via the optional second argument `{ env }: MigrationContext` (see [Migration Script Anatomy](#migration-script-anatomy)). These are resolved at deploy time and inlined into the bundle. Do not read `process.env` inside `migrate.ts` — Node-side environment access is unavailable at runtime; only the injected `env` (and the data itself) reflect the target environment.

For genuinely different schemas across environments, prefer separate workspaces with the same migration history rather than divergent `migrations/` directories.

## Troubleshooting

### Remote schema drift detected

**Cause:** Remote schema doesn't match what the migration history says it should be.

**Resolution:**

1. `tailor tailordb migration status` to see local vs remote.
2. Compare with teammates — has someone applied different migrations?
3. If remote was changed manually, decide whether to update local migrations to match or to use `migration set <N>` to align bookkeeping.
4. To force the remote schema back to a known snapshot, use `migration sync <N>` (see [`migration sync` Semantics](#migration-sync-semantics)).
5. As a last resort in non-production environments, `--no-schema-check` skips both checks. Do not use this as a routine workaround.

### "Invalid schema snapshot" or "Invalid migration diff" error

**Cause:** A `schema.json` or `diff.json` file in the `migrations/` directory is corrupted or does not match the expected structure. Merge conflicts left in these files are a common cause.

**Resolution:**

1. Read the error message — it includes the file path and the offending field.
2. Restore the file from version control (`git checkout -- <path>`), or regenerate migration files with `migration generate` / `migration script`.
3. Do not hand-edit `schema.json` or `diff.json`; they are managed by the CLI.

### "Unsupported migration file format version" error

**Cause:** A `schema.json` or `diff.json` file is older or newer than the format versions supported by the installed SDK.

**Resolution:** Follow the ordering in the error message. For an older history, restore an SDK version that can read every file, run `migration rebaseline`, commit and deploy the new baseline everywhere, and then upgrade. For a file produced by a newer SDK, upgrade the SDK that is reading it. Do not hand-edit the version field.

### "No machine user available for migration execution"

**Cause:** Neither `migration.machineUser` is set nor are there any machine users in `auth.machineUsers`.

**Resolution:** Add a machine user to auth, apply auth changes, then re-run.

### "Machine user not found"

**Cause:** `migration.machineUser` references a name that doesn't exist in the deployed auth config.

**Resolution:** Either add the machine user to `auth.machineUsers` and apply, or change `migration.machineUser` to a valid name.

### Migration script execution fails

**Cause:** Runtime error in your `migrate.ts`, a permission error from the machine user, or a constraint violation when post-migration tightens tables.

**Resolution:** Read the `Logs:` block. Fix the script or the data assumption it relies on, and re-run `tailor deploy`. The label is not bumped on failure, so the same migration retries.

### `migrate.ts` not found for a migration that needs one

**Cause:** `diff.requiresMigrationScript` is true but `migrate.ts` is missing from the migration directory.

**Resolution:** Restore the file from version control, or create it with `tailor tailordb migration script <N> --namespace <namespace>`. If the migration intentionally needs no data transformation, record that decision with `tailor tailordb migration script <N> --namespace <namespace> --no-script --reason "<why no data migration is needed>"` instead.

---

---
url: https://docs.tailor.tech/sdk/services/workflow.md
---
# Workflow

Workflows orchestrate multiple jobs that can depend on each other, enabling complex multi-step operations with durable execution.

## Overview

Workflows provide:

* Job orchestration with dependencies
* Durable execution with automatic state management
* Resume capabilities from failure points
* Access to TailorDB via Kysely query builder
* Job starting to compose multi-step logic

For the official Tailor Platform documentation, see [Workflow Guide](/guides/workflow/).

## Workflow Rules

All workflow components must follow these rules:

**Definition Rules:**

* **One workflow + multiple jobs per file**: Each file can define multiple jobs (named exports) and one workflow (default export)
* **Workflow export method**: Must use `export default`
* **Job export method**: Must use named exports (`export const`)
* **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 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`                                                                                                                                                        |
| `createWorkflowJob`'s `name`/`body` must be written directly in the call | Not as a reference to a variable or the result of another function — the build cannot see through that indirection and fails instead of silently leaving the job out                           |
| `.start()` must be called from within the calling job's `body`           | A function defined inside `body` may call it too, but not a function defined outside `body` — the build cannot see through that indirection and fails instead of silently leaving the call out |
| Call `<job>.start()`, not `execJobFunction` directly                     | Calling `tailor.workflow.execJobFunction(...)` (or the `workflow` value imported from `@tailor-platform/sdk/runtime`) directly is not detected as a dependency and fails the build             |

## Creating a Workflow Job

Define workflow jobs using `createWorkflowJob`:

```typescript
import { createWorkflowJob } from "@tailor-platform/sdk";
import { getDB } from "../generated/tailordb";

// All jobs must be named exports
export const fetchCustomer = createWorkflowJob({
  name: "fetch-customer",
  body: async (input: { customerId: string }) => {
    const db = getDB("tailordb");
    const customer = await db
      .selectFrom("Customer")
      .selectAll()
      .where("id", "=", input.customerId)
      .executeTakeFirst();
    return customer;
  },
});
```

## Input and Output Type Constraints

Workflow job inputs and outputs are serialized as JSON when passed between jobs. This imposes type constraints:

**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
export const myJob = createWorkflowJob({
  name: "my-job",
  body: async (input: { id: string; count: number; tags: string[] }) => {
    // ...
  },
});

// Compile error — Date is not allowed in input
export const badJob = createWorkflowJob({
  name: "bad-job",
  body: async (input: { createdAt: Date }) => {
    // ...
  },
});

// 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** 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.

## Starting Jobs

Use `.start()` to start other jobs from within a job.

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";
import { fetchCustomer } from "./jobs/fetch-customer";
import { sendNotification } from "./jobs/send-notification";

export const mainJob = createWorkflowJob({
  name: "main-job",
  body: (input: { customerId: string }) => {
    const customer = fetchCustomer.start({
      customerId: input.customerId,
    });
    const notification = sendNotification.start({
      message: "Order processed",
      recipient: customer.email,
    });
    return { customer, notification };
  },
});
```

### Deterministic Execution Requirement

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 `.start()` calls with the same arguments in the same order.

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.start({ region });
  results.push(result);
}
```

```typescript
// ❌ Bad: non-deterministic — argument changes between executions
processJob.start({ timestamp: Date.now() });

// ✅ 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.start({ id: item.id });
}

// ✅ 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.start({ id: item.id });
}
```

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 `.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

Define a workflow using `createWorkflow` and export it as default:

```typescript
import { createWorkflow, createWorkflowJob } from "@tailor-platform/sdk";
import { fetchCustomer } from "./jobs/fetch-customer";
import { sendNotification } from "./jobs/send-notification";

// Jobs must be named exports
export const processOrder = createWorkflowJob({
  name: "process-order",
  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 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.start({
      message: "Order processed",
      recipient: customer.email,
    });
    return { customerId: input.customerId };
  },
});

// Workflow must be default export
export default createWorkflow({
  name: "order-processing",
  mainJob: processOrder,
});
```

## Execution Events

Workflows can publish execution lifecycle events for executors. When an executor subscribes to a workflow's events, `deploy` enables publishing automatically. A `workflowExecution*` trigger enables it on the workflow, and a `workflowJobExecution*` trigger enables it on every job that workflow runs. See [Workflow Execution Triggers](executor.md#workflow-execution-triggers).

Publishing follows the subscription in both directions: removing the last subscribing trigger turns it back off on the next `deploy`, as does disabling the last executor that carries one.

Set `publishEvents` explicitly to pin the value instead. Use `true` to publish workflow-level events with no subscribing executor:

```typescript
export default createWorkflow({
  name: "order-processing",
  mainJob: processOrder,
  publishEvents: true,
});
```

A job takes the same field for its own execution events:

```typescript
export const processOrder = createWorkflowJob({
  name: "process-order",
  publishEvents: true,
  body: async () => ({ processed: true }),
});
```

Use `false` to keep publishing off. `deploy` fails if an executor subscribes to events the value opts out of, so the subscription cannot silently go unfulfilled.

**Subscribing from another config:** an executor in another config auto-enables publishing the same way, as long as both configs take part in the same `deploy` (`--config a,b`). The workflow a `workflowExecution*` or `workflowJobExecution*` trigger names must be declared by a config in the run; `deploy` fails otherwise rather than creating an executor whose events never arrive. `deploy` records the dependency on the workflow itself, so deploying that config alone later asks for confirmation instead of silently turning publishing off. Declaring `publishEvents` clears the record: a declared value no longer depends on which configs are deployed together, so there is nothing left to warn about.

## 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 `createWaitPoint` to create a single typed wait point:

```typescript
import { createWaitPoint } from "@tailor-platform/sdk";

export const approval = createWaitPoint<
  { message: string; requestId: string },
  { approved: boolean }
>("approval");
```

Keys must match `[a-z0-9-]`, be 3 to 63 characters long, and start and end with `[a-z0-9]`.

For multiple wait points, use `createWaitPoints` with a builder callback. Property names become wait point keys, and JSDoc on each property is preserved in IDE autocompletion:

```typescript
import { createWaitPoints } from "@tailor-platform/sdk";

export const waitPoints = createWaitPoints((define) => ({
  /** Manager approval step */
  "manager-approval": define<{ amount: number }, { approved: boolean }>(),
  /** Finance review step */
  "finance-review": define<{ invoiceId: string }, { validated: boolean }>(),
}));

await waitPoints["manager-approval"].wait({ amount: 50000 });
```

Pass the key to `define` when the property name you want to read at the call site is not a valid key:

```typescript
export const waitPoints = createWaitPoints((define) => ({
  managerApproval: define.for("manager-approval")<{ amount: number }, { approved: 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 { createWaitPoint, createWorkflow, createWorkflowJob } from "@tailor-platform/sdk";

export const approval = createWaitPoint<
  { 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 [Jobs that wait on approval](../testing.md#jobs-that-wait-on-approval) in the testing guide.

### Keys With Runtime Values

A wait point key identifies one suspension inside one execution. When a job suspends more than once for the same reason — one approval per order line, one per approver — every suspension needs its own key, otherwise the second `wait()` fails because a suspension with that key is already pending.

Write `$paramName` as a whole `-`-delimited segment of the key to leave a slot for a runtime value — `line-approval-$lineId` works, `line-approval$lineId` does not. Declare such a key through `createWaitPoints`, passing it to `define` **before** the `Payload` and `Result` type arguments — the param names then become the argument of `.with()`, which builds the concrete key:

```typescript
export const { lineApproval } = createWaitPoints((define) => ({
  lineApproval: define.for("line-approval-$lineId")<{ message: string }, { approved: boolean }>(),
}));

// Suspends on "line-approval-<lineId>", so parallel lines never collide
const result = await lineApproval.with({ lineId: line.id }).wait({ message: "Please approve" });
```

The key has to come before the type arguments because TypeScript stops inferring it as a literal type once `Payload` and `Result` are given explicitly, and the param names can only be read off a literal. `createWaitPoint` takes its type arguments first, so it cannot type `$params` at all, and `deploy` rejects such a key — one wait point per key is what it is for, and a key with `$params` stands for a family of them.

`deploy` checks every declared key against the grammar above, so a key the platform would reject is reported before anything is deployed.

A parameterized wait point exposes only `.with()` — there is no way to wait on the unsubstituted key.

Resolve it from the same param values:

```typescript
await lineApproval.with({ lineId: input.lineId }).resolve(input.executionId, (payload) => {
  console.log("Resolving:", payload.message);
  return { approved: input.approved };
});
```

Rules to keep in mind:

* Param values must match `[a-z0-9-]`, cannot be empty, and cannot start or end with `-`. Record IDs work as-is; uppercase or underscored values do not.
* The composed key still has to fit 63 characters. A UUID takes 36, so a key holding one leaves 26 characters for everything else.
* The key needs at least one literal segment alongside its `$params`, so `"$lineId"` alone is rejected: a key made only of caller data carries no identity of its own.
* Param values are part of the key, so they must be derived from the job's input. A value from `Date.now()` or `Math.random()` changes when the platform replays the job and the execution fails.
* Keys are compared exactly, and the SDK does not check whether two declared keys can produce the same string. `"a-$x"` with `x = "b-c"` and `"a-b-$y"` with `y = "c"` both produce `a-b-c`. Keep the literal part of each key distinct, and prefer putting `$params` last.

## 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:

| Field               | Type     | Description                                                |
| ------------------- | -------- | ---------------------------------------------------------- |
| `maxRetries`        | `number` | Maximum number of retries (1–10)                           |
| `initialBackoff`    | `string` | Initial backoff duration (e.g., `"1s"`, `"500ms"`, max 1h) |
| `maxBackoff`        | `string` | Maximum backoff duration (e.g., `"30s"`, `"5m"`, max 24h)  |
| `backoffMultiplier` | `number` | Backoff multiplier for exponential backoff (>= 1)          |

Duration strings support `ms`, `s`, and `m` units. `initialBackoff` must be less than or equal to `maxBackoff`.

```typescript
export default createWorkflow({
  name: "order-processing",
  mainJob: processOrder,
  retryPolicy: {
    maxRetries: 3,
    initialBackoff: "1s",
    maxBackoff: "30s",
    backoffMultiplier: 2,
  },
});
```

## Concurrency Policy

You can limit the number of concurrent executions of a workflow by setting `concurrencyPolicy`. When the limit is reached, new executions remain in PENDING state until a running execution completes.

| Field                     | Type     | Description                                      |
| ------------------------- | -------- | ------------------------------------------------ |
| `maxConcurrentExecutions` | `number` | Maximum number of concurrent executions (1-1000) |

When omitted, only platform-level limits apply.

```typescript
export default createWorkflow({
  name: "order-processing",
  mainJob: processOrder,
  concurrencyPolicy: {
    maxConcurrentExecutions: 5,
  },
});
```

## 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 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

Use `defineWorkflowExecutionPolicies` with a builder callback. Property names supply the workspace-unique name and default key prefix verbatim, matching the mental model of `createWaitPoints`. Override `name` or `key` in the body when the property identifier is not valid execution policy grammar or the key prefix needs to differ. Set `matchType: "prefix"` to register the prefix as a wildcard that matches every dispatch key starting with it (the default, `"exact"`, matches only a dispatch key equal to it).

```typescript
import { defineWorkflowExecutionPolicies } from "@tailor-platform/sdk";

export const executionPolicies = defineWorkflowExecutionPolicies((define) => ({
  /** Shared cap across every "premium" worker dispatch. */
  premium: define({ concurrencyPolicy: { maxConcurrentExecutions: 5 } }),
  /** Per-tenant cap: one pool per resolved tenant key. */
  tenantApi: define({
    name: "tenant-api",
    matchType: "prefix",
    concurrencyPolicy: { maxConcurrentExecutions: 3 },
  }),
}));
```

For a single policy, use `defineWorkflowExecutionPolicy(name, def?)`; the key prefix defaults to `name` when `key` is omitted.

`concurrencyPolicy` is optional; when omitted, the policy registers the key as valid without a user-defined limit (platform safety nets still apply).

Register the policies on your config so the SDK creates them on the workspace during deploy:

```typescript
// tailor.config.ts
import { defineConfig } from "@tailor-platform/sdk";
import { executionPolicies } from "./workflows/policies";

export default defineConfig({
  workflow: {
    files: ["workflows/**/*.ts"],
    executionPolicies,
  },
});
```

### Key Grammar

`key` accepts `[a-z0-9_:.-]` and must start with `[a-z0-9]`. An exact key must also end with `[a-z0-9]`; a wildcard prefix (`matchType: "prefix"`) may end with any of those characters, since the platform appends a trailing `*` after it. The platform-registered key — including that trailing `*` when wildcarded — is 2 to 64 characters long, so a wildcard prefix must be at most 63 characters. `foo:bar` is a valid exact key; `tenant-api` with `matchType: "prefix"` registers `tenant-api*` as a wildcard prefix.

An exact-key policy applies to dispatches whose runtime key equals the policy key. A wildcard policy applies to every dispatch whose runtime key begins with the prefix; each concrete resolved key gets its own independent pool of the declared size (a `cap = 3` wildcard yields three concurrent dispatches per resolved key, not three across every match). When a dispatch matches more than one policy (for example, an exact key that also falls under a wildcard prefix, or two wildcard prefixes where one starts with the other), every matching policy's cap is enforced independently, and the tightest one blocks.

### Referencing a Policy from a Workflow

Pass the runtime key through the `executionPolicyKey` option on `job.start()`. 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";
import { executionPolicies } from "./policies";
import { sendNotification } from "./jobs/send-notification";
import { fetchTenant } from "./jobs/fetch-tenant";

export const mainJob = createWorkflowJob({
  name: "main-job",
  body: async (input: { tenantId: string }) => {
    // Exact key policy: pass .key directly.
    await sendNotification.start(
      { message: "Order processed" },
      { executionPolicyKey: executionPolicies.premium.key },
    );

    // Wildcard policy: build the concrete key with keyFor().
    await fetchTenant.start(
      { tenantId: input.tenantId },
      { executionPolicyKey: executionPolicies.tenantApi.keyFor(input.tenantId) },
    );
  },
});
```

## Starting a Workflow from a Resolver

You can start a workflow execution from a resolver using `workflow.start()`.

* `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
import { createResolver, t } from "@tailor-platform/sdk";
import orderProcessingWorkflow from "../workflows/order-processing";

export default createResolver({
  name: "startOrderProcessing",
  operation: "mutation",
  input: {
    orderId: t.string(),
    customerId: t.string(),
  },
  body: async ({ input }) => {
    const workflowRunId = await orderProcessingWorkflow.start(
      { orderId: input.orderId, customerId: input.customerId },
      { invoker: "manager-machine-user" },
    );

    return { workflowRunId };
  },
  output: t.object({
    workflowRunId: t.string(),
  }),
});
```

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

Recommended file structure for workflows:

```
workflows/
├── jobs/
│   ├── fetch-customer.ts    # export const fetchCustomer = createWorkflowJob(...)
│   └── send-notification.ts # export const sendNotification = createWorkflowJob(...)
└── order-processing.ts      # export const processOrder = createWorkflowJob(...)
                             # export default createWorkflow(...)
```

All jobs can be in a single file or split across multiple files, as long as they are named exports.

## CLI Commands

Manage workflows using the CLI:

```bash
# List workflows
tailor workflow list

# Get workflow details
tailor workflow get <name>

# Start a workflow
tailor workflow start <name> -m <machine-user> -a '{"key": "value"}'

# List executions
tailor workflow executions

# Get execution details with logs
tailor workflow executions <execution-id> --logs

# Resume a failed execution
tailor workflow resume <execution-id>
```

See [Workflow CLI Commands](../cli/workflow) for full documentation.

---

---
url: https://docs.tailor.tech/tutorials.md
---
# Tutorials

Follow the tutorials to learn how to manage the data schema within TailorDB. Activate services to set up authentication (Auth) for secure access control and configure the executor service for automation.
Properly configuring these components ensures the application performs reliably.

## Prerequisite

Follow our step-by-step [tutorials](/tutorials/develop-from-scratch/overview) to create a sample project management application

## Expand your application

These well-structured examples can be modified to suit various templates.

---

---
url: https://docs.tailor.tech/tutorials/app-endpoint.md
---
# Adding Application Endpoints

This tutorial shows how to add new services to your Tailor application using the SDK. Services provide different capabilities like database access, custom logic, authentication, and workflow orchestration.

* To follow along with this tutorial, first complete the [SDK Quickstart](../sdk/quickstart). It provides the app template that we'll modify in the steps ahead.

## How Services Work in the SDK

The SDK automatically creates application endpoints (subgraphs) based on the services you configure in `tailor.config.ts`. When you define a service configuration, the SDK:

1. Reads your service files from the specified directories
2. Validates the service definitions
3. Generates the corresponding application endpoints
4. Deploys them to your workspace

## Available Services

You can configure the following services in your application:

* **TailorDB** (`db`): Database schema and types
* **Resolver** (`resolver`): Custom GraphQL query and mutation resolvers
* **Executor** (`executor`): Event-driven handlers that respond to database changes
* **Workflow** (`workflow`): Job orchestration for background tasks
* **Auth** (`auth`): Authentication and authorization
* **IdP** (`idp`): Built-in identity provider
* **Static Website** (`staticWebsites`): Static file hosting

## Adding a Service

To add a new service to your application, update your `tailor.config.ts` file with the service configuration. Each service requires you to specify glob patterns that match the files containing your service definitions.

### Example: Adding TailorDB

```typescript
import { defineConfig } from "@tailor-platform/sdk";

export default defineConfig({
  name: "my-app",
  db: {
    "my-database": {
      files: ["db/**/*.ts"],
    },
  },
});
```

This configuration tells the SDK to:

* Create a TailorDB service named "my-database"
* Load all TypeScript files from the `db/` directory

### Example: Adding Resolvers

```typescript
export default defineConfig({
  name: "my-app",
  resolver: {
    "my-resolver": {
      files: ["resolver/**/*.ts"],
    },
  },
});
```

### Example: Adding Multiple Services

You can configure multiple services in the same configuration file:

```typescript
export default defineConfig({
  name: "my-app",
  db: {
    "my-database": {
      files: ["db/**/*.ts"],
    },
  },
  resolver: {
    "my-resolver": {
      files: ["resolver/**/*.ts"],
    },
  },
  executor: {
    files: ["executors/**/*.ts"],
  },
  workflow: {
    files: ["workflows/**/*.ts"],
  },
});
```

## Deploying Changes

After updating your configuration, deploy the changes to your workspace:

```bash
npm run deploy -- --workspace-id <your-workspace-id>
```

The SDK will:

1. Load all service files matching your glob patterns
2. Generate the application endpoints for each configured service
3. Deploy them to your workspace

Your new service endpoints will be available in the GraphQL API after deployment completes.

## Next Steps

Learn more about configuring specific services:

* [TailorDB](../sdk/services/tailordb) - Database schema definition
* [Resolver](../sdk/services/resolver) - Custom GraphQL resolvers
* [Executor](../sdk/services/executor) - Event-driven handlers
* [Workflow](../sdk/services/workflow) - Job orchestration
* [Configuration](../sdk/configuration) - Complete configuration reference

---

---
url: https://docs.tailor.tech/tutorials/development-workflow.md
---
# Development Workflow

This guide covers the typical development workflow when building applications with the Tailor Platform SDK.

## Local Development

### Project Structure

A typical SDK project has the following structure:

```
my-app/
├── src/
│   ├── tailordb/        # Database schema definitions
│   ├── resolvers/       # Custom GraphQL resolvers
│   ├── executors/       # Event-driven handlers
│   └── index.ts         # Main entry point
├── tailor.config.ts     # SDK configuration
└── package.json
```

### Development Commands

```bash
# Start development with hot reload
npm run dev

# Generate TypeScript types
npm run generate

# Run tests
npm run test
```

## Deployment

### Deploy to a Workspace

```bash
# Deploy to your workspace
npm run deploy -- --workspace-id <your-workspace-id>
```

### Environment Management

Use environment variables for configuration:

```bash
# Set environment-specific values
TAILOR_WORKSPACE_ID=your-workspace-id npm run deploy
```

## Testing

The SDK supports testing your application logic:

```typescript
import { test, expect } from "vitest";
import hello from "./resolvers/hello";

test("hello resolver returns greeting", async () => {
  const result = await hello.body({
    input: { name: "World" },
  });
  expect(result.message).toBe("Hello, World!");
});
```

---

---
url: https://docs.tailor.tech/tutorials/resolver.md
---
# Creating Custom Resolvers

Resolvers are custom GraphQL endpoints that implement business logic. In this tutorial, you'll create a mutation resolver that assigns a task to a team member with validation.

* To follow along with this tutorial, first complete the [SDK Quickstart](../sdk/quickstart). It provides the app template that we'll build upon.

## Tutorial Steps

1. Set up the data schema
2. Configure the resolver service
3. Create the resolver
4. Deploy and test
5. View execution logs

## 1. Set up the Data Schema

First, create the necessary types in TailorDB. Create two files in your `db/` directory:

**Project Type:**

```typescript
import { db } from "@tailor-platform/sdk";

export const project = db.table("Project", {
  name: db.string().description("Project name"),
  description: db.string().optional().description("Project description"),
  status: db.enum(["active", "completed", "archived"]).description("Project status"),
  ...db.fields.timestamps(),
});
export type project = typeof project;
```

**Task and TeamMember Types:**

```typescript
import { db } from "@tailor-platform/sdk";
import { project } from "./project";

export const teamMember = db.table("TeamMember", {
  name: db.string().description("Team member name"),
  email: db.string().description("Team member email"),
  role: db.string().optional().description("Team member role"),
  ...db.fields.timestamps(),
});
export type teamMember = typeof teamMember;

export const task = db.table("Task", {
  title: db.string().description("Task title"),
  description: db.string().optional().description("Task description"),
  status: db.enum(["todo", "in_progress", "completed"]).description("Task status"),
  priority: db.enum(["low", "medium", "high"]).description("Task priority"),
  projectId: db
    .uuid()
    .relation({ type: "n-1", toward: { type: project } })
    .description("Associated project"),
  assigneeId: db
    .uuid()
    .relation({ type: "n-1", toward: { type: teamMember } })
    .optional()
    .description("Assigned team member"),
  dueDate: db.string().optional().description("Due date"),
  ...db.fields.timestamps(),
});
export type task = typeof task;
```

## 2. Configure the Resolver Service

Update your `tailor.config.ts` to include the resolver service:

```typescript
import { defineConfig } from "@tailor-platform/sdk";

export default defineConfig({
  name: "project-management",
  db: {
    "project-db": {
      files: ["db/**/*.ts"],
    },
  },
  resolver: {
    "project-resolver": {
      files: ["resolver/**/*.ts"],
    },
  },
});
```

This configures the SDK to load resolver definitions from the `resolver/` directory.

## 3. Create the Resolver

Create a new file `resolver/assign-task.ts` with the following resolver definition:

```typescript
import { createResolver, t } from "@tailor-platform/sdk";
import { getDB } from "../generated/tailordb";

export default createResolver({
  name: "assignTask",
  operation: "mutation",
  description: "Assign a task to a team member with validation",
  input: {
    taskId: t.string().description("ID of the task to assign"),
    assigneeId: t.string().description("ID of the team member"),
    dueDate: t.string().optional().description("Optional due date"),
  },
  body: async (context) => {
    const db = getDB("project-db");

    // Check if task exists
    const task = await db
      .selectFrom("Task")
      .selectAll()
      .where("id", "=", context.input.taskId)
      .executeTakeFirstOrThrow();

    // Check if assignee exists
    const assignee = await db
      .selectFrom("TeamMember")
      .selectAll()
      .where("id", "=", context.input.assigneeId)
      .executeTakeFirstOrThrow();

    // Update task
    await db
      .updateTable("Task")
      .set({
        assigneeId: context.input.assigneeId,
        status: "in_progress",
        dueDate: context.input.dueDate || task.dueDate,
        updatedAt: new Date().toISOString(),
      })
      .where("id", "=", context.input.taskId)
      .execute();

    return {
      taskId: task.id,
      taskTitle: task.title,
      assigneeName: assignee.name,
      message: `Task "${task.title}" assigned to ${assignee.name}`,
    };
  },
  output: t.object({
    taskId: t.string().description("ID of the assigned task"),
    taskTitle: t.string().description("Title of the task"),
    assigneeName: t.string().description("Name of the assignee"),
    message: t.string().description("Success message"),
  }),
});
```

### How This Resolver Works

1. **Input Validation**: The resolver accepts `taskId`, `assigneeId`, and an optional `dueDate`
2. **Database Queries**: Uses Kysely query builder to fetch task and team member records
3. **Validation**: Throws an error if the task or assignee doesn't exist (via `executeTakeFirstOrThrow()`)
4. **Update Logic**: Updates the task with the new assignee, changes status to "in\_progress", and updates the timestamp
5. **Response**: Returns the task details and a success message

## 4. Deploy and Test

First, generate Kysely types for type-safe database queries:

```bash
npm run generate
```

This generates TypeScript types and the `getDB()` helper in the `generated/` directory based on your TailorDB schema.

Then deploy your changes to the workspace:

```bash
npm run deploy -- --workspace-id <your-workspace-id>
```

The SDK will deploy your TailorDB schema and the resolver to your workspace.

### Test the Resolver

First, create some test data. Open the GraphQL Playground in the [Console](https://console.tailor.tech) and create a project, team member, and task:

```graphql
mutation {
  createProject(
    input: {
      name: "Website Redesign"
      description: "Redesign company website"
      status: "active"
      createdAt: "2026-02-09T10:00:00Z"
    }
  ) {
    id
    name
  }
}

mutation {
  createTeamMember(
    input: { name: "Alice Johnson", email: "alice@example.com", role: "Developer" }
  ) {
    id
    name
  }
}

mutation {
  createTask(
    input: {
      title: "Design homepage mockup"
      description: "Create initial design concepts"
      status: "todo"
      priority: "high"
      projectId: "<project-id>"
      createdAt: "2026-02-09T10:00:00Z"
      updatedAt: "2026-02-09T10:00:00Z"
    }
  ) {
    id
    title
  }
}
```

Now test the `assignTask` resolver:

```graphql
mutation {
  assignTask(
    input: { taskId: "<task-id>", assigneeId: "<team-member-id>", dueDate: "2026-02-15T17:00:00Z" }
  ) {
    taskId
    taskTitle
    assigneeName
    message
  }
}
```

Expected response:

```json
{
  "data": {
    "assignTask": {
      "taskId": "<task-id>",
      "taskTitle": "Design homepage mockup",
      "assigneeName": "Alice Johnson",
      "message": "Task \"Design homepage mockup\" assigned to Alice Johnson"
    }
  }
}
```

## 5. View Execution Logs

You can view resolver execution logs in the [Console](https://console.tailor.tech). Navigate to your workspace and select the `Execution Logs` tab to see:

* Input parameters for each resolver call
* Execution time and status
* Response data or error messages
* Database queries performed

This helps you debug issues and understand how your resolver processes requests.

## Advanced: Triggering Executors from Resolvers

You can configure resolvers to publish events when they execute, allowing executors to trigger automatically after resolver execution. This is useful for post-processing tasks like sending notifications or updating related data.

```typescript
export default createResolver({
  name: "assignTask",
  operation: "mutation",
  publishEvents: true, // Enable event publishing
  // ... rest of resolver config
});
```

**How it works:**

* When `publishEvents: true`, the resolver publishes execution events
* Executors can listen for these events using `resolverExecutedTrigger()`
* The SDK **automatically enables** `publishEvents` when an executor references the resolver

**Example executor that triggers after resolver execution:**

```typescript
import { createExecutor, resolverExecutedTrigger } from "@tailor-platform/sdk";
import assignTaskResolver from "../resolver/assign-task";

export default createExecutor({
  name: "notify-task-assigned",
  trigger: resolverExecutedTrigger({
    resolver: assignTaskResolver,
    condition: ({ result, error }) => !error && !!result.taskId,
  }),
  operation: {
    kind: "function",
    body: async ({ result }) => {
      console.log(`Task ${result.taskId} assigned to ${result.assigneeName}`);
      // Send notification logic here
    },
  },
});
```

For more details, see [Executor Service - Resolver Executed Trigger](../sdk/services/executor#resolver-executed-trigger).

## Next Steps

Learn more about resolvers:

* [Resolver Guide](../guides/resolver) - Complete resolver guide with examples
* [Input Validation](../guides/tailordb/validations) - Add validation rules to your data
* [TailorDB Overview](../guides/tailordb/overview) - Learn about database schema and queries

---

---
url: https://docs.tailor.tech/tutorials/develop-from-scratch/overview.md
---
# Develop from Scratch with Tailor Platform SDK

Build a project management app with database types, auth, resolvers, and executors using TypeScript.

## Prerequisites

* **Node.js 22+**
* **Tailor Platform workspace** — create one at [console.tailor.tech](https://console.tailor.tech). Note your workspace ID.

## Steps

| Step                                                                  | What's Added                                    | Key Files                                                          |
| --------------------------------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------ |
| [Step 1: Database Schema](/tutorials/develop-from-scratch/step-01)    | Project scaffolding, User/Project/Task types    | `package.json`, `tsconfig.json`, `tailor.config.ts`, `src/db/*.ts` |
| [Step 2: Auth & Permissions](/tutorials/develop-from-scratch/step-02) | Auth namespace, machine users, permission rules | `src/common/permission.ts`, updated `src/db/*.ts`                  |
| [Step 3: Resolver](/tutorials/develop-from-scratch/step-03)           | closeProject mutation, Kysely type generator    | `src/resolver/closeProject.ts`, `src/generated/tailordb.ts`        |
| [Step 4: Executor](/tutorials/develop-from-scratch/step-04)           | Slack notification on task creation             | `src/executor/newTaskSlackNotification.ts`                         |

## Final File Tree

```
project-management/
├── package.json
├── tsconfig.json
├── tailor.config.ts
└── src/
    ├── common/permission.ts
    ├── db/
    │   ├── user.ts
    │   ├── project.ts
    │   └── task.ts
    ├── generated/tailordb.ts        # auto-generated
    ├── resolver/closeProject.ts
    └── executor/newTaskSlackNotification.ts
```

## Code Repository

[github.com/tailor-platform/templates/tree/main/docs/build-from-scratch/sdk](https://github.com/tailor-platform/templates/tree/main/docs/build-from-scratch/sdk)

## Additional Resources

* [Tailor Platform SDK Documentation](../../sdk/quickstart)
* [TailorDB Service](../../sdk/services/tailordb)
* [Resolver Service](../../sdk/services/resolver)
* [Executor Service](../../sdk/services/executor)
* [Auth Service](../../sdk/services/auth)

---

---
url: https://docs.tailor.tech/tutorials/develop-from-scratch/step-01.md
---
# Step 1: Create Database Schema

This step establishes the foundational database schema for your project management application using the Tailor Platform SDK. You'll define three core types (User, Project, Task) with relationships and automatic timestamp management, all using type-safe TypeScript.

[Source code on GitHub](https://github.com/tailor-platform/templates/tree/main/docs/build-from-scratch/sdk/step-01)

## Project Setup

```json {{title: 'package.json'}}
{
  "name": "project-management",
  "private": true,
  "type": "module",
  "scripts": {
    "deploy": "tailor apply",
    "generate": "tailor generate"
  },
  "dependencies": {
    "@tailor-platform/function-kysely-tailordb": "0.1.3",
    "kysely": "0.28.10"
  },
  "devDependencies": {
    "@tailor-platform/sdk": "latest",
    "typescript": "5.9.3"
  }
}
```

```json {{title: 'tsconfig.json'}}
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "allowSyntheticDefaultImports": true,
    "esModuleInterop": true,
    "allowJs": true,
    "strict": true,
    "noEmit": true,
    "skipLibCheck": true,
    "resolveJsonModule": true,
    "types": ["node", "@tailor-platform/function-types"]
  },
  "include": ["**/*.ts"]
}
```

## Configuration Files

```typescript {{title: 'tailor.config.ts'}}
import { defineConfig } from "@tailor-platform/sdk";

export default defineConfig({
  name: "project-management",
  db: { "main-db": { files: [`./src/db/*.ts`] } },
});
```

> `db.enum()` takes a **single array argument**: `db.enum(["A", "B"])`, not `db.enum("A", "B")`.

```typescript {{title: 'src/db/user.ts'}}
import { db } from "@tailor-platform/sdk";

export const user = db.table("User", {
  name: db.string().description("Name of the user"),
  email: db.string().unique().description("Email address of the user"),
  role: db.enum(["MANAGER", "STAFF"]),
  ...db.fields.timestamps(),
});
```

```typescript {{title: 'src/db/project.ts'}}
import { db } from "@tailor-platform/sdk";

export const project = db.table("Project", {
  name: db.string().description("Name of the Project"),
  description: db.string({ optional: true }).description("Description of the project"),
  status: db.enum([
    { value: "PLANNING", description: "Planning status" },
    { value: "IN_PROGRESS", description: "In Progress status" },
    { value: "ON_HOLD", description: "On hold status" },
    { value: "COMPLETED", description: "Completed status" },
    { value: "CANCELED", description: "Canceled status" },
    { value: "CLOSED", description: "Closed status" },
  ]),
  startDate: db.date().description("Start date of the project"),
  endDate: db.date({ optional: true }).description("End date of the project"),
  ...db.fields.timestamps(),
});
```

```typescript {{title: 'src/db/task.ts'}}
import { db } from "@tailor-platform/sdk";
import { project } from "./project";
import { user } from "./user";

export const task = db.table("Task", {
  name: db.string().description("Name of the Task"),
  description: db.string({ optional: true }).description("Description of the task"),
  projectId: db
    .uuid()
    .description("ID of the project the task belongs to")
    .relation({ type: "n-1", toward: { type: project } }),
  assigneeId: db
    .uuid({ optional: true })
    .description("ID of the user assigned to the task")
    .relation({ type: "n-1", toward: { type: user } }),
  status: db.enum([
    { value: "TODO", description: "To Do status" },
    { value: "IN_PROGRESS", description: "In Progress status" },
    { value: "IN_REVIEW", description: "In Review status" },
    { value: "DONE", description: "Done status" },
    { value: "CANCELED", description: "Canceled status" },
  ]),
  dueDate: db.date().description("Due date of the task"),
  ...db.fields.timestamps(),
});
```

## File Tree

```
project-management/
├── package.json
├── tsconfig.json
├── tailor.config.ts
└── src/
    └── db/
        ├── user.ts
        ├── project.ts
        └── task.ts
```

## Deploy

The workspace is provided at deploy time, not in `tailor.config.ts`. Pass it via the `TAILOR_PLATFORM_WORKSPACE_ID` environment variable (or the `--workspace-id` flag). On the first deploy, the SDK injects a stable `id` into `tailor.config.ts` to track the application across renames — keep it under version control.

```bash
npm install
export TAILOR_PLATFORM_WORKSPACE_ID=your-workspace-id
npm run deploy
# or: npm run deploy -- --workspace-id your-workspace-id
```

## Next Step

[Step 2: Add Authentication](/tutorials/develop-from-scratch/step-02)

---

---
url: https://docs.tailor.tech/tutorials/develop-from-scratch/step-02.md
---
# Step 2: Add Authentication and Permissions

This step adds authentication capabilities to your project management application. You'll configure user profile management linked to your User type and create machine users for different roles, enabling secure access control and automated operations. You will also implement role-based permissions to control data access.

[Source code on GitHub](https://github.com/tailor-platform/templates/tree/main/docs/build-from-scratch/sdk/step-02)

## Configuration Files

```typescript {{title: 'tailor.config.ts'}}
import { defineAuth, defineConfig } from "@tailor-platform/sdk";
import { user } from "./src/db/user";

export default defineConfig({
  name: "project-management",
  db: { "main-db": { files: [`./src/db/*.ts`] } },
  auth: defineAuth("main-auth", {
    userProfile: {
      type: user,
      usernameField: "email",
      attributes: {
        role: true,
      },
    },
    machineUsers: {
      manager: {
        attributes: { role: "MANAGER" },
      },
      staff: {
        attributes: { role: "STAFF" },
      },
    },
  }),
});
```

```typescript {{title: 'src/common/permission.ts'}}
import type {
  PermissionCondition,
  TailorTypeGqlPermission,
  TailorTypePermission,
} from "@tailor-platform/sdk";

export interface User {
  role: string;
}

export const loggedIn = [{ user: "_loggedIn" }, "=", true] as const satisfies PermissionCondition;

export const permissionLoggedIn = {
  create: [loggedIn],
  read: [loggedIn],
  update: [loggedIn],
  delete: [loggedIn],
} as const satisfies TailorTypePermission;

export const gqlPermissionLoggedIn = [
  {
    conditions: [loggedIn],
    actions: "all",
    permit: true,
  },
] as const satisfies TailorTypeGqlPermission;
```

All three types now import and apply permissions via `.permission()` (record-level) and `.gqlPermission()` (GraphQL-level). Both layers must pass for an operation to succeed.

```typescript {{title: 'src/db/user.ts'}}
import { db } from "@tailor-platform/sdk";
import { gqlPermissionLoggedIn, permissionLoggedIn } from "../common/permission";

export const user = db
  .table("User", {
    name: db.string().description("Name of the user"),
    email: db.string().unique().description("Email address of the user"),
    role: db.enum(["MANAGER", "STAFF"]),
    ...db.fields.timestamps(),
  })
  .permission(permissionLoggedIn)
  .gqlPermission(gqlPermissionLoggedIn);
```

```typescript {{title: 'src/db/project.ts'}}
import { db } from "@tailor-platform/sdk";
import { gqlPermissionLoggedIn, permissionLoggedIn } from "../common/permission";

export const project = db
  .table("Project", {
    name: db.string().description("Name of the Project"),
    description: db.string({ optional: true }).description("Description of the project"),
    status: db.enum([
      { value: "PLANNING", description: "Planning status" },
      { value: "IN_PROGRESS", description: "In Progress status" },
      { value: "ON_HOLD", description: "On hold status" },
      { value: "COMPLETED", description: "Completed status" },
      { value: "CANCELED", description: "Canceled status" },
      { value: "CLOSED", description: "Closed status" },
    ]),
    startDate: db.date({ optional: true }).description("Start date of the project"),
    endDate: db.date({ optional: true }).description("End date of the project"),
    ...db.fields.timestamps(),
  })
  .permission(permissionLoggedIn)
  .gqlPermission(gqlPermissionLoggedIn);
```

```typescript {{title: 'src/db/task.ts'}}
import { db } from "@tailor-platform/sdk";
import { project } from "./project";
import { user } from "./user";
import { gqlPermissionLoggedIn, permissionLoggedIn } from "../common/permission";

export const task = db
  .table("Task", {
    name: db.string().description("Name of the Task"),
    description: db.string({ optional: true }).description("Description of the task"),
    projectId: db
      .uuid()
      .description("ID of the project the task belongs to")
      .relation({ type: "n-1", toward: { type: project } }),
    assigneeId: db
      .uuid({ optional: true })
      .description("ID of the user assigned to the task")
      .relation({ type: "n-1", toward: { type: user } }),
    status: db.enum([
      { value: "TODO", description: "To Do status" },
      { value: "IN_PROGRESS", description: "In Progress status" },
      { value: "IN_REVIEW", description: "In Review status" },
      { value: "DONE", description: "Done status" },
      { value: "CANCELED", description: "Canceled status" },
    ]),
    dueDate: db.date().description("Due date of the task"),
    ...db.fields.timestamps(),
  })
  .permission(permissionLoggedIn)
  .gqlPermission(gqlPermissionLoggedIn);
```

## File Tree

```
project-management/
├── package.json
├── tsconfig.json
├── tailor.config.ts
└── src/
    ├── common/
    │   └── permission.ts          # New
    └── db/
        ├── user.ts                # Updated with permissions
        ├── project.ts             # Updated with permissions
        └── task.ts                # Updated with permissions
```

## Deploy

```bash
npm run deploy
```

## Next Step

[Step 3: Add Resolver](/tutorials/develop-from-scratch/step-03)

---

---
url: https://docs.tailor.tech/tutorials/develop-from-scratch/step-03.md
---
# Step 3: Add Resolver

Add a `closeProject` mutation that cancels incomplete tasks and closes a project in a transaction. Also adds an `admin` machine user and Kysely type generator.

[Source code on GitHub](https://github.com/tailor-platform/templates/tree/main/docs/build-from-scratch/sdk/step-03)

## Configuration Files

Changes from Step 2: added `admin` machine user, `resolver` namespace, and `plugins` export.

> Since the `admin` machine user uses `role: "ADMIN"`, update `src/db/user.ts` to include it: `db.enum(["MANAGER", "STAFF", "ADMIN"])`.

```typescript {{title: 'tailor.config.ts'}}
import { defineAuth, defineConfig, definePlugins } from "@tailor-platform/sdk";
import { kyselyTypePlugin } from "@tailor-platform/sdk/plugin/kysely-type";
import { user } from "./src/db/user";

export default defineConfig({
  name: "project-management",
  db: { "main-db": { files: [`./src/db/*.ts`] } },
  auth: defineAuth("main-auth", {
    userProfile: {
      type: user,
      usernameField: "email",
      attributes: {
        role: true,
      },
    },
    machineUsers: {
      manager: {
        attributes: { role: "MANAGER" },
      },
      staff: {
        attributes: { role: "STAFF" },
      },
      admin: {
        attributes: { role: "ADMIN" },
      },
    },
  }),
  resolver: { "main-resolver": { files: [`./src/resolver/*.ts`] } },
});

export const plugins = definePlugins(kyselyTypePlugin({ distPath: `./src/generated/tailordb.ts` }));
```

> For optional output fields, use `t.string({ optional: true })`, not `t.string().optional()`. The `.optional()` chain does not exist.

```typescript {{title: 'src/resolver/closeProject.ts'}}
import { createResolver, t } from "@tailor-platform/sdk";
import { getDB } from "../generated/tailordb";

export default createResolver({
  name: "closeProject",
  operation: "mutation",
  input: {
    id: t.string(),
  },
  body: async (context) => {
    const db = getDB("main-db");

    // 1. Fetch the project
    const project = await db
      .selectFrom("Project")
      .selectAll()
      .where("id", "=", context.input.id)
      .executeTakeFirst();

    if (!project) {
      throw new Error(`Project not found, expected:1 got:0`);
    }

    if (project.status === "CLOSED") {
      return { result: "Project is already closed." };
    }

    // 2. Get all incomplete tasks for the project
    const incompleteTasks = await db
      .selectFrom("Task")
      .selectAll()
      .where("projectId", "=", context.input.id)
      .where("status", "!=", "DONE")
      .execute();

    // 3. Start a transaction
    await db.transaction().execute(async (trx: any) => {
      // Mark all incomplete tasks as canceled
      for (const task of incompleteTasks) {
        await trx
          .updateTable("Task")
          .set({ status: "CANCELED" })
          .where("id", "=", task.id)
          .execute();
      }
      // Close the project
      await trx
        .updateTable("Project")
        .set({ status: "CLOSED" })
        .where("id", "=", context.input.id)
        .execute();
    });

    return {
      result: `${context.input.id} project has been closed. All incomplete tasks are marked as canceled.`,
    };
  },
  output: t.object({
    result: t.string({ optional: true }),
  }),
});
```

## File Tree

```
project-management/
├── package.json
├── tsconfig.json
├── tailor.config.ts
└── src/
    ├── common/permission.ts
    ├── db/
    │   ├── user.ts                    # Updated: add ADMIN to role enum
    │   ├── project.ts
    │   └── task.ts
    ├── generated/
    │   └── tailordb.ts                # Auto-generated
    └── resolver/
        └── closeProject.ts            # New
```

## Deploy

> You must run `generate` before `deploy` whenever you add or change database types.

```bash
npm run generate
npm run deploy
```

## Verify

```graphql
mutation {
  closeProject(input: { id: "project-uuid-here" }) {
    result
  }
}
```

## Next Step

[Step 4: Add Executor](/tutorials/develop-from-scratch/step-04)

---

---
url: https://docs.tailor.tech/tutorials/develop-from-scratch/step-04.md
---
# Step 4: Add Executor

Add an executor that sends a Slack notification whenever a Task is created.

[Source code on GitHub](https://github.com/tailor-platform/templates/tree/main/docs/build-from-scratch/sdk/step-04)

## Configuration Files

Only change from Step 3: added `executor` to `tailor.config.ts`.

```typescript {{title: 'tailor.config.ts'}}
import { defineAuth, defineConfig, definePlugins } from "@tailor-platform/sdk";
import { kyselyTypePlugin } from "@tailor-platform/sdk/plugin/kysely-type";
import { user } from "./src/db/user";

export default defineConfig({
  name: "project-management",
  db: { "main-db": { files: [`./src/db/*.ts`] } },
  auth: defineAuth("main-auth", {
    userProfile: {
      type: user,
      usernameField: "email",
      attributes: {
        role: true,
      },
    },
    machineUsers: {
      manager: {
        attributes: { role: "MANAGER" },
      },
      staff: {
        attributes: { role: "STAFF" },
      },
      admin: {
        attributes: { role: "ADMIN" },
      },
    },
  }),
  resolver: { "main-resolver": { files: [`./src/resolver/*.ts`] } },
  executor: { files: ["./src/executor/*.ts"] },
});

export const plugins = definePlugins(kyselyTypePlugin({ distPath: `./src/generated/tailordb.ts` }));
```

`createExecutor` takes an object config with `name`, `trigger`, and `operation`. The trigger `recordCreatedTrigger` takes `{ type: task }`. Available trigger context: `newRecord` (created), `oldRecord`/`newRecord` (updated), `oldRecord` (deleted).

```typescript {{title: 'src/executor/newTaskSlackNotification.ts'}}
import { createExecutor, recordCreatedTrigger } from "@tailor-platform/sdk";
import { task } from "../db/task";

export default createExecutor({
  name: "new-task-slack-notification",
  description: "Send Slack notification when a new task is created",
  trigger: recordCreatedTrigger({
    type: task,
  }),
  operation: {
    kind: "webhook",
    url: "https://hooks.slack.com/services/yourSlackWebhookURL",
    headers: {
      "Content-Type": "application/json",
    },
    requestBody: ({ newRecord }) => ({
      text: "New Task created :tada: " + newRecord.name,
    }),
  },
});
```

## File Tree

```
project-management/
├── package.json
├── tsconfig.json
├── tailor.config.ts
└── src/
    ├── common/permission.ts
    ├── db/
    │   ├── user.ts
    │   ├── project.ts
    │   └── task.ts
    ├── generated/tailordb.ts
    ├── resolver/closeProject.ts
    └── executor/
        └── newTaskSlackNotification.ts    # New
```

## Deploy

```bash
npm run generate
npm run deploy
```

## Verify

```graphql
mutation {
  createTask(
    input: {
      name: "Test notification"
      description: "Testing executor"
      projectId: "your-project-id"
      status: TODO
      dueDate: "2025-12-31"
    }
  ) {
    id
    name
  }
}
```

Check your Slack channel for the notification. If it doesn't appear, verify the webhook URL is correct and test it directly:

```bash
curl -X POST https://hooks.slack.com/services/YOUR_WEBHOOK_URL \
  -H "Content-Type: application/json" \
  -d '{"text": "Test message"}'
```

## Additional Resources

* [Executor Guide](/guides/executor/overview)
* [Webhook Triggers Documentation](/guides/executor/incoming-webhook-trigger)

---

---
url: https://docs.tailor.tech/tutorials/manage-data-schema/overview.md
---
# Managing Data Schema with Tailor Platform

Tailor Platform offers a powerful feature that allows you to generate GraphQL APIs from schema files. This makes it easy for your company to create a custom data schema that aligns perfectly with your business requirements.

The main database in Tailor Platform, where you store and retrieve your data, is called TailorDB. With TailorDB, you can effortlessly modify existing data schemas (data models) in our templates or add new tables (equivalent to tables in a relational database). The GraphQL endpoint will be automatically generated, eliminating the need for additional coding.

This tutorial introduces you to TailorDB. In the subsequent tutorials, you'll learn how to add fields to existing tables, how to create new tables and how to validate fields for your application.

## What you'll learn

* [Basics of data schema](/tutorials/manage-data-schema/data-schema-basics)
* [Modify schema](/tutorials/manage-data-schema/modify-data-schema)
* [Create schema](/tutorials/manage-data-schema/create-data-schema)
* [Validate fields](/tutorials/manage-data-schema/validate-field-data)

## Prerequisite

* Complete [Quickstart](/getting-started/quickstart)&#x20;

---

---
url: https://docs.tailor.tech/tutorials/manage-data-schema/create-data-schema.md
---
# Adding a New Data Model

With Tailor Platform's TailorDB, you can easily add new tables (data models) to your application. The GraphQL API will be automatically generated for the new table.

This tutorial demonstrates how to create a new data schema using the SDK.

* See [Core Concepts](/getting-started/core-concepts/) to get an overview of Workspace, Organization, Application and Service.
* To follow along with this tutorial, first complete the [SDK Quickstart](../../sdk/quickstart) and the [Data Schema Basics](data-schema-basics) tutorial.

## Tutorial Steps

To create a `Task` table in TailorDB, you'll need to:

1. Define the `Task` schema
2. Deploy the change
3. Verify the schema change through GraphQL

### 1. Define the Task Schema

Create a new file `db/task.ts` in your project and define the Task table:

```typescript
import { db } from "@tailor-platform/sdk";
import { project } from "./project";

export const task = db.table("Task", {
  title: db.string().description("Task title"),
  description: db.string().optional().description("Task description"),
  status: db
    .enum(["todo", "in_progress", "completed", "blocked"])
    .description("Current task status"),
  priority: db.enum(["low", "medium", "high", "urgent"]).description("Task priority level"),
  projectId: db
    .uuid()
    .relation({ type: "n-1", toward: { type: project } })
    .description("Associated project"),
  assigneeId: db.string().optional().description("ID of assigned team member"),
  dueDate: db.string().optional().description("Task due date"),
  estimatedHours: db.float().optional().description("Estimated hours to complete"),
  ...db.fields.timestamps(),
});
export type task = typeof task;
```

**Schema Explanation:**

* **title**: Required string field for the task name
* **description**: Optional detailed description
* **status**: Enumeration with predefined status values
* **priority**: Enumeration for priority levels
* **projectId**: Many-to-one relation to the Project table
* **assigneeId**: Optional reference to a team member
* **dueDate**: Optional date field
* **estimatedHours**: Optional float for time estimation
* **createdAt/updatedAt**: Timestamp fields

Fields like `id` are automatically generated without being explicitly defined. See [Auto-generated Fields](../../sdk/services/tailordb#auto-generated-fields) for more information.

### 2. Deploy the Change

Deploy the new Task table to your workspace:

```bash
npm run deploy -- --workspace-id <your-workspace-id>
```

The SDK will:

* Detect the new table definition
* Create the Task table in TailorDB
* Generate the GraphQL API for the Task table

### 3. Verify Schema Change Through GraphQL

The SDK automatically generates the following GraphQL APIs for the `Task` table:

* **Queries**: `task`, `tasks` - Fetch task data
* **Mutations**: `createTask`, `updateTask`, `deleteTask` - Modify task data

Open the GraphQL Playground in the [Console](https://console.tailor.tech) and test the new API.

First, ensure you have a project created (from the previous tutorials). Then create a task:

```graphql
mutation {
  createTask(
    input: {
      title: "Design homepage mockup"
      description: "Create initial design concepts for the new homepage"
      status: "todo"
      priority: "high"
      projectId: "<your-project-id>"
      estimatedHours: 8.0
      dueDate: "2026-02-15T17:00:00Z"
      createdAt: "2026-02-09T10:00:00Z"
      updatedAt: "2026-02-09T10:00:00Z"
    }
  ) {
    id
    title
    status
    priority
  }
}
```

Example response:

```json
{
  "data": {
    "createTask": {
      "id": "a80ccddb-2f42-4ac3-a298-a6a766a24316",
      "title": "Design homepage mockup",
      "status": "todo",
      "priority": "high"
    }
  }
}
```

You can view the Task resource values in the [Console](https://console.tailor.tech).

Query the task to verify all fields:

```graphql
query {
  task(id: "a80ccddb-2f42-4ac3-a298-a6a766a24316") {
    id
    title
    description
    status
    priority
    projectId
    assigneeId
    dueDate
    estimatedHours
    createdAt
    updatedAt
  }
}
```

Example response:

```json
{
  "data": {
    "task": {
      "id": "a80ccddb-2f42-4ac3-a298-a6a766a24316",
      "title": "Design homepage mockup",
      "description": "Create initial design concepts for the new homepage",
      "status": "todo",
      "priority": "high",
      "projectId": "<your-project-id>",
      "assigneeId": null,
      "dueDate": "2026-02-15T17:00:00Z",
      "estimatedHours": 8.0,
      "createdAt": "2026-02-09T10:00:00Z",
      "updatedAt": "2026-02-09T10:00:00Z"
    }
  }
}
```

You can also query all tasks:

```graphql
query {
  tasks {
    edges {
      node {
        id
        title
        status
        priority
        dueDate
      }
    }
  }
}
```

## Next Steps

Now that you've created a new table, explore more advanced features:

* [Relationships](../../sdk/services/tailordb#relationships) - Define relations between tables
* [Field Types](../../sdk/services/tailordb#field-types) - Learn about all available field types
* [Indexes](../../sdk/services/tailordb#indexes) - Optimize query performance
* [Hooks](../../sdk/services/tailordb#hooks) - Add automatic field population

## Further Information

* [TailorDB Service](../../sdk/services/tailordb) - Complete TailorDB documentation
* [Schema Design Best Practices](../../sdk/services/tailordb#best-practices) - Tips for effective schema design

---

---
url: https://docs.tailor.tech/tutorials/manage-data-schema/data-schema-basics.md
---
# Data Schema in Tailor Platform

This tutorial demonstrates how a data schema is mapped to GraphQL APIs using the SDK.

* Complete the [SDK Quickstart](../../sdk/quickstart)

## Data Schema

A data model of your application is defined by the schema. Each table is typically defined in its own file for readability. See [TailorDB Documentation](../../sdk/services/tailordb) to learn more about schema definition.

## Tutorial Steps

1. Define a data table
2. View the schema in GraphQL playground
3. See how the configuration maps to GraphQL APIs

### 1. Define a Data Table

Create a `Project` table in your application. In your project's `db/` directory, create a file called `project.ts`:

```typescript
import { db } from "@tailor-platform/sdk";

export const project = db.table("Project", {
  name: db.string().description("Project name"),
  description: db.string().optional().description("Project description"),
  status: db
    .enum(["planning", "active", "completed", "archived"])
    .description("Current project status"),
  startDate: db.string().optional().description("Project start date"),
  endDate: db.string().optional().description("Project end date"),
  budget: db.float().optional().description("Project budget"),
  priority: db.enum(["low", "medium", "high", "critical"]).description("Project priority level"),
  ...db.fields.timestamps(),
});
export type project = typeof project;
```

This TypeScript file defines a `Project` table with various fields:

* **name**: Required string field for the project name
* **description**: Optional string field for project details
* **status**: Enumeration field with predefined values
* **startDate/endDate**: Optional date fields
* **budget**: Optional float field for financial tracking
* **priority**: Enumeration for priority levels
* **createdAt/updatedAt**: Timestamp fields for tracking changes

Deploy this schema using:

```bash
npm run deploy -- --workspace-id <your-workspace-id>
```

### 2. View the Schema in GraphQL Playground

Open the GraphQL playground by navigating to the [Console](https://console.tailor.tech) and selecting your workspace. Click on "GraphQL Playground" to access the interactive API explorer.

### 3. See How the Configuration Maps to GraphQL APIs

Now that you've seen the schema definition in the TypeScript file, let's explore how this maps to the GraphQL API. In the GraphQL playground, you can test the API with a query like the one below:

```graphql
query {
  projects {
    edges {
      node {
        id
        name
        description
        status
        priority
        startDate
        endDate
        budget
        createdAt
        updatedAt
      }
    }
  }
}
```

This query will return a list of `Project` objects with the specified fields. You can see how the schema defined in the TypeScript file is automatically converted to GraphQL types and operations.

You'll notice some fields like `id` are generated automatically without being explicitly defined in the schema. These are pre-defined fields. Please refer to [Auto-generated fields](../../sdk/services/tailordb#auto-generated-fields) for more information.

The SDK automatically creates:

* **Query operations**: `project`, `projects` for fetching data
* **Mutation operations**: `createProject`, `updateProject`, `deleteProject` for modifying data
* **Connection types**: For pagination support with `edges` and `node` structure

## Next Steps

Learn more about working with data schemas:

* [TailorDB Service](../../sdk/services/tailordb) - Complete TailorDB reference
* [Field Types](../../sdk/services/tailordb#field-types) - Available field types and options
* [Relationships](../../sdk/services/tailordb#relationships) - Define relations between tables
* [Modifying Data Schema](modify-data-schema) - How to update existing schemas
* [Creating Data Schema](create-data-schema) - Add new tables to your application

---

---
url: https://docs.tailor.tech/tutorials/manage-data-schema/import-csv-file.md
---
# Import CSV files

CSV files are plain text files that contain tabular data, with each field separated by a comma.

To import data from a CSV file to the TailorDB, you can use the [Console](https://console.tailor.tech).

## 1. Select workspace

Log into the Console, select the workspace, and click on `TailorDB -- main-db` option.

## 2. Select type

Select `Project` type, choose `Data` tab and click on `import` button.

![Tailor Console - Data import](./../assets/tutorials-console-data-import.png)

## 3. Upload a CSV file

Here you can download the template by clicking on the button `Download Template`. The example.csv file contains the header of the file.

![Tailor Console - Data import upload](./../assets/tutorials-console-data-import-upload.png)

```
id,name,description,status,startDate,endDate,budget,priority,createdAt,updatedAt
```

Add the following data to the example.csv to create a new product in TailorDB.

```
Website Redesign,Complete overhaul of company website with modern UI/UX,IN_PROGRESS,2024-01-15,2024-06-30,2024-01-10T10:00:00Z,2024-02-09T15:30:00Z
Mobile App Development,Develop iOS and Android mobile applications,PLANNING,2024-03-01,2024-12-31,2024-02-01T09:00:00Z,2024-02-09T14:20:00Z
Marketing Campaign Q1,Launch new product marketing campaign,COMPLETED,2024-01-01,2024-03-31,2023-12-15T08:00:00Z,2024-04-01T16:45:00Z
Infrastructure Upgrade,Upgrade server infrastructure and cloud services,IN_PROGRESS,2024-02-01,2024-05-31,2024-01-20T11:30:00Z,2024-02-08T10:15:00Z
Customer Support Portal,Build self-service customer support platform,PLANNING,2024-04-01,2024-09-30,2024-02-05T13:00:00Z,2024-02-09T09:30:00Z
Database Migration,Migrate legacy database to modern architecture,COMPLETED,2023-06-01,2023-12-31,2023-05-15T07:00:00Z,2024-01-15T18:00:00Z
```

## 4. Map Columns

You can include the columns into which you want to insert data. Click on `Submit` after making your selections.

![Tailor Console - Data import map columns](./../assets/tutorials-console-data-import-map-columns.png)

## 5. Verify the import

After completing the import, the table populates with the new data, and a message displays details about the number of imported rows.

![Tailor Console - Data import message](./../assets/tutorials-console-data-import-message.png)

---

---
url: https://docs.tailor.tech/tutorials/manage-data-schema/modify-data-schema.md
---
# Adding a New Field to Data Model

Tailor Platform makes it easy to modify data schemas. With TailorDB, you can modify existing data tables and the GraphQL endpoint will be automatically generated.

This tutorial demonstrates how to add a new field to an existing data table using the SDK.

* See [Core Concepts](/getting-started/core-concepts/) to get an overview of Workspace, Organization, Application and Service.
* To follow along with this tutorial, first complete the [SDK Quickstart](../../sdk/quickstart) and the [Data Schema Basics](data-schema-basics) tutorial.

## TailorDB

TailorDB is a service that enables you to manage data schemas and automatically generate GraphQL APIs based on those schemas. See [TailorDB Service Documentation](../../sdk/services/tailordb) for more information.

## Tutorial Steps

To add a new `teamSize` field to the `Project` table, you will:

1. Add the `teamSize` field to the `Project` table
2. Deploy the change
3. Verify the schema change through GraphQL

### 1. Add the `teamSize` Field to the Project Table

Open your `db/project.ts` file and add the new field:

```typescript
import { db } from "@tailor-platform/sdk";

export const project = db.table("Project", {
  name: db.string().description("Project name"),
  description: db.string().optional().description("Project description"),
  status: db
    .enum(["planning", "active", "completed", "archived"])
    .description("Current project status"),
  startDate: db.string().optional().description("Project start date"),
  endDate: db.string().optional().description("Project end date"),
  budget: db.float().optional().description("Project budget"),
  priority: db.enum(["low", "medium", "high", "critical"]).description("Project priority level"),
  teamSize: db.int().optional().description("Number of team members"),
  ...db.fields.timestamps(),
});
export type project = typeof project;
```

The new `teamSize` field:

* Has type `int()` for integer values
* Is optional (can be null)
* Includes a description for documentation

Fields like `id` are automatically generated without being explicitly defined. These are pre-defined fields. See [Auto-generated Fields](../../sdk/services/tailordb#auto-generated-fields) for more information.

### 2. Deploy the Change

Deploy the updated schema to your workspace:

```bash
npm run deploy -- --workspace-id <your-workspace-id>
```

The SDK will:

* Detect the schema changes
* Update the TailorDB table
* Regenerate the GraphQL API with the new field

### 3. Verify Schema Change Through GraphQL

Open the GraphQL Playground in the [Console](https://console.tailor.tech) and select your workspace.

Create a Project with the new `teamSize` field:

```graphql
mutation {
  createProject(
    input: {
      name: "Website Redesign"
      description: "Complete redesign of company website"
      status: "active"
      priority: "high"
      teamSize: 5
      createdAt: "2026-02-09T10:00:00Z"
      updatedAt: "2026-02-09T10:00:00Z"
    }
  ) {
    id
    name
    teamSize
  }
}
```

Example response:

```json
{
  "data": {
    "createProject": {
      "id": "c3e9313b-ef80-45da-a5b2-f6d77810dd92",
      "name": "Website Redesign",
      "teamSize": 5
    }
  }
}
```

Query the project to verify the `teamSize` field:

```graphql
query {
  project(id: "c3e9313b-ef80-45da-a5b2-f6d77810dd92") {
    name
    teamSize
    status
    priority
  }
}
```

Example response:

```json
{
  "data": {
    "project": {
      "name": "Website Redesign",
      "teamSize": 5,
      "status": "active",
      "priority": "high"
    }
  }
}
```

## Next Steps

Now that you've learned how to add a field, you can proceed to:

* [Creating Data Schema](create-data-schema) - Learn how to create new tables
* [Field Types](../../sdk/services/tailordb#field-types) - Explore all available field types
* [Field Validation](../../sdk/services/tailordb#validation) - Add validation rules to fields

## Further Information

* [TailorDB Service](../../sdk/services/tailordb) - Complete TailorDB documentation
* [Schema Design Best Practices](../../sdk/services/tailordb#best-practices) - Tips for designing effective schemas

---

---
url: https://docs.tailor.tech/tutorials/manage-data-schema/validate-field-data.md
---
# Validate Field Data

Accurate and valid data is essential to ensure the success of any application. Tailor Platform provides an easy way to validate data with TailorDB. You can define validation rules within your data model to ensure your data is accurate and valid.

This tutorial demonstrates how to apply data validation rules to your fields using the SDK.

* See [Core Concepts](/getting-started/core-concepts/) to get an overview of Workspace, Organization, Application and Service.
* To follow along with this tutorial, first complete the [SDK Quickstart](../../sdk/quickstart) and the [Data Schema Basics](data-schema-basics) tutorial.

## Tutorial Steps

Follow these steps to add a validation rule to the `name` field of a Project:

1. Define a validation rule
2. Deploy the change
3. Confirm the applied validation rule

### 1. Define a Validation Rule

Open your `db/project.ts` file and add a validation rule to the `name` field. We'll ensure project names are between 3 and 50 characters:

```typescript
import { db } from "@tailor-platform/sdk";

export const project = db.table("Project", {
  name: db
    .string()
    .description("Project name")
    .validate(
      ({ value }) => (value.length >= 3 ? undefined : "Project name must be at least 3 characters"),
      ({ value }) =>
        value.length <= 50 ? undefined : "Project name must be 50 characters or less",
    ),
  description: db.string().optional().description("Project description"),
  status: db
    .enum(["planning", "active", "completed", "archived"])
    .description("Current project status"),
  startDate: db.string().optional().description("Project start date"),
  endDate: db.string().optional().description("Project end date"),
  completionPercentage: db
    .int()
    .optional()
    .validate(({ value }) =>
      value === undefined || (value >= 0 && value <= 100)
        ? undefined
        : "Completion percentage must be between 0 and 100",
    )
    .description("Project completion percentage"),
  priority: db.enum(["low", "medium", "high", "critical"]).description("Project priority level"),
  teamSize: db
    .int()
    .optional()
    .validate(({ value }) =>
      value === undefined || (value > 0 && value <= 100)
        ? undefined
        : "Team size must be between 1 and 100",
    )
    .description("Number of team members"),
  ...db.fields.timestamps(),
});
export type project = typeof project;
```

**Validation Rules Explained:**

* **name**: Must be at least 3 characters and no more than 50 characters
* **completionPercentage**: Must be between 0 and 100 (if provided)
* **teamSize**: Must be between 1 and 100 (if provided)

The `validate()` method accepts:

* One or more validation functions, each receiving `{ value }` (the field value after hooks)
* Each function returns an error message string to fail, or `void`/`undefined` to pass
* Multiple validations can be chained by passing multiple functions

For more information, see [Input Validation](../../sdk/services/resolver#input-validation) documentation.

### 2. Deploy the Change

Deploy the updated schema with validation rules:

```bash
npm run deploy -- --workspace-id <your-workspace-id>
```

The SDK will deploy the schema with the validation rules applied.

### 3. Confirm the Applied Validation Rule

Open the GraphQL Playground in the [Console](https://console.tailor.tech) and select your workspace.

**Test 1: Invalid Project Name (Too Short)**

Try to create a project with a name that's too short:

```graphql
mutation {
  createProject(
    input: {
      name: "AB"
      status: "active"
      priority: "high"
      createdAt: "2026-02-09T10:00:00Z"
      updatedAt: "2026-02-09T10:00:00Z"
    }
  ) {
    id
  }
}
```

Error response:

```json
{
  "errors": [
    {
      "message": "name: Validation failed",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": ["createProject"]
    }
  ],
  "data": {
    "createProject": null
  }
}
```

**Test 2: Invalid Project Name (Too Long)**

Try to create a project with a name that exceeds the maximum length:

```graphql
mutation {
  createProject(
    input: {
      name: "This is an extremely long project name that exceeds the fifty character limit"
      status: "active"
      priority: "high"
      createdAt: "2026-02-09T10:00:00Z"
      updatedAt: "2026-02-09T10:00:00Z"
    }
  ) {
    id
  }
}
```

Error response:

```json
{
  "errors": [
    {
      "message": "name: Project name must be 50 characters or less",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": ["createProject"]
    }
  ],
  "data": {
    "createProject": null
  }
}
```

**Test 3: Invalid Completion Percentage**

Try to create a project with an invalid completion percentage:

```graphql
mutation {
  createProject(
    input: {
      name: "Website Redesign"
      status: "active"
      priority: "high"
      completionPercentage: 150
      createdAt: "2026-02-09T10:00:00Z"
      updatedAt: "2026-02-09T10:00:00Z"
    }
  ) {
    id
  }
}
```

Error response:

```json
{
  "errors": [
    {
      "message": "completionPercentage: Completion percentage must be between 0 and 100",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": ["createProject"]
    }
  ],
  "data": {
    "createProject": null
  }
}
```

**Test 4: Invalid Team Size**

Try to create a project with an invalid team size:

```graphql
mutation {
  createProject(
    input: {
      name: "Website Redesign"
      status: "active"
      priority: "high"
      teamSize: 150
      createdAt: "2026-02-09T10:00:00Z"
      updatedAt: "2026-02-09T10:00:00Z"
    }
  ) {
    id
  }
}
```

Error response:

```json
{
  "errors": [
    {
      "message": "teamSize: Team size must be between 1 and 100",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": ["createProject"]
    }
  ],
  "data": {
    "createProject": null
  }
}
```

**Test 5: Valid Project**

Create a project with valid data:

```graphql
mutation {
  createProject(
    input: {
      name: "Website Redesign"
      description: "Complete redesign of company website"
      status: "active"
      priority: "high"
      completionPercentage: 25
      teamSize: 8
      createdAt: "2026-02-09T10:00:00Z"
      updatedAt: "2026-02-09T10:00:00Z"
    }
  ) {
    id
    name
    teamSize
    completionPercentage
  }
}
```

Successful response:

```json
{
  "data": {
    "createProject": {
      "id": "e10f0541-3521-469c-a269-951b6ba06cc3",
      "name": "Website Redesign",
      "teamSize": 8,
      "completionPercentage": 25
    }
  }
}
```

## Next Steps

Learn more about validation and schema design:

* [Field Validation](../../sdk/services/tailordb#validation) - Complete validation reference
* [Field Types](../../sdk/services/tailordb#field-types) - All available field types
* [Creating Data Schema](create-data-schema) - Learn how to create new tables
* [Best Practices](../../sdk/services/tailordb#best-practices) - Schema design guidelines

---

---
url: https://docs.tailor.tech/tutorials/setup-auth/overview.md
---
# Setting up Auth

In this tutorial, you'll learn key concepts and techniques that are fundamental to using Auth service.

The [Auth service](/guides/auth/overview) authorizes application users and manages their access to resources.
It provides a set of APIs to authenticate users and control their access to various resources.

For a comprehensive overview of Auth service capabilities and supported Identity Providers, see the [Auth service guide](/guides/auth/overview). To learn about querying user information when Auth is used as a subgraph, see [Auth as a Subgraph](/guides/auth/overview#authasasubgraph).

## Prerequisite

* Complete [Quickstart](/getting-started/quickstart)&#x20;

There are various approaches to obtaining an access token depending on the type of protocol being used.

In this section, you will explore two approaches for obtaining access tokens.

The first approach focuses on logging in using an OAuth2 client, leveraging OIDC or SAML protocols to obtain an access token.

The second approach is to request an ID token from your identity provider, then use it to get an access token from your app's OAuth2 API.

## What you'll learn

* [Set up the IdP](setup-identity-provider)
* [Register the IdP with Tailor PF Auth service](register-identity-provider)
* [Create users](login/create-user)
* [Create an OAuth2 client](login/create-oauth2-client)
* [Log in using ID token](login/id-token)
* [Set up Auth Connections](setup-auth-connections)

---

---
url: https://docs.tailor.tech/tutorials/setup-auth/setup-identity-provider.md
---
# Set up your Identity Provider

The [Auth service](/guides/auth/overview) works with an identity provider (IdP) to authenticate users.

## Prerequisite

* Complete [Quickstart](/getting-started/quickstart)&#x20;
* See [Core concepts](/getting-started/core-concepts/) to get an overview of Workspace, Organization, Application and Service.

Before configuring the Auth service for authentication, you need to set up an identity provider.

The Tailor Platform supports several Identity Providers. For detailed setup guides specific to each provider, see:

* [Okta Integration Guide](/guides/auth/integration/okta) - Enterprise-grade identity management
* [Auth0 Integration Guide](/guides/auth/integration/auth0) - Flexible identity platform
* [Google Workspace Integration Guide](/guides/auth/integration/google-workspace) - Google's productivity platform (coming soon)

In this tutorial, we'll use Auth0 as an example of an identity provider.
If you don't have an Auth0 account, sign up for a free account at [Auth0](https://auth0.com/).

After creating the account, configure Auth0 with your preferred authentication protocol, as outlined below, to register your IdP with the Auth service.

1. Setting up IdP for OIDC
2. Setting up IdP for SAML
3. Setting up IdP for ID Token

## 1. Setting up IdP for OIDC

In the Auth0 Dashboard, locate your application's domain, client ID, and client secret in the Application settings.

![Tutorials – Set up identity provider](../assets/auth0-application-settings.png)

Add `http://tailorctl.tailor.tech:8086/callback` to `Allowed Callback URLs` in the `Application URIs` section of the settings.

![Tutorials – Set up identity provider](../assets/auth0-callback-url.png)

## 2. Setting up IdP for SAML

In the Auth0 Dashboard, navigate to `Applications` and select your application. Select `Addons` tab to enable `SAML2 WEB APP`.

![Tutorials – Set up identity provider SAML](../assets/auth0-saml-addon.png)

After enabling the SAML2 WEB APP in Auth0:

1. Click the addon and open the Settings tab.

2. Set the `Application Callback URL`:

`https://api.tailor.tech/saml/acs`

Enter the following setting in the `Settings` section. Here, we are using an email address as a user identifier.
You can update the settings to use a different identifier. The `audience` field corresponds to the EntityID expected by the Tailor Platform in SAML assertions.

Scroll to the bottom of the tab and save the settings.

```json
{
  "audience": "https://api.tailor.tech/saml/{workspace_id}/{auth_namespace}/metadata.xml", // EntityID for Tailor Platform
  "nameIdentifierFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
  "nameIdentifierProbes": ["http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"]
}
```

![Tutorials – Set up identity provider](../assets/auth0-saml-settings.png)

### SAML Endpoints for Tailor Platform

The EntityID uniquely identifies the Tailor Platform as a Service Provider (SP) in the SAML authentication flow. When configuring your Identity Provider, you need to specify the EntityID that corresponds to your Tailor Platform application.

Your Identity Provider (IdP) sends SAML assertions to the ACS URL after successful authentication. This URL must be configured in your IdP to match the callback URL expected by Tailor Platform.

Configure the following values in the Auth0 SAML addon settings:

| Parameter         | Value                                                                       |
| ----------------- | --------------------------------------------------------------------------- |
| **EntityID**      | `https://api.tailor.tech/saml/{workspace_id}/{auth_namespace}/metadata.xml` |
| **ACS URL**       | `https://api.tailor.tech/saml/acs`                                          |
| **NameID Format** | `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`                    |
| **Binding**       | HTTP-POST                                                                   |

The ACS URL must match exactly what you configure in your Tailor Platform Auth service. Any mismatch will result in authentication failures.

## 3. Setting up IdP for ID Token

In the Auth0 Dashboard, locate your application's domain, client ID and client secret in the Application settings.

![Tutorials – Set up identity provider ID token](../assets/auth0-application-settings.png)

Add `http://tailorctl.tailor.tech:8086/callback` to `Allowed Callback URLs` in the `Application URIs` section of the settings.

![Tutorials – Set up identity provider ID token](../assets/auth0-callback-url.png)

### (Optional) Below are the steps to enable `Password Grant` exchanges.

These steps are optional. They are configured to allow easy acquisition of ID Tokens using the Password grant type.

1. Configure tenant

In the Auth0 dashboard, select `Settings` from the navigation and locate `API Authorization Settings` in the `General` tab.
Scroll down to locate the `Default Directory` setting and enter `Username-Password-Authentication`.

![Tutorials – Set up identity provider ID token](../assets/auth0-id-token-tenant-settings.png)

2. Update `Grant Types`

Select your application from the `Applications` section, then navigate to the `Settings` tab, and scroll down to find `Advanced Settings`.

In the `Advanced Settings`, navigate to the `Grant Types` tab and check the box next to `Password` to enable the `Password` grant type.

![Tutorials – Set up identity provider ID token](../assets/auth0-id-token-grant-type-settings.png)

Next, copy your API Identifier by selecting `APIs` under `Applications` from the navigation menu.

![Tutorials – Set up identity provider ID token](../assets/auth0-id-token-api-identifier.png)

## Next steps

After configuring the IdP with your preferred authentication protocol, you are ready to register it with the Auth service.

---

---
url: https://docs.tailor.tech/tutorials/setup-auth/register-identity-provider.md
---
# Register Identity provider with Auth service

To enable authentication through an identity provider, you need to register it with the Auth service. In this tutorial, you'll learn how to register IdPs for different authentication protocols using the Tailor Platform SDK.

## Prerequisites

* Complete the [SDK Quickstart](../../sdk/quickstart)
* [Set up the IdP](setup-identity-provider)
* Have your IdP credentials ready (client ID, client secret, provider URL, etc.)

## Tutorial Steps

1. Register IdP with the Auth service for each protocol (OIDC, SAML, ID Token)
2. Deploy the changes

## 1. Register IdP with the Auth Service

### OIDC (OpenID Connect)

First, ensure you have a User type defined in your database schema (e.g., `db/user.ts`):

```typescript
import { db } from "@tailor-platform/sdk";

export const user = db.table("User", {
  email: db.string().unique(), // usernameField must be unique
  name: db.string(),
  roles: db.array(db.string()).optional(),
  ...db.fields.timestamps(),
});
```

Then update your `tailor.config.ts` to include the Auth service with OIDC configuration:

```typescript
import { defineAuth, defineConfig } from "@tailor-platform/sdk";
import { user } from "./db/user";

const auth = defineAuth("project-management-auth", {
  userProfile: {
    type: user,
    usernameField: "email",
    attributes: {
      roles: true,
    },
  },
  idProvider: {
    name: "oidc-provider",
    oidc: {
      clientId: process.env.OIDC_CLIENT_ID!,
      clientSecret: {
        vaultName: "my-vault",
        secretName: "oidc-client-secret",
      },
      providerUrl: process.env.OIDC_PROVIDER_URL!,
    },
  },
});

export default defineConfig({
  name: "project-management",
  db: {
    "main-db": {
      files: ["db/**/*.ts"],
    },
  },
  auth,
});
```

**Environment Variables:**

Create a `.env` file in your project root:

```bash
OIDC_CLIENT_ID=your_auth0_client_id
OIDC_PROVIDER_URL=https://your-domain.us.auth0.com
```

**Store the Client Secret:**

Before deploying, you need to store your client secret in the secret manager. Run these commands:

```bash
# Create a vault
tailor secret vault create my-vault

# Store the client secret
tailor secret create \
  --vault-name my-vault \
  --name oidc-client-secret \
  --value YOUR_CLIENT_SECRET
```

**Vault naming rules:** Only lowercase letters (a-z), numbers (0-9), and hyphens (-). Must start and end with a letter or number, 2-62 characters long.

### SAML

The Tailor Platform provides a built-in key for signing SAML authentication requests. When request signing is enabled, the platform automatically signs requests sent from the SP to the IdP. The SP metadata, including the public key for signature verification, is available at `https://api.tailor.tech/saml/{workspace_id}/{auth_namespace}/metadata.xml`.

Update your `tailor.config.ts` to include SAML configuration:

```typescript
import { defineAuth, defineConfig } from "@tailor-platform/sdk";
import { user } from "./db/user";

const auth = defineAuth("project-management-auth", {
  userProfile: {
    type: user,
    usernameField: "email",
    attributes: {
      roles: true,
    },
  },
  idProvider: {
    name: "saml-provider",
    saml: {
      metadataUrl: process.env.SAML_METADATA_URL!,
      // Alternative: use rawMetadata for inline XML
      // rawMetadata: `<?xml version="1.0"?>...`,
      enableSignRequest: false, // Set to true to enable request signing
      defaultRedirectURL: "https://your-app.example.com/login",
    },
  },
});

export default defineConfig({
  name: "project-management",
  db: {
    "main-db": {
      files: ["db/**/*.ts"],
    },
  },
  auth,
});
```

**Configuration Properties:**

| Property               | Description                                                                                                                                            |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **metadataUrl**        | Metadata URL of the identity provider **(required if rawMetadata is not provided)**.                                                                   |
| **rawMetadata**        | Raw SAML metadata XML string **(required if metadataUrl is not provided)**.                                                                            |
| **enableSignRequest**  | Whether to enable signing of SAML authentication requests (optional, defaults to `false`). When enabled, the platform uses a built-in key for signing. |
| **defaultRedirectURL** | URL the platform redirects to when a SAML assertion arrives without a `RelayState`.                                                                    |

**Environment Variables:**

Add to your `.env` file:

```bash
SAML_METADATA_URL=https://your-idp.com/saml/metadata
```

The metadata URL is provided by your Identity Provider (IdP). You can typically find this in your IdP's SAML application settings.

### ID Token

For ID Token-based authentication, update your `tailor.config.ts`:

```typescript
import { defineAuth, defineConfig } from "@tailor-platform/sdk";
import { user } from "./db/user";

const auth = defineAuth("project-management-auth", {
  userProfile: {
    type: user,
    usernameField: "email",
    attributes: {
      roles: true,
    },
  },
  idProvider: {
    name: "idtoken-provider",
    idToken: {
      clientId: process.env.ID_TOKEN_CLIENT_ID!,
      providerUrl: process.env.ID_TOKEN_PROVIDER_URL!,
    },
  },
});

export default defineConfig({
  name: "project-management",
  db: {
    "main-db": {
      files: ["db/**/*.ts"],
    },
  },
  auth,
});
```

**Environment Variables:**

Add to your `.env` file:

```bash
ID_TOKEN_CLIENT_ID=your_auth0_client_id
ID_TOKEN_PROVIDER_URL=https://your-domain.us.auth0.com
```

Replace with your Auth0 client ID and domain.

## 2. Deploy the Changes

Deploy your application with the Auth configuration:

```bash
npm run deploy -- --workspace-id <your-workspace-id>
```

The SDK will deploy the Auth service with your IdP configuration.

**Verification:**

1. Open the [Console](https://console.tailor.tech) and navigate to your workspace
2. Go to the Auth section to verify your IdP configuration
3. Test the authentication flow with your IdP

**Multiple IdP Configurations:**

You can register multiple identity providers in the same application:

```typescript
export default defineConfig({
  name: "project-management",
  auth: {
    namespace: "project-management-auth",
    idpConfigs: [
      {
        name: "oidc-provider",
        oidc: {/* ... */},
      },
      {
        name: "saml-provider",
        saml: {/* ... */},
      },
      {
        name: "idtoken-provider",
        idToken: {/* ... */},
      },
    ],
    userProfileConfig: {
      tailordb: {
        namespace: "main-db",
        type: "User",
        usernameField: "email",
        attributeFields: ["roles"],
      },
    },
  },
});
```

You can now use your Auth service to manage access to resources.

## Next Steps

* [Create user](login/create-user) - Learn how to create users in your application
* [Create an OAuth2 client](login/create-oauth2-client) - Securely authenticate and authorize access to your data
* [Auth Service Documentation](../../sdk/services/auth) - Complete Auth service reference

---

---
url: https://docs.tailor.tech/tutorials/setup-auth/setup-auth-connections.md
---
# Setting up Auth Connections

Auth connections enable your application to authenticate with external OAuth2 providers (such as Google, Microsoft 365, or QuickBooks) on behalf of itself, not on behalf of a user. Functions, executors, and workflows can then access those provider APIs at runtime using a managed access token.

* To follow along, first complete the [SDK Quickstart](../../sdk/quickstart) and [Setting up Auth](overview).

This tutorial manages the connection through SDK config (`defineAuth()`), which is one of two supported approaches. You can instead create, authorize, and manage a connection entirely from the Console with `tailor authconnection open` — see [Setup Flow](/guides/auth/authconnection#setup-flow) in the AuthConnection guide for both options and why a given connection should only be managed by one of them.

## What you'll build

A connection to Google's API that your resolvers and functions can use to call Google services without managing OAuth2 tokens manually.

## Tutorial Steps

1. Configure the connection in `defineAuth()`
2. Deploy the connection
3. Authorize the connection
4. Use the connection token at runtime
5. Manage connections via CLI

### 1. Configure the Connection

Add a `connections` block to your `defineAuth()` in `tailor.config.ts`:

```typescript
import { defineAuth } from "@tailor-platform/sdk";
import { idp } from "./idp";

export const auth = defineAuth("my-auth", {
  userProfile: {
    type: user,
    usernameField: "email",
  },
  idProvider: idp.provider("my-provider", "my-client"),
  connections: {
    "google-connection": {
      type: "oauth2",
      providerUrl: "https://accounts.google.com",
      issuerUrl: "https://accounts.google.com",
      clientId: process.env.GOOGLE_CLIENT_ID!,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
    },
  },
});
```

**Connection config fields:**

| Field          | Required | Description                                 |
| -------------- | -------- | ------------------------------------------- |
| `type`         | Yes      | Connection type. Currently only `"oauth2"`. |
| `providerUrl`  | Yes      | OAuth2 provider base URL.                   |
| `issuerUrl`    | Yes      | OAuth2 issuer URL for JWT validation.       |
| `clientId`     | Yes      | Your OAuth2 app's client ID.                |
| `clientSecret` | Yes      | Your OAuth2 app's client secret.            |
| `authUrl`      | No       | Override the authorization endpoint.        |
| `tokenUrl`     | No       | Override the token endpoint.                |

Store `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` in your `.env` file or CI secrets. Never commit them.

### 2. Deploy the Connection

Run `tailor deploy` to register the connection with the platform:

```bash
tailor deploy
```

This creates the connection record. The connection exists but is not yet authorized (it has no tokens yet).

::: info In-place updates
Redeploying updates an existing connection **in-place**, preserving the OAuth token. If a change requires re-authorization (for example, the provider URL or client ID changed), `deploy` will warn you to run `authconnection authorize` again.
:::

### 3. Authorize the Connection

Run the authorize command to complete the OAuth2 flow:

```bash
tailor authconnection authorize --name google-connection \
  --scopes "openid,profile,email"
```

This opens a browser tab for the OAuth2 consent screen. After you approve, the platform exchanges the authorization code for tokens and stores them securely. Your app code never handles the tokens directly.

You can also run `tailor authconnection open` to authorize from the Console instead of the local CLI flow:

```bash
tailor authconnection open
```

Verify the connection is authorized:

```bash
tailor authconnection list
```

### 4. Use the Connection Token at Runtime

Use `authconnection.getConnectionToken()` from `@tailor-platform/sdk/runtime` in a resolver, executor, or workflow to retrieve the current access token:

```typescript
// resolvers/fetch-google-profile.ts
import { createResolver, t } from "@tailor-platform/sdk";
import { authconnection } from "@tailor-platform/sdk/runtime";

export default createResolver({
  name: "fetchGoogleProfile",
  operation: "query",
  input: {},
  output: t.object({
    email: t.string(),
    name: t.string(),
  }),
  body: async () => {
    const tokens = await authconnection.getConnectionToken("google-connection");

    const response = await fetch("https://www.googleapis.com/oauth2/v2/userinfo", {
      headers: {
        Authorization: `Bearer ${tokens.access_token}`,
      },
    });

    const profile = await response.json();
    return { email: profile.email, name: profile.name };
  },
});
```

The connection name is **type-checked** against the connections defined in `defineAuth()`. If you rename or remove a connection, TypeScript will flag any call sites immediately.

```typescript
// authconnection.getConnectionToken("unknown-connection"); // ❌ TypeScript error
```

Type narrowing comes from the generated `tailor.d.ts`. Run `tailor generate` (or `deploy`) after adding or renaming connections to refresh it.

### 5. Manage Connections via CLI

```bash
# List all connections and their status
tailor authconnection list

# Re-authorize a connection (e.g. token expired or scopes changed)
tailor authconnection authorize --name google-connection \
  --scopes "openid,profile,email,https://www.googleapis.com/auth/calendar"

# Revoke a connection
tailor authconnection revoke --name google-connection
```

## Complete Example: Calling an External API from an Executor

Here's a full executor that calls the Google Calendar API whenever a meeting record is created:

```typescript
// executor/sync-to-google-calendar.ts
import { createExecutor, recordCreatedTrigger } from "@tailor-platform/sdk";
import { authconnection } from "@tailor-platform/sdk/runtime";
import { meeting } from "../db/meeting";

export default createExecutor({
  name: "sync-to-google-calendar",
  description: "Create a Google Calendar event when a meeting is scheduled",
  trigger: recordCreatedTrigger({ type: meeting }),
  operation: {
    kind: "function",
    body: async ({ newRecord }) => {
      const tokens = await authconnection.getConnectionToken("google-connection");

      await fetch("https://www.googleapis.com/calendar/v3/calendars/primary/events", {
        method: "POST",
        headers: {
          Authorization: `Bearer ${tokens.access_token}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          summary: newRecord.title,
          start: { dateTime: newRecord.startTime },
          end: { dateTime: newRecord.endTime },
        }),
      });
    },
  },
});
```

## Next Steps

* [Auth Service](../../sdk/services/auth#auth-connections) - Full auth connections API reference
* [Built-in Interfaces](/guides/function/builtin-interfaces#auth-connection) - Runtime token API
* [Auth Guide](/guides/auth/authconnection) - Platform-level auth connection docs
* [Setting up Auth](overview) - Back to auth tutorial overview

---

---
url: https://docs.tailor.tech/tutorials/setup-auth/login/create-oauth2-client.md
---
# Using OAuth2 to log in to the Tailor PF app

In this tutorial, you'll learn how to set up secure user access to your Tailor PF app using OAuth2 authentication with the Tailor Platform SDK.

## Prerequisites

* Complete the [SDK Quickstart](../../../sdk/quickstart)
* [Set up the IdP](../setup-identity-provider)
* [Register your IdP](../register-identity-provider)

## Tutorial Steps

1. Configure OAuth2 client in the Auth configuration
2. Deploy and log in to the app
3. Connect with Next.js UI (optional)

## 1. Configure OAuth2 Client in the Auth Configuration

Update your `tailor.config.ts` to include OAuth2 client configuration:

```typescript
import { defineConfig } from "@tailor-platform/sdk";

export default defineConfig({
  name: "project-management",
  db: {
    "main-db": {
      files: ["db/**/*.ts"],
    },
  },
  auth: {
    namespace: "project-management-auth",
    idpConfigs: [
      {
        name: "oidc-provider",
        oidc: {
          clientId: process.env.OIDC_CLIENT_ID!,
          clientSecret: {
            vaultName: "my-vault",
            secretName: "oidc-client-secret",
          },
          providerUrl: process.env.OIDC_PROVIDER_URL!,
        },
      },
    ],
    userProfileConfig: {
      tailordb: {
        namespace: "main-db",
        type: "User",
        usernameField: "email",
        attributeFields: ["roles"],
      },
    },
    oauth2Clients: [
      {
        name: "spa-client",
        description: "OAuth2 browser client for SPA",
        clientType: "browser",
        redirectUris: [
          "http://localhost:3000/__oauth/callback",
          "http://tailorctl.tailor.tech:8086/callback",
        ],
        grantTypes: ["authorization_code", "refresh_token"],
      },
    ],
  },
});
```

**OAuth2 Client Properties:**

| **Property**   | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`         | The name of the OAuth2 client. Use descriptive names like `"spa-client"` or `"server-client"`.                                                                                                                                                                                                                                                                                                                                                        |
| `clientType`   | Specifies the OAuth2 client type: - `"confidential"` for server-side applications that can securely store credentials - `"public"` for mobile applications that cannot securely store secrets - `"browser"` for Single Page Applications (SPAs) with enhanced security features. For guidance on choosing the right client type for SPA applications, see [OAuth2 Client Selection for SPAs](/guides/auth/spa-oauth2-client). |
| `grantTypes`   | An array specifying supported OAuth2 grant types: - `authorization_code`: for standard OAuth2 flows - `refresh_token`: to refresh access tokens.                                                                                                                                                                                                                                                                                          |
| `redirectUris` | A list of redirect URIs where the authorization server will send users after authentication. Includes: - `http://localhost:3000/__oauth/callback`: the default route in the Next.js app handling OAuth2 callbacks - `http://tailorctl.tailor.tech:8086/callback`: enables login via `tailorctl`.                                                                                                                                          |

**Multiple OAuth2 Clients:**

You can configure multiple OAuth2 clients for different use cases:

```typescript
oauth2Clients: [
  {
    name: "spa-client",
    description: "OAuth2 browser client for SPA",
    clientType: "browser",
    redirectUris: ["http://localhost:3000/__oauth/callback"],
    grantTypes: ["authorization_code", "refresh_token"],
  },
  {
    name: "server-client",
    description: "OAuth2 confidential client for server-side",
    clientType: "confidential",
    redirectUris: ["https://api.example.com/callback"],
    grantTypes: ["authorization_code", "refresh_token", "client_credentials"],
  },
  {
    name: "mobile-client",
    description: "OAuth2 public client for mobile apps",
    clientType: "public",
    redirectUris: ["myapp://callback"],
    grantTypes: ["authorization_code", "refresh_token"],
  },
],
```

## 2. Deploy and Log In to Your Tailor PF App

### Deploy the Configuration

Deploy your application with the OAuth2 client configuration:

```bash
npm run deploy -- --workspace-id <your-workspace-id>
```

### Log In Using SDK CLI

Run the following command to access your application:

```bash
tailor login --oauth2-client spa-client
```

You will be redirected to your IdP (e.g., Auth0) to authenticate. Log in with your credentials.

After successfully logging in, you will receive the access token.

### Use the Token in GraphQL Playground

To include the token in GraphQL Playground, navigate to the `Headers` tab and add the token to the `Authorization` header:

```json
{
  "Authorization": "Bearer {ACCESS_TOKEN}"
}
```

## 3. Connecting Tailor PF App and Next.js UI (Optional)

In this section, you'll learn how to integrate OAuth 2.0 authentication into a sample Next.js application to enable secure login to the Tailor PF app.

### 1. Get Client credentials

Run the following command to get the client\_id and client\_secret.

```bash
tailor oauth2client list
```

You will get the following response with the client credentials which is used in the Next.js app for OAuth2 client configuration.

```bash
+---------------+---------------------------------------------+
| NAME          | spa-client                                  |
| DESCRIPTION   | OAuth2 browser client for SPA               |
| GRANT_TYPES   | authorization_code,refresh_token            |
| REDIRECT_URIS | http://localhost:3000/__oauth/callback      |
| CLIENT_ID     | <client_id>                                 |
+---------------+---------------------------------------------+
```

### 2. Add the callback URL in the application settings

Add `https://{TAILOR_PF_APP_URL}/oauth2/callback` to `Allowed Callback URLs` in the `Application URIs` section of the Application settings.

![Tutorials – Set up OAuth2 Client](../../assets/tutorial-auth-auth0-tailol-pf-oauth-callback-url.png)

### 3. Next.js app configuration

You can clone the `tailor-nextjs-starter` Next.js app found [here](https://github.com/tailor-platform/tailor-nextjs-starter/tree/auth_example) to explore the configuration of an OAuth 2.0 client using the library [badgateway/oatuh2-client](https://github.com/badgateway/oauth2-client).

For managing OAuth 2.0 clients, it is recommended to use available libraries. As an example, `@badgateway/oauth2-client` is used here, but other libraries can also be utilized.

After cloning the repository, create a `.env.local` file in your project root directory and add the following environment variables:

```bash
OAUTH_SERVER_URL=http://{TAILOR_PF_APP_URL}/
OAUTH_CLIENT_ID={CLIENT_ID}
OAUTH_CLIENT_SECRET={CLIENT_SECRET}
NEXT_PUBLIC_BASE_URL=http://localhost:3000
```

Navigate to the application directory and run the following command to install the necessary dependencies.

```bash
npm i
```

Run the following command to start the application.

```bash
npm run dev
```

When you visit http://localhost:3000/ in your browser you should now see the below screen:

![Tutorials – Set up OAuth2 Client](../../assets/tutorial-auth-sample-ui-login.png)

Clicking on the `Login with OAuth` button will redirect to Auth0 for authentication. Log in with your credentials.

To handle the redirectUri, it is recommended to use Next.js middleware rather than directly specifying a redirection destination. This approach ensures that the ID token from the IdP can be processed securely without exposure.

In this example, the Next.js middleware is configured to handle redirects at `/__oauth/callback`. You can specify the final redirect destination here.

---

---
url: https://docs.tailor.tech/tutorials/setup-auth/login/create-user.md
---
# Create Users in Your Application

In the authentication process, the user authenticates through the Identity Provider (IdP), which verifies their identity.
Once successfully authenticated, TailorPF queries its database to check if the user’s account already exists.

If the user’s account exists, TailorPF issues an access token, granting the user the appropriate level of access to the requested application based on their roles and permissions.

Here is a diagram that explains the flow of the authentication process.
From the client's perspective, the authorization flow is as shown below and uses TailorPF as the authorization server with the Authorization Code Grant.

```mermaid
sequenceDiagram
  participant User
  participant Client
  participant PF AS TailorPF+IdP

  User->>+Client: Access protected resource
  Client-->>-User: Redirect to TailorPF's authorization endpoint
  User->>+PF: Authorization request to TailorPF
  rect rgba(0, 255, 255, .1)
    PF->>-User: Returns authentication screen
    User->>+PF: Submits authentication information
  end
  PF-->>-User: Redirect to Client's redirect URL
  User->>+Client: Authorization response from TailorPF
  Client->>+PF: Access token request to TailorPF
  PF->>-Client: Access token
  Client->>-User: Grant access to protected resource
```

## Steps to Create Users

### 1. Create a user in Auth0

Log in to your Auth0 account. In the `Dashboard`, navigate to `User management` and then select `Users`.
Click `Create User` to create a new user.

![Tutorials – Set up identity provider](../../assets/auth0-create-user.png)

### 2. Use a GraphQL query to create a user in the TailorDB

Get an access token to use it in the GraphQL playground to run queries.

Run the following command to get an access token:

```bash
tailor machineuser token admin-machine-user
```

Set the token in the Headers section of the playground as follows:

```json
{
  "Authorization": "bearer {ACCESS_TOKEN}"
}
```

Query the roles to assign a role to the user.

```graphql {{title:'query'}}
query {
  roles {
    edges {
      node {
        id
        name
      }
    }
  }
}
```

You can assign the user a role using its ID.

```graphql {{title:'response'}}
{
  "data": {
    "roles": {
      "edges": [
        {
          "node": {
          	"id": "422e0d2d-fb14-458b-bbb2-db307fc1a174",
            "name": "Admin"
          }
        },
        {
          "node": {
            "id": "f1292168-f6de-405a-9f5a-c674a239da93",
            "name": "Editor"
          }
        }
      ]
    }
  }
}
```

Create a user with the email address used in step 1 and assign the 'Editor' role.

```graphql {{title:'query'}}
mutation {
  createUser(
    input: {
      name: "<username>"
      email: "<user-email>"
      roles: ["f1292168-f6de-405a-9f5a-c674a239da93"]
    }
  ) {
    id
  }
}
```

The user is created and can now access the application.

## Next steps

* [Create an OAuth2 client](create-oauth2-client) to securely log in to the application.
* Log in manually using [ID tokens](id-token).

---

---
url: https://docs.tailor.tech/tutorials/setup-auth/login/id-token.md
---
# Using ID Token

The ID Token Auth flow ([JWT Bearer Grant Type](https://datatracker.ietf.org/doc/html/rfc7523))enables OAuth 2.0 clients to obtain access tokens by presenting a signed JWT to the authorization server.\
This method is particularly useful for server-to-server communication, where user interaction is not feasible.

## Prerequisite

* Set up and register your IdP for ID tokens using the tutorials in [Setting up IdP for ID Token](/tutorials/setup-auth/setup-identity-provider) and [Register your IdP](/tutorials/setup-auth/register-identity-provider).

## 1. Get your ID token

Send the following request by replacing yourAuth0Domain, username, password, yourApiIdentifier, yourClientId and yourClientSecret to get the id\_token.
Refer to [Setting up IdP for ID token](/tutorials/setup-auth/setup-identity-provider#3settingupidpforidtoken) to get your API identifier.

```
curl --request POST \
  --url 'https://{AUTH0_DOMAIN}.us.auth0.com}/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=password \
  --data 'username={USERNAME}' \
  --data 'password={PASSWORD}' \
  --data 'audience={API_IDENTIFIER}' \
  --data scope=openid \
  --data 'client_id={CLIENT_ID}' \
  --data 'client_secret={CLIENT_SECRET}'
```

Upon a successful request, you'll receive an HTTP 200 response with a payload containing access\_token, refresh\_token, id\_token, token\_type, and expires\_in values:

```bash {{ title: "example response", id: "response-2" }}
{
  "access_token": "eyJz93a...k4laUWw",
  "refresh_token": "GEbRxBN...edjnXbL",
  "id_token": "eyJ0XAi...4faeEoQ",
  "token_type": "Bearer",
  "expires_in": 36000
}
```

## 2. Call your API

Send the following request to your API to get a response with an access token that can be used in the GraphQL playground to run queries.

```bash
curl -X POST https://{YOUR_APP_SUBDOMAIN}.erp.dev/oauth2/token \
    -F grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer \
    -F assertion={id_token}
```

```bash {{ title: "example response", id: "response-2" }}
{
    "access_token":"0wxc8b...DQxfFtx",
    "refresh_token":"khScdBQ...p6OmDoY",
    "expires_in":86400
}
```

---

---
url: https://docs.tailor.tech/tutorials/setup-executor/overview.md
---
# Setting up the Executor

This tutorial section demonstrates how to create and use an Executor. You'll learn key concepts and techniques that are fundamental to using Executor service.

[Executor service](/guides/executor/overview) executes the user defined job based on a trigger. A job either sends an HTTP request to certain endpoint or executes a GQL query in the Tailor Application.

In this tutorial section, you'll activate the Executor service and learn about different types of triggers.

## What you'll learn

* [Event based trigger](/tutorials/setup-executor/event-based-trigger)
* [Incoming hook trigger](/tutorials/setup-executor/incoming-webhook-trigger)
* [Schedule based trigger](/tutorials/setup-executor/schedule-based-trigger)

## Prerequisite

* Complete [Quickstart](/getting-started/quickstart)&#x20;

---

---
url: https://docs.tailor.tech/tutorials/setup-executor/event-based-trigger.md
---
# Setting up an Event-based Trigger

Event-based triggers allow you to automatically run actions when specific database events occur. In this tutorial, we'll create an executor that sends a Slack notification when a Project's status changes to "COMPLETED".

* To follow along with this tutorial, first complete the [SDK Quickstart](../../sdk/quickstart) and the [Data Schema Basics](../manage-data-schema/data-schema-basics) tutorial.

## Tutorial Steps

To create an event-based trigger, you'll need to:

1. Configure the Executor service
2. Create the executor with a record updated trigger
3. Enable `publishEvents` feature on the Project table
4. Deploy the changes
5. Verify the trigger

### 1. Configure the Executor Service

Update your `tailor.config.ts` to include the executor service:

```typescript
import { defineConfig } from "@tailor-platform/sdk";

export default defineConfig({
  name: "project-management",
  db: {
    "main-db": {
      files: ["db/**/*.ts"],
    },
  },
  executor: {
    files: ["executor/**/*.ts"],
  },
});
```

This configures the SDK to load executor definitions from the `executor/` directory.

### 2. Create the Executor with Record Updated Trigger

Create a new file `executor/notify-project-completion.ts`:

```typescript
import { createExecutor, recordUpdatedTrigger } from "@tailor-platform/sdk";
import { project } from "../db/project";
import { getDB } from "../generated/tailordb";

export default createExecutor({
  name: "notify-project-completion",
  description: "Send Slack notification when project is completed",
  trigger: recordUpdatedTrigger({
    type: project,
    condition: ({ newRecord, oldRecord }) =>
      newRecord.status === "COMPLETED" && oldRecord.status !== "COMPLETED",
  }),
  operation: {
    kind: "webhook",
    url: () => "https://hooks.slack.com/services/YOUR_WEBHOOK_URL",
    headers: {
      "Content-Type": "application/json",
    },
    requestBody: async ({ newRecord }) => {
      const db = getDB("main-db");

      // Count tasks for summary
      const taskStats = await db
        .selectFrom("Task")
        .select(({ fn }) => [
          fn.count<number>("id").as("total"),
          fn.countAll<number>().filterWhere("status", "=", "DONE").as("completed"),
        ])
        .where("projectId", "=", newRecord.id)
        .executeTakeFirst();

      return {
        text: `🎉 Project Completed: ${newRecord.name}`,
        blocks: [
          {
            type: "section",
            text: {
              type: "mrkdwn",
              text: `*Project:* ${newRecord.name}\n*Status:* ${newRecord.status}\n*Tasks:* ${taskStats?.completed}/${taskStats?.total} completed`,
            },
          },
        ],
      };
    },
  },
});
```

**Key Components:**

1. **Trigger**: `recordUpdatedTrigger()` fires when a Project record is updated
   * `type: project`: Specifies which table to monitor
   * `condition`: Only triggers when status changes TO "COMPLETED" (not already completed)

2. **Operation**: `webhook` sends HTTP POST request to Slack
   * `url`: Your Slack webhook URL (replace with actual URL from Slack)
   * `requestBody`: Constructs the Slack message with project details and task statistics

3. **Database Query**: Uses Kysely to query task completion statistics before sending the notification

### 3. Enable `publishEvents` Feature

To ensure the executor triggers when Project records are updated, enable `publishEvents` in your Project table definition.

Update your `db/project.ts` file:

```typescript
import { db } from "@tailor-platform/sdk";

export const project = db
  .table("Project", {
    name: db.string().description("Project name"),
    description: db.string().optional().description("Project description"),
    status: db
      .enum(["planning", "active", "completed", "archived"])
      .description("Current project status"),
    startDate: db.string().optional().description("Project start date"),
    endDate: db.string().optional().description("Project end date"),
    createdAt: db.string().description("Creation timestamp"),
    updatedAt: db.string().description("Last update timestamp"),
  })
  .features({
    publishEvents: true,
  });
```

The `.features({ publishEvents: true })` configuration enables the platform to publish events when Project records are created, updated, or deleted. Without this feature enabled, the executor trigger will not fire.

### 4. Deploy the Changes

Before deploying, make sure you have:

1. Created a Slack webhook URL (see [Slack Incoming Webhooks](https://api.slack.com/messaging/webhooks))
2. Replaced `YOUR_WEBHOOK_URL` in the executor code with your actual webhook URL

Generate Kysely types for type-safe database access:

```bash
npm run generate
```

This generates TypeScript types and the `getDB()` helper in the `generated/` directory.

Deploy your application:

```bash
npm run deploy -- --workspace-id <your-workspace-id>
```

The SDK will deploy both the updated Project table with `publishEvents` enabled and the new executor.

### 5. Verify the Trigger

Open the [Console](https://console.tailor.tech) and navigate to your workspace. Select `Executors` to view the created executor.

**Test the Executor:**

1. **Create a test project**: In the GraphQL Playground, create a project with some tasks:

```graphql
mutation {
  createProject(
    input: {
      name: "Website Redesign"
      description: "Complete redesign of company website"
      status: "active"
      createdAt: "2026-02-09T10:00:00Z"
      updatedAt: "2026-02-09T10:00:00Z"
    }
  ) {
    id
  }
}
```

2. **Create some tasks** for the project (use the project ID from above):

```graphql
mutation {
  createTask(
    input: {
      title: "Design homepage"
      projectId: "<project-id>"
      status: "DONE"
      createdAt: "2026-02-09T10:00:00Z"
      updatedAt: "2026-02-09T10:00:00Z"
    }
  ) {
    id
  }
}
```

3. **Update the project status to COMPLETED**:

```graphql
mutation {
  updateProject(
    id: "<project-id>"
    input: { status: "COMPLETED", updatedAt: "2026-02-09T11:00:00Z" }
  ) {
    id
    status
  }
}
```

4. **Check Slack**: You should receive a notification in your Slack channel with the project name and task completion statistics.

5. **View executor logs**: In the Console, select the `Jobs` tab to see the executor execution history.

![Tailor Console Executor Jobs](../assets/tutorials-console-eventbased-executor-jobs.png)

Clicking `View Attempts` displays details of job execution attempts. The Tailor Platform automatically retries failed webhook calls (non-2xx status codes), except for configuration or script errors.

**Troubleshooting:**

* **No notification received**: Verify your Slack webhook URL is correct
* **Executor not triggering**: Ensure `publishEvents: true` is set in `.features()` on the Project table
* **Error in logs**: Check the executor logs in the Console for detailed error messages

## Multi-Event Triggers

Instead of creating separate executors for each event type, you can use `recordTrigger()` to handle multiple events in a single executor. This is useful when the response logic is similar across events.

Update `executor/notify-project-completion.ts` to also handle project creation:

```typescript
import { createExecutor, recordTrigger } from "@tailor-platform/sdk";
import { project } from "../db/project";

export default createExecutor({
  name: "notify-project-changes",
  description: "Send Slack notification on project create or status change to COMPLETED",
  trigger: recordTrigger({
    type: project,
    events: ["created", "updated"],
  }),
  operation: {
    kind: "webhook",
    url: () => "https://hooks.slack.com/services/YOUR_WEBHOOK_URL",
    headers: {
      "Content-Type": "application/json",
    },
    requestBody: async ({ event, newRecord, oldRecord }) => {
      if (event === "created") {
        return {
          text: `📋 New Project Created: ${newRecord.name}`,
        };
      }

      // event === "updated"
      if (newRecord.status === "COMPLETED" && oldRecord?.status !== "COMPLETED") {
        return {
          text: `🎉 Project Completed: ${newRecord.name}`,
        };
      }

      return null; // No notification for other updates
    },
  },
});
```

**Key differences from single-event triggers:**

|          | Single-event (`recordUpdatedTrigger`) | Multi-event (`recordTrigger`)            |
| -------- | ------------------------------------- | ---------------------------------------- |
| Import   | `recordUpdatedTrigger`                | `recordTrigger`                          |
| Events   | Fixed to one event                    | Pass `events: [...]` array               |
| Args     | Always has `oldRecord` + `newRecord`  | Use `args.event` to narrow the type      |
| Use case | Simple, focused handlers              | Shared logic across create/update/delete |

The `event` field on args is typed to match the `events` array you pass, so TypeScript will narrow correctly in `if (event === "created")` branches.

## Next Steps

Learn more about executors:

* [Executor Service](../../sdk/services/executor) - Complete executor documentation
* [Trigger Types](../../sdk/services/executor#trigger-types) - All available trigger types
* [Operation Types](../../sdk/services/executor#operation-types) - Different operation kinds
* [Schedule Triggers](schedule-based-trigger) - Create cron-based executors

---

---
url: https://docs.tailor.tech/tutorials/setup-executor/incoming-webhook-trigger.md
---
# Setting up an Incoming Webhook Trigger

Incoming webhook triggers allow external services to invoke actions in your Tailor application via HTTP requests. In this tutorial, we'll create an executor that accepts project updates from external tools (like GitHub, Jira, or custom integrations) and updates project status in your application.

* To follow along with this tutorial, first complete the [SDK Quickstart](../../sdk/quickstart) and the [Data Schema Basics](../manage-data-schema/data-schema-basics) tutorial.

## Tutorial Steps

To create an incoming webhook trigger, you'll need to:

1. Configure the Executor service
2. Create the executor with an incoming webhook trigger
3. Deploy the changes
4. Verify the trigger by sending webhook requests

### 1. Configure the Executor Service

Update your `tailor.config.ts` to include the executor service:

```typescript
import { defineConfig } from "@tailor-platform/sdk";

export default defineConfig({
  name: "project-management",
  db: {
    "main-db": {
      files: ["db/**/*.ts"],
    },
  },
  executor: {
    files: ["executor/**/*.ts"],
  },
});
```

This configures the SDK to load executor definitions from the `executor/` directory.

### 2. Create the Executor with Incoming Webhook Trigger

Create a new file `executor/webhook-update-project.ts`:

```typescript
import { createExecutor, incomingWebhookTrigger } from "@tailor-platform/sdk";
import { getDB } from "../generated/tailordb";

type WebhookPayload = {
  body: {
    projectId: string;
    status: string;
    description?: string;
  };
  headers: Record<string, string>;
};

export default createExecutor({
  name: "webhook-update-project",
  description: "Update project status via webhook from external tools",
  trigger: incomingWebhookTrigger<WebhookPayload>(),
  operation: {
    kind: "function",
    body: async ({ body, headers }) => {
      const db = getDB("main-db");

      // Validate the webhook payload
      if (!body.projectId || !body.status) {
        throw new Error("Missing required fields: projectId and status");
      }

      // Check if project exists
      const project = await db
        .selectFrom("Project")
        .selectAll()
        .where("id", "=", body.projectId)
        .executeTakeFirst();

      if (!project) {
        throw new Error(`Project not found: ${body.projectId}`);
      }

      // Update project status
      const updatedProject = await db
        .updateTable("Project")
        .set({
          status: body.status,
          description: body.description || project.description,
        })
        .where("id", "=", body.projectId)
        .returningAll()
        .executeTakeFirst();

      return {
        success: true,
        message: `Project ${updatedProject?.name} updated to ${body.status}`,
        projectId: updatedProject?.id,
      };
    },
  },
});
```

**Key Components:**

1. **Trigger**: `incomingWebhookTrigger<WebhookPayload>()` creates a webhook endpoint
   * Type parameter defines the expected payload structure
   * The trigger provides `body` and `headers` from the HTTP request

2. **Operation**: `function` executes custom TypeScript logic
   * Validates incoming payload
   * Checks if project exists
   * Updates project in the database
   * Returns success response

3. **Type Safety**: TypeScript types ensure payload structure is correct

**Payload Format:**

The webhook expects JSON payloads in this format:

```json
{
  "projectId": "project-uuid-here",
  "status": "completed",
  "description": "Updated project description (optional)"
}
```

You can also send form-urlencoded data, which will be automatically parsed into the `body` object.

### 3. Deploy the Changes

Deploy your application:

```bash
npm run deploy -- --workspace-id <your-workspace-id>
```

The SDK will create the incoming webhook endpoint for your executor.

### 4. Verify the Trigger

**Step 1: Get the webhook URL**

Open the [Console](https://console.tailor.tech) and navigate to your workspace. Select `Executors` and click on `webhook-update-project` to view the webhook URL.

The webhook URL format is:

```
https://api.erp.dev/v1/workspaces/{WORKSPACE_ID}/executors/webhook-update-project/invokeIncomingWebhook/{WEBHOOK_SECRET}
```

Alternatively, use the Tailor CLI:

```bash
npx tailor executor webhook list
```

**Step 2: Create a test project**

First, create a project to update. In the GraphQL Playground:

```graphql
mutation {
  createProject(
    input: {
      name: "API Integration Test"
      description: "Testing webhook integration"
      status: "planning"
      createdAt: "2026-02-09T10:00:00Z"
      updatedAt: "2026-02-09T10:00:00Z"
    }
  ) {
    id
    name
    status
  }
}
```

Note the project ID returned.

**Step 3: Send a webhook request**

Send a POST request to update the project status:

```bash
curl -X POST "https://api.erp.dev/v1/workspaces/{WORKSPACE_ID}/executors/webhook-update-project/invokeIncomingWebhook/{WEBHOOK_SECRET}" \
     -H "Content-Type: application/json" \
     -d '{
       "projectId": "<your-project-id>",
       "status": "active",
       "description": "Updated via webhook from external tool"
     }'
```

The webhook responds with `204 No Content`. The executor operation runs asynchronously after the response is sent.

You can also send form-urlencoded data:

```bash
curl -X POST "https://api.erp.dev/v1/workspaces/{WORKSPACE_ID}/executors/webhook-update-project/invokeIncomingWebhook/{WEBHOOK_SECRET}" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "projectId=<your-project-id>&status=completed&description=Done"
```

**Step 4: Verify the update**

Open the GraphQL Playground and query the project:

```graphql
query {
  project(id: "<your-project-id>") {
    id
    name
    status
    description
    updatedAt
  }
}
```

You should see the updated status and description.

**Step 5: View executor logs**

In the Console, select the `Jobs` tab under your executor to see the execution history. Each webhook call creates a job entry with:

* Request payload
* Execution status
* Response data
* Any errors encountered

## Security Considerations

1. **Webhook Secret**: The URL includes a secret token for authentication
2. **Validation**: Always validate incoming payloads in your executor function
3. **Error Handling**: Return appropriate error messages for invalid requests
4. **Rate Limiting**: Incoming webhook endpoints accept up to 100 requests per second per workspace. Requests above that are rejected with `429 Too Many Requests` — see [Incoming Webhook Rate Limit](../../reference/platform/platform-limits#incoming-webhook-rate-limit)

## Next Steps

Learn more about executors:

* [Executor Service](../../sdk/services/executor) - Complete executor documentation
* [Trigger Types](../../sdk/services/executor#trigger-types) - All available trigger types
* [Operation Types](../../sdk/services/executor#operation-types) - Different operation kinds
* [Event-based Triggers](event-based-trigger) - Create database event-driven executors

---

---
url: https://docs.tailor.tech/tutorials/setup-executor/schedule-based-trigger.md
---
# Setting up a Schedule-based Trigger

Schedule-based triggers allow you to automatically run actions at predefined intervals using cron expressions. In this tutorial, we'll create an executor that generates a daily project status report.

* To follow along with this tutorial, first complete the [SDK Quickstart](../../sdk/quickstart) and the [Data Schema Basics](../manage-data-schema/data-schema-basics) tutorial.

## Tutorial Steps

To create a schedule-based trigger, you'll need to:

1. Configure the Executor service
2. Create the executor with a schedule trigger
3. Deploy the changes
4. Verify the trigger

### 1. Configure the Executor Service

Update your `tailor.config.ts` to include the executor service:

```typescript
import { defineConfig } from "@tailor-platform/sdk";

export default defineConfig({
  name: "project-management",
  db: {
    "main-db": {
      files: ["db/**/*.ts"],
    },
  },
  executor: {
    files: ["executor/**/*.ts"],
  },
});
```

This configures the SDK to load executor definitions from the `executor/` directory.

### 2. Create the Executor with Schedule Trigger

Create a new file `executor/daily-project-report.ts`:

```typescript
import { createExecutor, scheduleTrigger } from "@tailor-platform/sdk";
import { getDB } from "../generated/tailordb";

export default createExecutor({
  name: "daily-project-report",
  description: "Generate daily project status report and send to Slack",
  trigger: scheduleTrigger({
    cron: "0 9 * * *", // Every day at 9:00 AM
    timezone: "America/New_York",
  }),
  operation: {
    kind: "webhook",
    url: () => "https://hooks.slack.com/services/YOUR_WEBHOOK_URL",
    headers: {
      "Content-Type": "application/json",
    },
    requestBody: async () => {
      const db = getDB("main-db");

      // Get all active projects
      const activeProjects = await db
        .selectFrom("Project")
        .selectAll()
        .where("status", "in", ["planning", "active"])
        .execute();

      // Count tasks by status for each project
      const projectSummaries = await Promise.all(
        activeProjects.map(async (project) => {
          const taskStats = await db
            .selectFrom("Task")
            .select(({ fn }) => [
              fn.count<number>("id").as("total"),
              fn.countAll<number>().filterWhere("status", "=", "DONE").as("completed"),
              fn.countAll<number>().filterWhere("status", "=", "TODO").as("todo"),
              fn.countAll<number>().filterWhere("status", "=", "IN_PROGRESS").as("inProgress"),
            ])
            .where("projectId", "=", project.id)
            .executeTakeFirst();

          return {
            name: project.name,
            status: project.status,
            stats: taskStats,
          };
        }),
      );

      // Format Slack message
      const projectBlocks = projectSummaries.map((p) => ({
        type: "section",
        text: {
          type: "mrkdwn",
          text:
            `*${p.name}* (${p.status})\n` +
            `Tasks: ${p.stats?.completed}/${p.stats?.total} completed | ` +
            `${p.stats?.inProgress} in progress | ${p.stats?.todo} todo`,
        },
      }));

      return {
        text: "Daily Project Status Report",
        blocks: [
          {
            type: "header",
            text: {
              type: "plain_text",
              text: "📊 Daily Project Status Report",
            },
          },
          {
            type: "section",
            text: {
              type: "mrkdwn",
              text: `Report generated: ${new Date().toLocaleDateString()}`,
            },
          },
          { type: "divider" },
          ...projectBlocks,
        ],
      };
    },
  },
});
```

**Key Components:**

1. **Trigger**: `scheduleTrigger()` runs the executor on a schedule
   * `cron`: Cron expression defining when to run (9 AM daily in this example)
   * `timezone`: Timezone for the schedule (optional, defaults to UTC)

2. **Cron Expression Format**: `minute hour day month day-of-week`
   * `0 9 * * *` = Every day at 9:00 AM
   * `*/5 * * * *` = Every 5 minutes
   * `0 */2 * * *` = Every 2 hours
   * `0 9 * * 1` = Every Monday at 9:00 AM
   * `0 0 1 * *` = First day of every month at midnight

3. **Operation**: Queries all active projects and their task statistics, then sends a formatted report to Slack

4. **Database Queries**: Uses Kysely to aggregate task data for each project

### 3. Deploy the Changes

Before deploying, make sure you have:

1. Created a Slack webhook URL (see [Slack Incoming Webhooks](https://api.slack.com/messaging/webhooks))
2. Replaced `YOUR_WEBHOOK_URL` in the executor code with your actual webhook URL
3. Generated Kysely types: `npm run generate` (if using Kysely type generator)

Deploy your application:

```bash
npm run deploy -- --workspace-id <your-workspace-id>
```

The SDK will deploy the executor with the schedule configuration.

### 4. Verify the Trigger

Open the [Console](https://console.tailor.tech) and navigate to your workspace. Select `Executors` to view the created executor.

**Understanding Schedule Execution:**

Scheduled executors:

* Run automatically according to the cron expression
* Execute in the specified timezone
* Appear in the Jobs tab after each execution
* Can be manually triggered from the Console for testing

**Test the Executor:**

While the executor will run automatically according to the schedule, you can test it immediately:

1. **Manually trigger the executor**: In the Console, find your executor and click "Run Now" to execute it immediately

2. **Check Slack**: Verify that the daily report appears in your Slack channel with project summaries

3. **View execution logs**: Select the `Jobs` tab to see execution history

**Troubleshooting:**

* **No notification received**: Check the Slack webhook URL and test it manually with curl
* **Error in logs**: Review the executor logs in the Console for detailed error messages

## Next Steps

Learn more about executors:

* [Executor Service](../../sdk/services/executor) - Complete executor documentation
* [Schedule Triggers](../../sdk/services/executor#schedule-trigger) - Detailed cron configuration
* [Operation Types](../../sdk/services/executor#operation-types) - Different operation kinds
* [Event-based Triggers](event-based-trigger) - React to database changes

---

---
url: https://docs.tailor.tech/getting-started/core-concepts.md
---
# Core Concepts

* [Platform Architecture](platform-architecture.md) - Understand the hierarchical structure of Tailor Platform resources and how they relate to each other
* [Workspace & Application](workspace-application.md) - Learn about Workspaces (top-level containers) and Applications (deployable units within Workspaces)
* [Services](services.md) - Explore Tailor Platform's core services including TailorDB, Auth, Resolver, and Workflow

---

---
url: https://docs.tailor.tech/app-shell.md
description: >-
  AppShell is an opinionated React application framework for creating
  applications on Tailor Platform with built-in authentication, routing, and
  beautiful UI components.
---

# Introduction

AppShell is a React-based framework that provides the foundation for building custom ERP applications on Tailor Platform. It handles the complex infrastructure so you can focus on building business-level screens and features.

## Why AppShell?

Building ERP applications involves a lot of repetitive infrastructure: authentication, routing, sidebar navigation, breadcrumbs, command palette, permission guards — and keeping them all in sync. AppShell exists to solve this integration problem.

**One declaration drives everything.** When you define a page with `appShellPageProps`, AppShell automatically generates the sidebar item, breadcrumb entry, command palette search result, and route guard — all from a single source of truth. Change a guard to `hidden`, and the page disappears from everywhere at once. No manual sync, no silent bugs.

**Purpose-built for ERP.** Most ERP screens are variations of the same CRUD patterns — lists, detail views, create forms, edit forms. AppShell absorbs this repetitive structure so you can focus your effort on the screens that actually require custom logic: dashboards, approval workflows, and domain-specific visualizations.

**Type-safe by design.** AppShell propagates types across your entire application. Module definitions, route paths, and context data are all type-checked at compile time, catching integration errors before they reach production.

**Vertically integrated with Tailor Platform.** Unlike generic admin frameworks that abstract away the backend, AppShell embraces its tight coupling with Tailor Platform. This lets it provide a complete, opinionated stack — from OAuth2/DPoP authentication to data fetching — without requiring you to write glue code.

## Our Backstory

AppShell was born from real-world ERP delivery projects at Tailor Technologies.

As we built multiple ERP systems on Tailor Platform for different clients, we kept writing the same integration code: wiring up authentication, connecting sidebar navigation to route guards, syncing breadcrumbs with page definitions. Each project had its own slightly different version of this glue, and every variation introduced new opportunities for bugs.

We extracted these common patterns into a shared framework. Instead of documenting "how to wire things together" and hoping every project follows the guide, we encoded the integration directly into code and types — making incorrect wiring a compile-time error rather than a runtime surprise.

Today, AppShell also reflects our bet on AI-assisted development. We operate with small teams augmented by AI agents, running multiple client projects in parallel. The framework's file-based conventions and declarative APIs minimize the decisions an AI agent needs to make — "where does this page go?" and "what do I need to declare?" always have exactly one answer. Knowledge gained on one project — whether by a developer or an AI skill file — transfers directly to the next.

For a deeper look at the tradeoffs and principles behind these choices, see [Design Philosophy](design-philosophy).

## Next Steps

* **[Quick Start](quickstart)** — Install AppShell and build your first page in minutes
* **[Modules & Resources](concepts/modules-and-resources)** — Understand how pages are declared and organized
* **[File-Based Routing](concepts/file-based-routing)** — Learn how directory structure drives navigation
* **[Authentication](concepts/authentication)** — Configure OAuth2 and identity providers
* **[Styling & Theming](concepts/styling-theming)** — Customize the look and feel

## Hosted References

* **[UI Catalogue](https://ui.tailor.tech)** — Every component rendered live, plus full-page samples, composite UI patterns, and routing recipes with copyable source
* **[Theme Generator](https://theme.tailor.tech/playground)** — Pick a primary color and export a matching AppShell palette CSS file

---

---
url: https://docs.tailor.tech/sdk/plugin.md
---
# Plugins (Beta)

> **Beta Feature**: The plugin system is currently in beta. APIs may change in future releases.

Plugins extend TailorDB tables by automatically generating additional tables, executors, and output files based on your table definitions.

## Overview

When you run `tailor generate`, the SDK:

1. Loads all TailorDB tables with plugin attachments
2. Passes each table to the attached plugins
3. Generates additional tables and executors based on plugin output
4. Writes all generated files to the appropriate locations

This enables plugins to create derived functionality based on your application's schema.

## Configuration

### Registering Plugins

Define plugins in `tailor.config.ts` using `definePlugins()`:

```typescript
import { defineConfig, definePlugins } from "@tailor-platform/sdk";
import myPlugin from "./plugins/my-plugin";

export const plugins = definePlugins(myPlugin);

export default defineConfig({
  name: "my-app",
  // ...
});
```

**Important**: The `plugins` export must be a named export (not default).

### Attaching Plugins to Tables

Use the `.plugin()` method to attach plugins to specific tables:

```typescript
import { db } from "@tailor-platform/sdk";

export const user = db
  .table("User", {
    name: db.string(),
    email: db.string(),
  })
  .plugin({
    "@example/my-plugin": {},
  });
```

### Plugin Configuration

Some plugins accept per-table configuration:

```typescript
export const customer = db
  .table("Customer", {
    name: db.string(),
    // ...
  })
  .plugin({
    "@example/soft-delete": {
      archiveReason: true,
      retentionDays: 90,
    },
  });
```

### Per-table Config Requirement

Per-table config is optional by default. Plugin authors can change this with
`tableConfigRequired` (boolean or function). When a function is used, it receives
the plugin-level config from `definePlugins()`.

### Global Plugin Configuration

Plugins can also accept global configuration via `definePlugins()`:

```typescript
import { definePlugins } from "@tailor-platform/sdk";
import { softDeletePlugin } from "./plugins/soft-delete";

export const plugins = definePlugins(
  // Custom plugin with global config (factory function)
  softDeletePlugin({
    archiveTablePrefix: "Deleted_",
    defaultRetentionDays: 90,
  }),
);
```

## Generated Output

Plugins can generate:

* **Tables**: Additional TailorDB tables (e.g., `CustomerHistory`, `Deleted_Customer`)
* **Executors**: Event handlers triggered by record changes
* **Field Extensions**: Additional fields added to the source table
* **Output Files**: TypeScript code and other files via generation-time hooks

Tables produced by definition-time hooks are validated before registration. This includes
generated tables and source tables after field extensions are applied. Malformed output stops
the build with an error that identifies the plugin and relevant table output, without partially
registering tables from that processing step.

Generated files are placed under `.tailor/<plugin-id>/` (the plugin ID is sanitized,
e.g. `@example/soft-delete` → `example-soft-delete`), such as:

* `.tailor/example-soft-delete/types`
* `.tailor/example-soft-delete/executors`

## Plugin Lifecycle

Plugins have 5 hooks across two lifecycle phases. Each hook fires at a specific point in the `tailor generate` pipeline:

```
tailor generate
│
├─ Load TailorDB tables
│   ├─ onTableLoaded       ← per table with .plugin() attached
│   └─ onNamespaceLoaded   ← once per namespace (namespace plugins)
│
├─ Resolve Auth
│
├─ onTailorDBReady           ← all tables finalized
│
├─ Load Resolvers
│
├─ onResolverReady           ← all resolvers finalized
│
├─ Load Executors
│
└─ onExecutorReady           ← all executors finalized
```

### Definition-time hooks

| Hook                | Trigger                              | Can do                                                            |
| ------------------- | ------------------------------------ | ----------------------------------------------------------------- |
| `onTableLoaded`     | Each table with `.plugin()` attached | Generate tables, resolvers, executors; extend source table fields |
| `onNamespaceLoaded` | Once per namespace                   | Generate tables, resolvers, executors                             |

These hooks produce TailorDB tables, resolvers, and executors that become part of the application. Requires `importPath` on the plugin.

### Generation-time hooks

| Hook              | Available data                              | Can do             |
| ----------------- | ------------------------------------------- | ------------------ |
| `onTailorDBReady` | TailorDB tables, Auth                       | Write output files |
| `onResolverReady` | TailorDB tables, Resolvers, Auth            | Write output files |
| `onExecutorReady` | TailorDB tables, Resolvers, Executors, Auth | Write output files |

These hooks receive all finalized data and produce output files (TypeScript code, etc.). No `importPath` required.

A plugin can implement hooks from either or both phases.

## Creating Custom Plugins

See [Custom Plugins](custom) for the full hook reference and examples.

---

---
url: https://docs.tailor.tech/guides/workflow.md
---

# Workflow Service

## Overview

Workflow service enables you to build and execute complex, multi-step background jobs with automatic state management and resume capabilities on Tailor Platform.

If a workflow fails at any step, you can resume it from where it stopped without re-executing successful steps, making it ideal for long-running operations that need reliability.

With Workflow service, you can:

* Chain multiple JavaScript functions into durable workflows
* Automatically preserve execution state at each step
* Resume failed workflows from the point of failure
* Access TailorDB and other platform services with proper authentication
* Monitor execution progress through Tailor Console and tailor CLI

### Workflow vs Function

Both Workflow and Function services execute JavaScript code, but serve different purposes:

| Feature               | Function                       | Workflow                                      |
| --------------------- | ------------------------------ | --------------------------------------------- |
| **Execution model**   | Synchronous, single execution  | Multi-step, stateful execution                |
| **Duration**          | Short-lived (seconds)          | Long-running (minutes to hours)               |
| **State management**  | None                           | Automatic state preservation                  |
| **Resume capability** | No                             | Yes, from point of failure                    |
| **Use case**          | Data transformation, API calls | Complex background jobs, multi-step processes |
| **Called from**       | Resolvers, Executors           | Executors, Functions                          |

**When to use Workflow:**

* You need to chain multiple operations with state preservation
* The job may fail and needs to be resumed without repeating successful steps
* You're orchestrating complex business processes across multiple services

**When to use Function:**

* You need quick, synchronous data processing
* The operation is a single, atomic task
* You're transforming data within resolvers

## How Workflow Execution Works

### Durable Execution Model

Workflow service uses a **durable execution model** where the execution state is automatically saved after each successful step.

**Example execution flow:**

```
Step 1: Fetch data from API    → Success ✓ (result cached)
Step 2: Transform data          → Success ✓ (result cached)
Step 3: Save to database        → Failed ✗
```

When you resume the workflow:

```
Step 1: Fetch data from API    → Skipped (use cached result)
Step 2: Transform data          → Skipped (use cached result)
Step 3: Save to database        → Retry from here
```

**Benefits:**

* **No duplicate work**: Successful steps are never re-executed
* **Safe retries**: You can retry as many times as needed
* **Cost efficient**: Only failed steps consume resources on retry
* **Data consistency**: Results from successful steps remain available

### Stack-Based Execution

Workflows support nested function calls, similar to regular programming:

```javascript
export function main(args) {
  // Call functions sequentially
  const data = tailor.workflow.execJobFunction("fetchData", {});
  const processed = tailor.workflow.execJobFunction("processData", data);
  return processed;
}
```

The execution stack:

```
[] → [main] → [main, fetchData] → [main] → [main, processData] → [main] → []
```

Each function's result is cached and passed to the next function in the chain.

Job functions within a single workflow execute **sequentially**, not in parallel. Each function completes before the next one starts. For concurrent execution, you can start multiple workflows asynchronously using `tailor.workflow.startWorkflow()`.

## Concurrency Control

In addition to the [platform-wide caps](/reference/platform/platform-limits#workflow-concurrency-limits) (50 per workspace, 20 per workflow), workflows can declare two independent concurrency policies. Neither rejects excess work, but they defer it in different ways: the workflow-level policy keeps new executions in `PENDING` at the scheduler, and the job function execution policy suspends the running workflow to `PENDING_RESUME` at dispatch time. Both resume automatically as slots free up.

### Workflow-level Concurrency Policy

Set `concurrencyPolicy.maxConcurrentExecutions` on the workflow definition to cap how many executions of the same workflow may run at once.

* Enforced by the **scheduler** when it picks up `PENDING` executions. Executions that would exceed the cap stay `PENDING` and are re-evaluated on the next scheduler tick.
* Scoped per workflow definition. Other workflows in the same workspace are unaffected.
* Applies to every entry point (`startWorkflow`, executor triggers, CLI `workflow start`) equally.

```typescript {{ title: 'workflows/import-orders.ts' }}
import { createWorkflow } from "@tailor-platform/sdk";
import { importOrders } from "./jobs/import-orders";

export default createWorkflow({
  name: "import-orders",
  mainJob: importOrders,
  concurrencyPolicy: {
    // At most 3 executions of `import-orders` run concurrently across the
    // workspace. The 4th trigger stays PENDING until one of the running
    // executions finishes.
    maxConcurrentExecutions: 3,
  },
});
```

See [Concurrency Policy](/sdk/services/workflow#concurrency-policy) in the SDK Workflow reference for the SDK API.

### Job Function Execution Policies

Declare workspace-scoped execution policies with a per-key `maxConcurrentExecutions` cap, then route job function dispatches through them by passing `executionPolicyKey` on `job.start()` / `tailor.workflow.execJobFunction()`.

* Enforced by the **runner** at dispatch time — a separate mechanism from the scheduler-level workflow cap above. The two stack: a workflow that is allowed to start can still have its job function dispatches suspended by an execution policy.
* Dispatches that would exceed the cap are suspended and resume automatically as slots free up.
* A dispatch without `executionPolicyKey` is unaffected by all declared policies, but still counts against the [platform workspace-wide job function limit](/reference/platform/platform-limits#workflow-job-function-concurrency-limits).
* User policies stack **on top of** the platform hard limits (workspace-wide 100 dispatches, per-key fallback 50 for policies without a user-defined cap). The most restrictive applicable cap wins.

**Declare policies and register them on the SDK config:**

```typescript {{ title: 'workflows/policies.ts' }}
import { defineWorkflowExecutionPolicies } from "@tailor-platform/sdk";

export const executionPolicies = defineWorkflowExecutionPolicies((define) => ({
  // Exact-key policy: one shared pool for dispatches keyed "premium".
  premium: define({ concurrencyPolicy: { maxConcurrentExecutions: 5 } }),
  // Wildcard policy: independent pool of size 3 per resolved key
  // (`tenant-api.acme`, `tenant-api.beta`, ...).
  tenantApi: define({
    name: "tenant-api",
    matchType: "prefix",
    concurrencyPolicy: { maxConcurrentExecutions: 3 },
  }),
}));
```

```typescript {{ title: 'tailor.config.ts' }}
import { defineConfig } from "@tailor-platform/sdk";
import { executionPolicies } from "./workflows/policies";

export default defineConfig({
  workflow: {
    files: ["workflows/**/*.ts"],
    executionPolicies,
  },
});
```

**Route a dispatch through a policy:**

```typescript {{ title: 'workflows/jobs/sync-tenant.ts' }}
import { createWorkflowJob } from "@tailor-platform/sdk";
import { executionPolicies } from "../policies";
import { syncOrders } from "./sync-orders";
import { pushMetrics } from "./push-metrics";

export const syncTenant = createWorkflowJob({
  name: "sync-tenant",
  body: async (input: { tenantId: string }) => {
    // Exact-key policy: pass `.key` directly (typed).
    await pushMetrics.start(
      { tenantId: input.tenantId },
      { executionPolicyKey: executionPolicies.premium.key },
    );

    // Wildcard policy: build the concrete key with `.keyFor(suffix)`.
    // Resolves to e.g. "tenant-api.acme"; each tenant gets its own pool of 3.
    await syncOrders.start(
      { tenantId: input.tenantId },
      { executionPolicyKey: executionPolicies.tenantApi.keyFor(input.tenantId) },
    );
  },
});
```

The same `executionPolicyKey` option is available on `tailor.workflow.execJobFunction(name, args, options)` when dispatching by name from a Function-service script.

**Matching modes:**

| Match type        | Declaration                       | Applies to                                          | Pool granularity                          |
| ----------------- | --------------------------------- | --------------------------------------------------- | ----------------------------------------- |
| Exact (default)   | `matchType: "exact"` (or omitted) | Dispatches whose key equals the policy key          | One pool shared by the exact key          |
| Prefix (wildcard) | `matchType: "prefix"`             | Dispatches whose key **starts with** the policy key | One independent pool **per resolved key** |

For wildcard policies, the platform registers the prefix with a trailing `*` and gives every concrete resolved key its own pool of the declared size. In the example above, `tenant-api` with `maxConcurrentExecutions: 3` allows **3 concurrent dispatches per tenant key** — `tenant-api.acme`, `tenant-api.beta`, and `tenant-api.gamma` each run up to 3 in parallel independently, not 3 across all of them combined.

**Overlapping policies stack (AND-of-caps).** When a dispatch key is covered by more than one policy (any mix of exact and wildcard prefixes), every covering policy applies — the dispatch acquires one slot in each matching pool, and any single saturated cap blocks it.

```typescript {{ title: 'workflows/policies.ts' }}
export const executionPolicies = defineWorkflowExecutionPolicies((define) => ({
  // Broad safety net: at most 100 dispatches under the "one" tree at once.
  one: define({
    name: "one",
    matchType: "prefix",
    concurrencyPolicy: { maxConcurrentExecutions: 100 },
  }),
  // Narrower cap for the "one.two" subtree.
  oneTwo: define({
    name: "one.two",
    matchType: "prefix",
    concurrencyPolicy: { maxConcurrentExecutions: 10 },
  }),
  // Even tighter cap for one exact key.
  oneTwoThree: define({
    name: "one.two.three",
    concurrencyPolicy: { maxConcurrentExecutions: 3 },
  }),
}));

// A dispatch with executionPolicyKey: "one.two.three" counts against all
// three pools simultaneously; the tightest cap (3) is what actually blocks.
// The broader `one*` and `one.two*` caps still guard the whole subtree, so a
// narrower policy cannot silently disable them.
```

See [Execution Policies](/sdk/services/workflow#execution-policies) in the SDK Workflow reference for the full declaration API, key grammar, and options for customizing `keyFor()`.