@tailor-platform/sdk 1.14.1 → 1.15.0

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

@@ -1,10 +1,10 @@
 /// <reference path="./../../user-defined.d.ts" />
-import { Ft as TailorField, rt as TailorDBType } from "../../index-Bid18Opo.mjs";
-import { G as WORKFLOW_TEST_ENV_KEY, n as output } from "../../index-BlUBAAvu.mjs";
+import { M as TailorDBType, st as TailorField } from "../../types-Db1oxr0U.mjs";
+import "../../index-DomkP6gz.mjs";
+import { G as WORKFLOW_TEST_ENV_KEY, n as output } from "../../index-Bs9AsQb2.mjs";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 
 //#region src/utils/test/index.d.ts
-
 /** Represents an unauthenticated user in the Tailor platform. */
 declare const unauthenticatedTailorUser: {
   readonly id: "00000000-0000-0000-0000-000000000000";

package/dist/utils/test/index.mjs

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

package/docs/plugin/custom.md

@@ -2,12 +2,28 @@
 
 > **Beta Feature**: The custom plugin API is in beta and may change in future releases.
 
-Create your own plugins by implementing the `PluginBase` interface.
+Create your own plugins by implementing the `Plugin` interface.
 
-## PluginBase Interface
+## Requirements
+
+**Plugins must use default export**:
 
 ```typescript
-interface PluginBase<PluginConfig = unknown> {
+// plugin.ts
+const myPlugin: Plugin = {
+  id: "@my-company/my-plugin",
+  // ...
+};
+
+export default myPlugin; // Required: must be default export
+```
+
+This is required so that generators can use plugin-generated TailorDB types via `getGeneratedType()`.
+
+## Plugin Interface
+
+```typescript
+interface Plugin<TypeConfig = unknown, PluginConfig = unknown> {
   /** Unique identifier for the plugin (e.g., "@my-company/soft-delete") */
   readonly id: string;
 
@@ -17,53 +33,46 @@ interface PluginBase<PluginConfig = unknown> {
   /** 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>;
+  processType?(
+    context: PluginProcessContext<TypeConfig, PluginConfig>,
+  ): TypePluginOutput | Promise<TypePluginOutput>;
 
   /** Process a namespace (plugins without a source type) */
   processNamespace?(
-    context: PluginNamespaceProcessContext,
-  ): NamespacePluginOutput | Promise<NamespacePluginOutput>;
+    context: PluginNamespaceProcessContext<PluginConfig>,
+  ): PluginOutput | Promise<PluginOutput>;
 }
 ```
 
 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.
+- If you want to attach a plugin via `.plugin()`, implement the `processType` method.
+- Namespace-only plugins implement `processNamespace` instead.
+- `pluginConfig` stores the plugin-level config so it can be read later during processing. Set it on the plugin object (e.g., via a factory function) before passing to `definePlugins()`.
 - `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`.
+- Use TypeScript type parameters (`TypeConfig`, `PluginConfig`) to get type-safe config in your `processType` and `processNamespace` methods.
 
 ## PluginProcessContext
 
-Context passed to the `process` method:
+Context passed to the `processType` method:
 
 ```typescript
-interface PluginProcessContext<Config = unknown, PluginConfig = unknown> {
+interface PluginProcessContext<TypeConfig = unknown, PluginConfig = unknown> {
   /** The TailorDB type being processed */
   type: TailorAnyDBType;
 
-  /** Per-type configuration from .plugin({ pluginId: config }) */
-  config: Config;
+  /** Per-type configuration from .plugin({ pluginId: typeConfig }) */
+  typeConfig: TypeConfig;
 
   /** Plugin-level configuration from definePlugins() */
   pluginConfig: PluginConfig;
@@ -78,38 +87,20 @@ interface PluginProcessContext<Config = unknown, PluginConfig = unknown> {
 Context passed to the `processNamespace` method:
 
 ```typescript
-interface PluginNamespaceProcessContext<Config = unknown> {
+interface PluginNamespaceProcessContext<PluginConfig = unknown> {
   /** Plugin-level configuration from definePlugins() */
-  pluginConfig: Config;
+  pluginConfig: PluginConfig;
 
-  /** Namespace of the TailorDB types */
+  /** Target namespace for generated 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:
+## Output Types
 
-```typescript
-const changeRequestTypes = context.generatedTypes.filter(
-  (entry) => entry.pluginId === "@example/change-request",
-);
-```
-
-## PluginOutput
+### PluginOutput (base)
 
-Return value from `process`:
+Base output used by both `processType` and `processNamespace`:
 
 ```typescript
 interface PluginOutput {
@@ -121,19 +112,80 @@ interface PluginOutput {
 
   /** Additional executors to generate */
   executors?: PluginGeneratedExecutor[];
+}
+```
+
+### TypePluginOutput
 
+Return value from `processType`. Extends `PluginOutput` with the ability to add fields to the source type:
+
+```typescript
+interface TypePluginOutput extends PluginOutput {
   /** Extensions to apply to the source type */
   extends?: {
     /** Fields to add to the source type */
-    fields?: Record<string, TailorAnyField>;
+    fields?: Record<string, TailorAnyDBField>;
   };
 }
 ```
 
-`processNamespace` returns `NamespacePluginOutput` (same shape as `PluginOutput` but without `extends`):
+`processNamespace` returns `PluginOutput` directly (namespace plugins cannot extend a source type).
+
+## getGeneratedType Helper
+
+The SDK provides an async `getGeneratedType()` helper function to retrieve plugin-generated TailorDB types. This enables generators and other tools to work with types generated by plugins.
+
+```typescript
+import { join } from "node:path";
+import { getGeneratedType } from "@tailor-platform/sdk/plugin";
+import { customer } from "./tailordb/customer";
+
+const configPath = join(import.meta.dirname, "./tailor.config.ts");
+
+// Get the generated type by config path, plugin ID, source type, and kind
+const DeletedCustomer = await getGeneratedType(
+  configPath,
+  "@example/soft-delete",
+  customer,
+  "archive",
+);
+```
+
+**Parameters:**
+
+- `configPath`: Path to `tailor.config.ts` (absolute or relative to cwd)
+- `pluginId`: The plugin's unique identifier (e.g., `"@example/soft-delete"`)
+- `sourceType`: The TailorDB type that the plugin is attached to (`null` for namespace plugins)
+- `kind`: The generated type 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 `processType()` or `processNamespace()` method
+5. Caches the result to avoid redundant processing
+6. Returns the generated type matching the specified kind
+
+### Example Usage
 
 ```typescript
-type NamespacePluginOutput = Omit<PluginOutput, "extends">;
+import { join } from "node:path";
+import { getGeneratedType } from "@tailor-platform/sdk/plugin";
+import { customer } from "./tailordb/customer";
+
+const configPath = join(import.meta.dirname, "./tailor.config.ts");
+
+// Type-attached plugin
+const DeletedCustomer = await getGeneratedType(
+  configPath,
+  "@example/soft-delete",
+  customer,
+  "archive",
+);
+
+// Namespace plugin (pass null as sourceType)
+const AuditLog = await getGeneratedType(configPath, "@example/audit-log", null, "auditLog");
 ```
 
 ## Example: Soft Delete Plugin
@@ -144,8 +196,8 @@ A complete example of a plugin that adds soft delete functionality:
 
 ```typescript
 // plugins/soft-delete/plugin.ts
-import { db, t } from "@tailor-platform/sdk";
-import type { PluginBase, PluginProcessContext, PluginOutput } from "@tailor-platform/sdk";
+import { db } from "@tailor-platform/sdk";
+import type { Plugin, PluginProcessContext, TypePluginOutput } from "@tailor-platform/sdk";
 
 interface SoftDeleteConfig {
   archiveReason?: boolean;
@@ -158,23 +210,10 @@ interface SoftDeletePluginConfig {
   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;
+): TypePluginOutput {
+  const { type, typeConfig, pluginConfig, namespace } = context;
   const prefix = pluginConfig?.archiveTablePrefix ?? "Deleted_";
 
   // Generate archive type
@@ -184,7 +223,7 @@ function processSoftDelete(
       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 && {
+      ...(typeConfig.archiveReason && {
         reason: db.string({ optional: true }).description("Reason for deletion"),
       }),
       ...db.fields.timestamps(),
@@ -213,27 +252,31 @@ function processSoftDelete(
   };
 }
 
-// Factory function for plugins with namespace config
-export function softDeletePlugin(pluginConfig?: SoftDeletePluginConfig): PluginBase {
+// Factory function for plugins with plugin-level config
+function createSoftDeletePlugin(
+  pluginConfig?: SoftDeletePluginConfig,
+): Plugin<SoftDeleteConfig, SoftDeletePluginConfig> {
   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,
+    processType: processSoftDelete,
   };
 }
+
+// Default export is required for getGeneratedType() to work
+export default createSoftDeletePlugin();
 ```
 
 ### Executor with Context
 
 ```typescript
 // plugins/soft-delete/executors/on-delete.ts
-import { createExecutor, recordDeletedTrigger, withPluginContext } from "@tailor-platform/sdk";
+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 {
@@ -273,8 +316,9 @@ export default withPluginContext((ctx: SoftDeleteContext) => {
 ```typescript
 // tailor.config.ts
 import { definePlugins } from "@tailor-platform/sdk";
-import { softDeletePlugin } from "./plugins/soft-delete";
+import softDeletePlugin from "./plugins/soft-delete";
 
+// Use a factory function to pass plugin-level config
 export const plugins = definePlugins(
   softDeletePlugin({
     archiveTablePrefix: "Deleted_",
@@ -309,10 +353,39 @@ export const plugins = definePlugins(
 
 ## Adding Type Safety
 
-To enable type checking for your plugin's configuration, add a declaration merge:
+Plugin type safety is provided at two levels:
+
+### Plugin-level type safety (TypeConfig / PluginConfig)
+
+Use TypeScript type parameters on `Plugin<TypeConfig, PluginConfig>` to get type-safe config
+in `processType` and `processNamespace` methods:
+
+```typescript
+interface MyTypeConfig {
+  archiveReason?: boolean;
+}
+
+interface MyPluginConfig {
+  prefix?: string;
+}
+
+const plugin: Plugin<MyTypeConfig, MyPluginConfig> = {
+  id: "@example/my-plugin",
+  // ...
+  processType(context) {
+    // context.typeConfig is MyTypeConfig
+    // context.pluginConfig is MyPluginConfig
+  },
+};
+```
+
+### Per-type `.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
-// user-defined.d.ts or your plugin's types.ts
+// your-plugin/types.d.ts (shipped with your plugin package)
 declare module "@tailor-platform/sdk" {
   interface PluginConfigs<Fields extends string> {
     "@example/soft-delete": {
@@ -339,13 +412,13 @@ declare module "@tailor-platform/sdk" {
 
 ### Type-Attached Plugins
 
-Implement `process` to handle types with the plugin attached:
+Implement `processType` to handle types with the plugin attached:
 
 ```typescript
-const plugin: PluginBase = {
+const plugin: Plugin = {
   id: "@example/my-plugin",
   // ...
-  process(context) {
+  processType(context) {
     // Called for each type with .plugin({ "@example/my-plugin": config })
     return {
       types: {
@@ -361,7 +434,7 @@ const plugin: PluginBase = {
 Implement `processNamespace` for plugins that generate types independently:
 
 ```typescript
-const plugin: PluginBase = {
+const plugin: Plugin = {
   id: "@example/audit-log",
   // ...
   processNamespace(context) {
@@ -376,10 +449,10 @@ const plugin: PluginBase = {
 Implement both methods for plugins that support both modes:
 
 ```typescript
-const plugin: PluginBase = {
+const plugin: Plugin = {
   id: "@example/hybrid",
   // ...
-  process(context) {
+  processType(context) {
     // Handle type attachments
   },
   processNamespace(context) {

package/docs/plugin/index.md

@@ -23,9 +23,9 @@ Define plugins in `tailor.config.ts` using `definePlugins()`:
 
 ```typescript
 import { defineConfig, definePlugins } from "@tailor-platform/sdk";
-import { myPlugin } from "./plugins/my-plugin";
+import myPlugin from "./plugins/my-plugin";
 
-export const plugins = definePlugins(myPlugin());
+export const plugins = definePlugins(myPlugin);
 
 export default defineConfig({
   name: "my-app",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailor-platform/sdk",
-  "version": "1.14.1",
+  "version": "1.15.0",
   "description": "Tailor Platform SDK - The SDK to work with Tailor Platform",
   "license": "MIT",
   "repository": {
@@ -9,14 +9,16 @@
     "directory": "packages/sdk"
   },
   "bin": {
-    "tailor-sdk": "./dist/cli/index.mjs"
+    "tailor-sdk": "./dist/cli/index.mjs",
+    "tailor-sdk-skills": "./dist/cli/skills.mjs"
   },
   "files": [
     "CHANGELOG.md",
     "dist",
     "docs",
     "postinstall.mjs",
-    "README.md"
+    "README.md",
+    "skills"
   ],
   "type": "module",
   "main": "./dist/configure/index.mjs",

package/skills/tailor-sdk/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: tailor-sdk
+description: Use this skill when working with @tailor-platform/sdk projects, including service configuration, CLI usage, and docs navigation.
+---
+
+# Tailor SDK Knowledge
+
+This skill helps with projects using `@tailor-platform/sdk`.
+
+## Primary Sources
+
+Use these files as the single source of truth:
+
+- `node_modules/@tailor-platform/sdk/README.md`
+- `node_modules/@tailor-platform/sdk/docs/configuration.md`
+- `node_modules/@tailor-platform/sdk/docs/services/*.md`
+- `node_modules/@tailor-platform/sdk/docs/cli-reference.md`
+- `node_modules/@tailor-platform/sdk/docs/cli/*.md`
+- `node_modules/@tailor-platform/sdk/docs/testing.md`
+
+## Working Rules
+
+1. Prefer SDK docs above assumptions. If behavior is unclear, cite the exact doc path used.
+2. Keep examples compatible with Node.js 22+.
+3. For CLI questions, verify command and option names from `docs/cli-reference.md` and `docs/cli/*.md`.
+4. For configuration questions, validate examples against `docs/configuration.md` and related service docs.
+
+## Quick Navigation
+
+- Setup and first deploy: `docs/quickstart.md`
+- Core config shape: `docs/configuration.md`
+- Service details: `docs/services/*.md`
+- CLI commands: `docs/cli-reference.md` and `docs/cli/*.md`
+- Testing patterns: `docs/testing.md`

package/dist/application-DM4zTgXU.mjs

@@ -1,4 +0,0 @@
-import "./chunk-C3Kl5s5P.mjs";
-import { t as defineApplication } from "./application-DnWZVbDO.mjs";
-
-export { defineApplication };