@tailor-platform/sdk 0.16.3 → 0.17.0

package/docs/services/tailordb.md

@@ -0,0 +1,305 @@
+# 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 types 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](https://docs.tailor.tech/guides/tailordb/overview).
+
+## Type Definition
+
+Define TailorDB Types in files matching glob patterns specified in `tailor.config.ts`.
+
+```typescript
+import { db } from "@tailor-platform/sdk";
+
+export const user = db.type("User", {
+  name: db.string(),
+  email: db.string().unique(),
+  age: db.int(),
+  ...db.fields.timestamps(),
+});
+```
+
+Specify plural form by passing an array as first argument:
+
+```typescript
+db.type(["User", "UserList"], {
+  name: db.string(),
+});
+```
+
+Pass a description as second argument:
+
+```typescript
+db.type("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.bool()`                     | Boolean  | boolean        |
+| `db.date()`                     | Date     | string         |
+| `db.datetime()`                 | DateTime | string \| Date |
+| `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 });
+```
+
+### Enum Fields
+
+```typescript
+db.enum(["red", "green", "blue"]);
+db.enum([
+  { value: "active", description: "Active status" },
+  { value: "inactive", description: "Inactive status" },
+]);
+```
+
+### Object Fields
+
+```typescript
+db.object({
+  street: db.string(),
+  city: db.string(),
+  country: db.string(),
+});
+```
+
+## 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.type("Role", {
+  name: db.string(),
+});
+
+const user = db.type("User", {
+  name: db.string(),
+  roleId: db.uuid().relation({
+    type: "n-1",
+    toward: { type: role },
+  }),
+});
+```
+
+For one-to-one relations, use `type: "1-1"`:
+
+```typescript
+const userProfile = db.type("UserProfile", {
+  userId: db.uuid().relation({
+    type: "1-1",
+    toward: { type: user },
+  }),
+  bio: db.string(),
+});
+```
+
+For foreign key constraint without creating a relation, use `type: "keyOnly"`:
+
+```typescript
+const user = db.type("User", {
+  roleId: db.uuid().relation({
+    type: "keyOnly",
+    toward: { type: role },
+  }),
+});
+```
+
+Create relations against different fields using `toward.key`:
+
+```typescript
+const user = db.type("User", {
+  email: db.string().unique(),
+});
+
+const userProfile = db.type("UserProfile", {
+  userEmail: db.string().relation({
+    type: "1-1",
+    toward: { type: user, key: "email" },
+  }),
+});
+```
+
+Customize relation names using `toward.as` / `backward` options:
+
+```typescript
+const userProfile = db.type("UserProfile", {
+  userId: db.uuid().relation({
+    type: "1-1",
+    toward: { type: 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 type from this type
+- `backward` - Customizes the field name for accessing this type from the related type
+
+### Hooks
+
+Add hooks to execute functions during data creation or update:
+
+```typescript
+db.datetime().hooks({
+  create: () => new Date(),
+  update: () => new Date(),
+});
+```
+
+Function arguments include: `value` (field value), `data` (entire record value), `user` (user performing the operation).
+
+### Validation
+
+```typescript
+db.string().validate(
+  ({ value }) => value.length > 5,
+  [
+    ({ value }) => value.length < 10,
+    "Value must be shorter than 10 characters",
+  ],
+);
+```
+
+### 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.type("User", {
+  name: db.string(),
+  ...db.fields.timestamps(),
+});
+```
+
+## Type Modifiers
+
+### Composite Indexes
+
+```typescript
+db.type("User", {
+  firstName: db.string(),
+  lastName: db.string(),
+}).indexes({
+  fields: ["firstName", "lastName"],
+  unique: true,
+  name: "user_name_idx",
+});
+```
+
+### File Fields
+
+```typescript
+db.type("User", {
+  name: db.string(),
+}).files({
+  avatar: "profile image",
+});
+```
+
+### Features
+
+```typescript
+db.type("User", {
+  name: db.string(),
+}).features({
+  aggregation: true,
+  bulkUpsert: true,
+});
+```
+
+### Permissions
+
+Configure Permission and GQLPermission. For details, see the [TailorDB Permission documentation](https://docs.tailor.tech/guides/tailordb/permission).
+
+```typescript
+db.type("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"] },
+  ]);
+```
+
+Following the secure-by-default principle, all operations are denied if permissions are not configured.

package/docs/services/workflow.md

@@ -0,0 +1,176 @@
+# 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 triggering for parallel or sequential execution
+
+For the official Tailor Platform documentation, see [Workflow Guide](https://docs.tailor.tech/guides/workflow).
+
+## Workflow Rules
+
+All workflow components must follow these rules:
+
+| Rule                                           | Description                                         |
+| ---------------------------------------------- | --------------------------------------------------- |
+| `createWorkflow` result must be default export | Workflow files must export the workflow as default  |
+| All jobs must be named exports                 | Every job used in a workflow must be a named export |
+| Job names must be unique                       | Job names must be unique across the entire project  |
+| `mainJob` is required                          | Every workflow must specify a `mainJob`             |
+| Jobs in `deps` must be job objects             | Pass job objects, not strings                       |
+
+## 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;
+  },
+});
+```
+
+## Job Dependencies
+
+Jobs can depend on other jobs using the `deps` array. Dependent jobs are accessible via the second argument of `body` function with hyphens replaced by underscores:
+
+```typescript
+import { createWorkflowJob } from "@tailor-platform/sdk";
+import { fetchCustomer } from "./jobs/fetch-customer";
+import { sendNotification } from "./jobs/send-notification";
+
+// All jobs must be named exports - including jobs with dependencies
+export const processOrder = createWorkflowJob({
+  name: "process-order",
+  deps: [fetchCustomer, sendNotification],
+  body: async (input: { orderId: string; customerId: string }, { jobs }) => {
+    // Access dependent jobs with hyphens replaced by underscores
+    // "fetch-customer" -> jobs.fetch_customer()
+    // "send-notification" -> jobs.send_notification()
+    const customer = await jobs.fetch_customer({
+      customerId: input.customerId,
+    });
+
+    const notification = await jobs.send_notification({
+      message: `Order ${input.orderId} is being processed`,
+      recipient: customer.email,
+    });
+
+    return {
+      orderId: input.orderId,
+      customerEmail: customer.email,
+      notificationSent: notification.sent,
+    };
+  },
+});
+```
+
+## Triggering Jobs
+
+Use `.trigger()` to start other jobs from within a job:
+
+```typescript
+export const mainJob = createWorkflowJob({
+  name: "main-job",
+  deps: [fetchCustomer, sendNotification],
+  body: (input: { customerId: string }, { jobs }) => {
+    // .trigger() is synchronous on server - do NOT use await
+    // "fetch-customer" -> jobs.fetch_customer
+    const customer = jobs.fetch_customer.trigger({
+      customerId: input.customerId,
+    });
+    const notification = jobs.send_notification.trigger({
+      message: "Order processed",
+      recipient: customer.email,
+    });
+    return { customer, notification };
+  },
+});
+```
+
+**Important:** `.trigger()` is synchronous on the server. Do NOT use `await` with it.
+
+## 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",
+  deps: [fetchCustomer, sendNotification],
+  body: async (input, { jobs }) => {
+    // ... job logic
+  },
+});
+
+// Workflow must be default export
+export default createWorkflow({
+  name: "order-processing",
+  mainJob: processOrder,
+});
+```
+
+## 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-sdk workflow list
+
+# Get workflow details
+tailor-sdk workflow get <name>
+
+# Start a workflow
+tailor-sdk workflow start <name> -m <machine-user> -g '{"key": "value"}'
+
+# List executions
+tailor-sdk workflow executions
+
+# Get execution details with logs
+tailor-sdk workflow executions <execution-id> --logs
+
+# Resume a failed execution
+tailor-sdk workflow resume <execution-id>
+```
+
+See [Workflow CLI Commands](../cli/workflow.md) for full documentation.

package/docs/testing.md

@@ -1,6 +1,8 @@
 # Testing Guide
 
-This guide covers testing patterns for Tailor Platform SDK applications using [Vitest](https://vitest.dev/). For a complete working example with full test code, use:
+This guide covers testing patterns for Tailor Platform SDK applications using [Vitest](https://vitest.dev/).
+
+For a complete working example with full test code, use the `testing` template:
 
 ```bash
 npm create @tailor-platform/sdk <your-project-name> --template testing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailor-platform/sdk",
-  "version": "0.16.3",
+  "version": "0.17.0",
   "description": "Tailor Platform SDK - The SDK to work with Tailor Platform",
   "license": "MIT",
   "main": "./dist/configure/index.mjs",
@@ -50,6 +50,7 @@
     "citty": "0.1.6",
     "confbox": "0.2.2",
     "consola": "3.4.2",
+    "date-fns": "4.1.0",
     "es-toolkit": "1.42.0",
     "inflection": "3.0.2",
     "madge": "8.0.0",
@@ -74,13 +75,13 @@
     "@types/node": "22.19.2",
     "cross-env": "10.1.0",
     "eslint": "9.39.1",
-    "eslint-plugin-jsdoc": "61.4.1",
+    "eslint-plugin-jsdoc": "61.5.0",
     "globals": "16.5.0",
     "sonda": "0.10.1",
     "tsdown": "0.15.6",
     "typescript": "5.9.3",
     "typescript-eslint": "8.49.0",
-    "vitest": "4.0.14"
+    "vitest": "4.0.15"
   },
   "scripts": {
     "test": "vitest",