@tailor-platform/sdk 1.11.0 → 1.12.0

package/dist/utils/test/index.d.mts

@@ -1,6 +1,6 @@
 /// <reference path="./../../user-defined.d.ts" />
-import { et as TailorDBType, mt as TailorField } from "../../index-DcOTucF6.mjs";
-import { W as WORKFLOW_TEST_ENV_KEY, n as output } from "../../index-D8zIUsWi.mjs";
+import { Ft as TailorField, rt as TailorDBType } from "../../index-Bid18Opo.mjs";
+import { G as WORKFLOW_TEST_ENV_KEY, n as output } from "../../index-BBr_q3vB.mjs";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 
 //#region src/utils/test/index.d.ts

package/dist/utils/test/index.mjs

@@ -1,4 +1,4 @@
-import { t as WORKFLOW_TEST_ENV_KEY } from "../../job-l-pIR9IY.mjs";
+import { t as WORKFLOW_TEST_ENV_KEY } from "../../job-zGAXCidt.mjs";
 
 //#region src/utils/test/index.ts
 /** Represents an unauthenticated user in the Tailor platform. */

package/docs/cli/tailordb.md

@@ -651,18 +651,6 @@ tailor-sdk apply --no-schema-check
 **Notes:**
 
 - This command is a beta feature and may introduce breaking changes in future releases
-- `@liam-hq/cli` is required for `export`, `serve`, and `deploy`
-- `serve` is required only for `tailordb erd serve`
-
-Install dependencies:
-
-```bash
-npm i -D @liam-hq/cli serve
-# OR
-yarn add -D @liam-hq/cli serve
-# OR
-pnpm add -D @liam-hq/cli serve
-```
 
 **Usage Examples:**
 

package/docs/generator/builtin.md

@@ -18,10 +18,10 @@ Generates Kysely type definitions and the `getDB()` function for type-safe datab
 
 ### Prerequisites
 
-Install the required runtime dependencies:
+Install the required dev dependency for type definitions:
 
 ```bash
-pnpm add -D @tailor-platform/function-kysely-tailordb @tailor-platform/function-types
+pnpm add -D @tailor-platform/function-types
 ```
 
 ### Output

package/docs/plugin/custom.md

@@ -0,0 +1,389 @@
+# 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 `PluginBase` interface.
+
+## PluginBase Interface
+
+```typescript
+interface PluginBase<PluginConfig = unknown> {
+  /** Unique identifier for the plugin (e.g., "@my-company/soft-delete") */
+  readonly id: string;
+
+  /** Human-readable description */
+  readonly description: string;
+
+  /** Import path for generated code to reference */
+  readonly importPath: string;
+
+  /** Schema for per-type configuration via .plugin() (required when using process) */
+  readonly configSchema?: TailorAnyField;
+
+  /** Schema for plugin-level configuration via definePlugins() (optional) */
+  readonly pluginConfigSchema?: TailorAnyField;
+
+  /** Controls whether per-type config is required when attaching via .plugin() */
+  readonly typeConfigRequired?: boolean | ((pluginConfig?: PluginConfig) => boolean);
+
+  /** Plugin-level config passed via definePlugins() */
+  readonly pluginConfig?: PluginConfig;
+
+  /** Optional template for generating PluginConfigs typing */
+  readonly configTypeTemplate?: string;
+
+  /** Process a type with this plugin attached */
+  process?(context: PluginProcessContext): PluginOutput | Promise<PluginOutput>;
+
+  /** Process a namespace (plugins without a source type) */
+  processNamespace?(
+    context: PluginNamespaceProcessContext,
+  ): NamespacePluginOutput | Promise<NamespacePluginOutput>;
+}
+```
+
+Notes:
+
+- `importPath` should be resolvable from the directory containing `tailor.config.ts`. Code generators use it to import plugin APIs such as `getGeneratedType` and executor modules.
+- If you want to attach a plugin via `.plugin()`, you must provide `configSchema` and `process`.
+- Namespace-only plugins can omit `configSchema` and implement `processNamespace` instead.
+- `pluginConfig` stores the plugin-level config so it can be read later during processing. If you prefer not to set it manually, you can pass config as a tuple to `definePlugins([plugin, config])`.
+- For custom plugins, `pluginConfig` is the expected pattern. The tuple form can also be used to pass config.
+- `resolve` should return a dynamic import; relative specifiers are resolved from the plugin module.
+- Per-type config is optional by default. Use `typeConfigRequired: true` to make it mandatory.
+- To toggle optional/required based on plugin config, provide a function for `typeConfigRequired`.
+
+## PluginProcessContext
+
+Context passed to the `process` method:
+
+```typescript
+interface PluginProcessContext<Config = unknown, PluginConfig = unknown> {
+  /** The TailorDB type being processed */
+  type: TailorAnyDBType;
+
+  /** Per-type configuration from .plugin({ pluginId: config }) */
+  config: Config;
+
+  /** Plugin-level configuration from definePlugins() */
+  pluginConfig: PluginConfig;
+
+  /** Namespace of the TailorDB type */
+  namespace: string;
+}
+```
+
+## PluginNamespaceProcessContext
+
+Context passed to the `processNamespace` method:
+
+```typescript
+interface PluginNamespaceProcessContext<Config = unknown> {
+  /** Plugin-level configuration from definePlugins() */
+  pluginConfig: Config;
+
+  /** Namespace of the TailorDB types */
+  namespace: string;
+
+  /** TailorDB types in the namespace (after type-attached processing) */
+  types: TailorAnyDBType[];
+
+  /** Plugin-generated types for type-attached plugins in the namespace */
+  generatedTypes: Array<{
+    type: TailorAnyDBType;
+    pluginId: string;
+    generatedTypeKind?: string;
+    originalType: TailorAnyDBType;
+  }>;
+}
+```
+
+`generatedTypes` includes only type-attached plugin-generated types (so `originalType` is always present), and `types` contains only user-defined types.
+For example:
+
+```typescript
+const changeRequestTypes = context.generatedTypes.filter(
+  (entry) => entry.pluginId === "@example/change-request",
+);
+```
+
+## PluginOutput
+
+Return value from `process`:
+
+```typescript
+interface PluginOutput {
+  /** Additional TailorDB types to generate */
+  types?: Record<string, TailorAnyDBType>;
+
+  /** Additional resolvers to generate */
+  resolvers?: PluginGeneratedResolver[];
+
+  /** Additional executors to generate */
+  executors?: PluginGeneratedExecutor[];
+
+  /** Extensions to apply to the source type */
+  extends?: {
+    /** Fields to add to the source type */
+    fields?: Record<string, TailorAnyField>;
+  };
+}
+```
+
+`processNamespace` returns `NamespacePluginOutput` (same shape as `PluginOutput` but without `extends`):
+
+```typescript
+type NamespacePluginOutput = Omit<PluginOutput, "extends">;
+```
+
+## Example: Soft Delete Plugin
+
+A complete example of a plugin that adds soft delete functionality:
+
+### Plugin Definition
+
+```typescript
+// plugins/soft-delete/plugin.ts
+import { db, t } from "@tailor-platform/sdk";
+import type { PluginBase, PluginProcessContext, PluginOutput } from "@tailor-platform/sdk";
+
+interface SoftDeleteConfig {
+  archiveReason?: boolean;
+  retentionDays?: number;
+}
+
+interface SoftDeletePluginConfig {
+  archiveTablePrefix?: string;
+  defaultRetentionDays?: number;
+  requireTypeConfig?: boolean;
+}
+
+const configSchema = t.object({
+  archiveReason: t.bool({ optional: true }),
+  retentionDays: t.int({ optional: true }),
+  // Use { required: true } to mark fields as required in plugin configs.
+  // By default, plugin config fields are optional.
+  // token: t.string({ required: true }),
+});
+
+const pluginConfigSchema = t.object({
+  archiveTablePrefix: t.string({ optional: true }),
+  defaultRetentionDays: t.int({ optional: true }),
+});
+
+function processSoftDelete(
+  context: PluginProcessContext<SoftDeleteConfig, SoftDeletePluginConfig>,
+): PluginOutput {
+  const { type, config, pluginConfig, namespace } = context;
+  const prefix = pluginConfig?.archiveTablePrefix ?? "Deleted_";
+
+  // Generate archive type
+  const archiveType = db
+    .type(`${prefix}${type.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"),
+      ...(config.archiveReason && {
+        reason: db.string({ optional: true }).description("Reason for deletion"),
+      }),
+      ...db.fields.timestamps(),
+    })
+    .description(`Archive for deleted ${type.name} records`);
+
+  // Extend source type with deletedAt field
+  const extendFields = {
+    deletedAt: db.datetime({ optional: true }).description("Soft delete timestamp"),
+  };
+
+  return {
+    types: { archive: archiveType },
+    extends: { fields: extendFields },
+    executors: [
+      {
+        name: `${type.name.toLowerCase()}-on-delete`,
+        resolve: async () => await import("./executors/on-delete"),
+        context: {
+          sourceType: type,
+          archiveType,
+          namespace,
+        },
+      },
+    ],
+  };
+}
+
+// Factory function for plugins with namespace config
+export function softDeletePlugin(pluginConfig?: SoftDeletePluginConfig): PluginBase {
+  return {
+    id: "@example/soft-delete",
+    description: "Adds soft delete with archive functionality",
+    importPath: "./plugins/soft-delete",
+    configSchema,
+    pluginConfigSchema,
+    pluginConfig,
+    typeConfigRequired: (config) => config?.requireTypeConfig === true,
+    process: processSoftDelete,
+  };
+}
+```
+
+### Executor with Context
+
+```typescript
+// plugins/soft-delete/executors/on-delete.ts
+import { createExecutor, recordDeletedTrigger, withPluginContext } from "@tailor-platform/sdk";
+import type { TailorAnyDBType } from "@tailor-platform/sdk";
+import { getDB } from "generated/tailordb";
+
+interface SoftDeleteContext {
+  sourceType: TailorAnyDBType;
+  archiveType: TailorAnyDBType;
+  namespace: string;
+}
+
+export default withPluginContext((ctx: SoftDeleteContext) => {
+  const { sourceType, archiveType, namespace } = ctx;
+
+  return createExecutor({
+    name: `${sourceType.name.toLowerCase()}-on-delete`,
+    description: `Archives deleted ${sourceType.name} records`,
+    trigger: recordDeletedTrigger({ type: sourceType }),
+    operation: {
+      kind: "function",
+      body: async ({ oldRecord, user }) => {
+        const db = getDB(namespace as "tailordb");
+        await db
+          .insertInto(archiveType.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
+  .type("Customer", {
+    name: db.string(),
+    email: db.string(),
+  })
+  .plugin({
+    "@example/soft-delete": {
+      archiveReason: true,
+    },
+  });
+```
+
+If your plugin uses `typeConfigRequired` as a function, you can toggle whether per-type config
+is required via `pluginConfig`:
+
+```typescript
+export const plugins = definePlugins(
+  softDeletePlugin({
+    archiveTablePrefix: "Deleted_",
+    requireTypeConfig: true,
+  }),
+);
+```
+
+## Adding Type Safety
+
+To enable type checking for your plugin's configuration, add a declaration merge:
+
+```typescript
+// user-defined.d.ts or your plugin's types.ts
+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 type being configured, enabling field-aware configurations:
+
+```typescript
+declare module "@tailor-platform/sdk" {
+  interface PluginConfigs<Fields extends string> {
+    "@example/i18n": {
+      labels: Partial<Record<Fields, { ja: string; en: string }>>;
+    };
+  }
+}
+```
+
+## Plugin Types
+
+### Type-Attached Plugins
+
+Implement `process` to handle types with the plugin attached:
+
+```typescript
+const plugin: PluginBase = {
+  id: "@example/my-plugin",
+  // ...
+  process(context) {
+    // Called for each type with .plugin({ "@example/my-plugin": config })
+    return {
+      types: {
+        /* generated types */
+      },
+    };
+  },
+};
+```
+
+### Namespace Plugins
+
+Implement `processNamespace` for plugins that generate types independently:
+
+```typescript
+const plugin: PluginBase = {
+  id: "@example/audit-log",
+  // ...
+  processNamespace(context) {
+    // Called once per namespace, with namespace-level types available
+    return { types: { auditLog: /* generated type */ } };
+  },
+};
+```
+
+### Hybrid Plugins
+
+Implement both methods for plugins that support both modes:
+
+```typescript
+const plugin: PluginBase = {
+  id: "@example/hybrid",
+  // ...
+  process(context) {
+    // Handle type attachments
+  },
+  processNamespace(context) {
+    // Handle namespace generation
+  },
+};
+```

package/docs/plugin/index.md

@@ -0,0 +1,112 @@
+# Plugins (Beta)
+
+> **Beta Feature**: The plugin system is currently in beta. APIs may change in future releases.
+
+Plugins extend TailorDB types by automatically generating additional types and executors based on your type definitions.
+
+## Overview
+
+When you run `tailor-sdk generate`, the SDK:
+
+1. Loads all TailorDB types with plugin attachments
+2. Passes each type to the attached plugins
+3. Generates additional types 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 Types
+
+Use the `.plugin()` method to attach plugins to specific types:
+
+```typescript
+import { db } from "@tailor-platform/sdk";
+
+export const user = db
+  .type("User", {
+    name: db.string(),
+    email: db.string(),
+  })
+  .plugin({
+    "@example/my-plugin": {},
+  });
+```
+
+### Plugin Configuration
+
+Some plugins accept per-type configuration:
+
+```typescript
+export const customer = db
+  .type("Customer", {
+    name: db.string(),
+    // ...
+  })
+  .plugin({
+    "@example/soft-delete": {
+      archiveReason: true,
+      retentionDays: 90,
+    },
+  });
+```
+
+### Per-type Config Requirement
+
+Per-type config is optional by default. Plugin authors can change this with
+`typeConfigRequired` (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:
+
+- **Types**: Additional TailorDB types (e.g., `CustomerHistory`, `Deleted_Customer`)
+- **Executors**: Event handlers triggered by record changes
+- **Field Extensions**: Additional fields added to the source type
+
+Generated files are placed under `.tailor-sdk/<plugin-id>/` (the plugin ID is sanitized,
+e.g. `@example/soft-delete` → `example-soft-delete`), such as:
+
+- `.tailor-sdk/example-soft-delete/types`
+- `.tailor-sdk/example-soft-delete/executors`
+
+## Creating Custom Plugins
+
+See [Custom Plugins](./custom.md) for how to create your own plugins.

package/docs/services/workflow.md

@@ -56,6 +56,34 @@ export const fetchCustomer = createWorkflowJob({
 });
 ```
 
+## 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 — only primitives (`string`, `number`, `boolean`, `null`), arrays, and plain objects are allowed. `Date`, `Map`, `Set`, functions, and other non-serializable types cannot be used.
+
+```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 }) => {
+    // ...
+  },
+});
+```
+
+**Output types** are more permissive — `Date` and objects with `toJSON()` are allowed because they are serialized via `JSON.stringify` at runtime (e.g., `Date` becomes a string).
+
+These constraints are enforced at compile time — you will get a type error if you use an unsupported type.
+
 ## Triggering Jobs
 
 Use `.trigger()` to start other jobs from within a job.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailor-platform/sdk",
-  "version": "1.11.0",
+  "version": "1.12.0",
   "description": "Tailor Platform SDK - The SDK to work with Tailor Platform",
   "license": "MIT",
   "repository": {
@@ -36,6 +36,16 @@
       "types": "./dist/utils/test/index.d.mts",
       "import": "./dist/utils/test/index.mjs",
       "default": "./dist/utils/test/index.mjs"
+    },
+    "./kysely": {
+      "types": "./dist/kysely/index.d.mts",
+      "import": "./dist/kysely/index.mjs",
+      "default": "./dist/kysely/index.mjs"
+    },
+    "./plugin": {
+      "types": "./dist/plugin/index.d.mts",
+      "import": "./dist/plugin/index.mjs",
+      "default": "./dist/plugin/index.mjs"
     }
   },
   "dependencies": {
@@ -43,16 +53,20 @@
     "@bufbuild/protobuf": "2.10.2",
     "@connectrpc/connect": "2.1.1",
     "@connectrpc/connect-node": "2.1.1",
+    "@liam-hq/cli": "0.7.24",
     "@oxc-project/types": "0.108.0",
     "@standard-schema/spec": "1.1.0",
+    "@tailor-platform/function-kysely-tailordb": "0.1.3",
     "@urql/core": "6.0.1",
     "chalk": "5.6.2",
     "chokidar": "5.0.0",
     "confbox": "0.2.2",
     "consola": "3.4.2",
     "date-fns": "4.1.0",
+    "es-toolkit": "^1.44.0",
     "find-up-simple": "1.0.1",
     "inflection": "3.0.2",
+    "kysely": "0.28.10",
     "madge": "8.0.0",
     "mime-types": "3.0.2",
     "multiline-ts": "4.0.1",
@@ -64,6 +78,7 @@
     "pkg-types": "2.3.0",
     "politty": "^0.1.1",
     "rolldown": "1.0.0-beta.60",
+    "serve": "14.2.5",
     "std-env": "3.10.0",
     "table": "6.9.0",
     "ts-cron-validator": "1.1.5",
@@ -74,7 +89,6 @@
   },
   "devDependencies": {
     "@eslint/js": "9.39.2",
-    "@tailor-platform/function-kysely-tailordb": "0.1.3",
     "@tailor-platform/function-types": "0.8.0",
     "@toiroakr/lines-db": "0.6.1",
     "@types/madge": "5.0.3",
@@ -87,7 +101,6 @@
     "eslint-plugin-jsdoc": "62.1.0",
     "eslint-plugin-oxlint": "1.39.0",
     "globals": "17.0.0",
-    "kysely": "0.28.2",
     "oxlint": "1.39.0",
     "oxlint-tsgolint": "0.11.1",
     "sonda": "0.10.1",
@@ -96,26 +109,6 @@
     "typescript-eslint": "8.53.0",
     "vitest": "4.0.17"
   },
-  "peerDependencies": {
-    "@liam-hq/cli": "*",
-    "@tailor-platform/function-kysely-tailordb": "*",
-    "kysely": "*",
-    "serve": "*"
-  },
-  "peerDependenciesMeta": {
-    "@liam-hq/cli": {
-      "optional": true
-    },
-    "@tailor-platform/function-kysely-tailordb": {
-      "optional": true
-    },
-    "kysely": {
-      "optional": true
-    },
-    "serve": {
-      "optional": true
-    }
-  },
   "scripts": {
     "test": "vitest",
     "test:unit": "vitest --project=unit",