@tailor-platform/sdk 0.16.3 → 0.17.0

package/docs/configuration.md

@@ -2,6 +2,17 @@
 
 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.md) - Database schema definition
+- [Resolver](./services/resolver.md) - Custom GraphQL resolvers
+- [Executor](./services/executor.md) - Event-driven handlers
+- [Workflow](./services/workflow.md) - Job orchestration
+- [Auth](./services/auth.md) - Authentication and authorization
+- [IdP](./services/idp.md) - Built-in identity provider
+- [Static Website](./services/staticwebsite.md) - Static file hosting
+- [Secret Manager](./services/secret.md) - Secure credential storage
+
 ### Application Settings
 
 ```typescript
@@ -53,7 +64,7 @@ export default defineConfig({
 
 ### Built-in IdP
 
-Configure the Built-in IdP service using `defineIdp()`. The returned IdP object provides type-safe provider references via `idp.provider()` that can be used in Auth service configuration.
+Configure the Built-in IdP service using `defineIdp()`. See [IdP](./services/idp.md) for full documentation.
 
 ```typescript
 import { defineIdp } from "@tailor-platform/sdk";
@@ -68,13 +79,9 @@ export default defineConfig({
 });
 ```
 
-**authorization**: User management permissions (`"insecure"`, `"loggedIn"`, or CEL expression).
-
-**clients**: OAuth client names for the IdP.
-
 ### Auth Service
 
-Configure Auth service using `defineAuth()`:
+Configure Auth service using `defineAuth()`. See [Auth](./services/auth.md) for full documentation.
 
 ```typescript
 import { defineAuth } from "@tailor-platform/sdk";
@@ -86,17 +93,6 @@ const auth = defineAuth("my-auth", {
     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"),
 });
 
@@ -105,24 +101,15 @@ export default defineConfig({
 });
 ```
 
-**userProfile**: Maps identities to TailorDB type with username field and attributes.
-
-**machineUsers**: Service accounts with predefined attributes.
-
-**oauth2Clients**: OAuth 2.0 clients with redirect URIs and grant types.
-
-**idProvider**: External identity provider (OIDC, SAML, IDToken, or BuiltInIdP).
-
 ### Static Websites
 
-Configure static website hosting using `defineStaticWebSite()`. The returned website object provides a type-safe `url` property that can be used in CORS settings and OAuth2 redirect URIs.
+Configure static website hosting using `defineStaticWebSite()`. See [Static Website](./services/staticwebsite.md) for full documentation.
 
 ```typescript
 import { defineStaticWebSite } from "@tailor-platform/sdk";
 
 const website = defineStaticWebSite("my-website", {
   description: "My Static Website",
-  allowedIPAddresses: ["192.168.0.0/24"],
 });
 
 export default defineConfig({
@@ -130,13 +117,9 @@ export default defineConfig({
 });
 ```
 
-**description**: Description of the site.
-
-**allowedIPAddresses**: List of IP addresses allowed to access the site in CIDR format.
-
 ### Environment Variables
 
-Define environment variables that can be accessed in resolvers and executors:
+Define environment variables that can be accessed in resolvers, executors, and workflows:
 
 ```typescript
 export default defineConfig({
@@ -163,6 +146,12 @@ body: ({ input, env }) => {
 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 };
+};
 ```
 
 ### Workflow Service
@@ -181,3 +170,18 @@ export default defineConfig({
 **files**: Glob patterns to match workflow files. Required.
 
 **ignores**: Glob patterns to exclude files. Optional.
+
+### Generators
+
+Configure code generators using `defineGenerators()`. Generators must be exported as a named export.
+
+```typescript
+import { defineGenerators } from "@tailor-platform/sdk";
+
+export const generators = defineGenerators(
+  ["@tailor-platform/kysely-type", { distPath: "./generated/tailordb.ts" }],
+  ["@tailor-platform/enum-constants", { distPath: "./generated/enums.ts" }],
+);
+```
+
+See [Generators](./generator/index.md) for full documentation.

package/docs/generator/builtin.md

@@ -0,0 +1,194 @@
+# Builtin Generators
+
+The SDK includes four builtin generators for common code generation tasks.
+
+## @tailor-platform/kysely-type
+
+Generates Kysely type definitions and the `getDB()` function for type-safe database access.
+
+### Configuration
+
+```typescript
+["@tailor-platform/kysely-type", { distPath: "./generated/tailordb.ts" }];
+```
+
+| Option     | Type     | Description                 |
+| ---------- | -------- | --------------------------- |
+| `distPath` | `string` | Output file path (required) |
+
+### Prerequisites
+
+Install the required runtime dependencies:
+
+```bash
+pnpm add -D @tailor-platform/function-kysely-tailordb @tailor-platform/function-types
+```
+
+### Output
+
+Generates a TypeScript file containing:
+
+- Type definitions for all TailorDB types
+- `getDB(namespace)` function to create Kysely instances
+- Utility types for Timestamp and Serial fields
+
+### Usage
+
+```typescript
+import { getDB } from "./generated/tailordb";
+
+// In resolvers
+body: async (context) => {
+  const db = getDB("tailordb");
+  const users = await db
+    .selectFrom("User")
+    .selectAll()
+    .where("email", "=", context.input.email)
+    .execute();
+  return { users };
+};
+
+// In executors
+body: async ({ newRecord }) => {
+  const db = getDB("tailordb");
+  await db
+    .insertInto("AuditLog")
+    .values({ userId: newRecord.id, action: "created" })
+    .execute();
+};
+
+// In workflow jobs
+body: async (input, { env }) => {
+  const db = getDB("tailordb");
+  return await db
+    .selectFrom("Order")
+    .selectAll()
+    .where("id", "=", input.orderId)
+    .executeTakeFirst();
+};
+```
+
+## @tailor-platform/enum-constants
+
+Extracts enum constants from TailorDB type definitions.
+
+### Configuration
+
+```typescript
+["@tailor-platform/enum-constants", { distPath: "./generated/enums.ts" }];
+```
+
+| Option     | Type     | Description                 |
+| ---------- | -------- | --------------------------- |
+| `distPath` | `string` | Output file path (required) |
+
+### Output
+
+Generates TypeScript constants for all enum fields:
+
+```typescript
+// Generated output
+export const OrderStatus = {
+  PENDING: "PENDING",
+  PROCESSING: "PROCESSING",
+  COMPLETED: "COMPLETED",
+  CANCELLED: "CANCELLED",
+} as const;
+
+export type OrderStatus = (typeof OrderStatus)[keyof typeof OrderStatus];
+```
+
+### Usage
+
+```typescript
+import { OrderStatus } from "./generated/enums";
+
+// Type-safe enum usage
+const status: OrderStatus = OrderStatus.PENDING;
+
+// In queries
+const orders = await db
+  .selectFrom("Order")
+  .selectAll()
+  .where("status", "=", OrderStatus.COMPLETED)
+  .execute();
+```
+
+## @tailor-platform/file-utils
+
+Generates utility functions for handling file-type fields in TailorDB.
+
+### Configuration
+
+```typescript
+["@tailor-platform/file-utils", { distPath: "./generated/files.ts" }];
+```
+
+| Option     | Type     | Description                 |
+| ---------- | -------- | --------------------------- |
+| `distPath` | `string` | Output file path (required) |
+
+### Output
+
+Generates TypeScript interfaces and utilities for types with file fields:
+
+```typescript
+// Generated output
+export interface UserFileFields {
+  avatar: string;
+  documents: string;
+}
+
+export function getUserFileFields(): (keyof UserFileFields)[] {
+  return ["avatar", "documents"];
+}
+```
+
+## @tailor-platform/seed
+
+Generates seed data configuration files for database initialization.
+
+### Configuration
+
+```typescript
+["@tailor-platform/seed", { distPath: "./seed" }][
+  // With executable script
+  ("@tailor-platform/seed", { distPath: "./seed", machineUserName: "admin" })
+];
+```
+
+| Option            | Type     | Description                                        |
+| ----------------- | -------- | -------------------------------------------------- |
+| `distPath`        | `string` | Output directory path (required)                   |
+| `machineUserName` | `string` | Machine user name for executable script (optional) |
+
+### Output
+
+Generates a seed directory structure:
+
+```
+seed/
+├── config.yaml           # Entity dependencies configuration
+├── data/
+│   ├── User.jsonl        # Seed data files (JSONL format)
+│   └── Product.jsonl
+├── graphql/
+│   ├── User.graphql      # GraphQL mutation files
+│   └── Product.graphql
+├── mapping/
+│   ├── User.yaml         # GraphQL Ingest mapping files
+│   └── Product.yaml
+├── schema.ts             # lines-db schema definitions
+└── exec.mjs              # Executable script (if machineUserName provided)
+```
+
+### Usage
+
+If `machineUserName` is provided, an executable script is generated:
+
+```bash
+# Run seed data import
+node seed/exec.mjs
+```
+
+The generated files are compatible with gql-ingest for bulk data import.

package/docs/generator/custom.md

@@ -0,0 +1,150 @@
+# Custom Generators (Preview)
+
+> **Preview Feature**: The custom generator API is in preview and may change in future releases.
+
+Create your own generators by implementing the `CodeGenerator` interface.
+
+## CodeGenerator Interface
+
+```typescript
+interface CodeGenerator<T, R, E, Ts, Rs> {
+  id: string;
+  description: string;
+
+  // Process individual items
+  processType(args: {
+    type: ParsedTailorDBType;
+    namespace: string;
+    source: { filePath: string; exportName: string };
+  }): T | Promise<T>;
+
+  processResolver(args: {
+    resolver: Resolver;
+    namespace: string;
+  }): R | Promise<R>;
+
+  processExecutor(executor: Executor): E | Promise<E>;
+
+  // Aggregate per namespace (optional)
+  processTailorDBNamespace?(args: {
+    namespace: string;
+    types: Record<string, T>;
+  }): Ts | Promise<Ts>;
+
+  processResolverNamespace?(args: {
+    namespace: string;
+    resolvers: Record<string, R>;
+  }): Rs | Promise<Rs>;
+
+  // Final aggregation
+  aggregate(args: {
+    input: GeneratorInput<Ts, Rs>;
+    executorInputs: E[];
+    baseDir: string;
+  }): GeneratorResult | Promise<GeneratorResult>;
+}
+```
+
+## GeneratorResult
+
+Generators return a `GeneratorResult` containing files to create:
+
+```typescript
+interface GeneratorResult {
+  files: Array<{
+    path: string; // Relative path from project root
+    content: string; // File content
+    skipIfExists?: boolean; // Skip if file already exists (default: false)
+    executable?: boolean; // Make file executable (default: false)
+  }>;
+  errors?: string[];
+}
+```
+
+## Example: Simple Type List Generator
+
+```typescript
+import type { CodeGenerator, GeneratorResult } from "@tailor-platform/sdk";
+
+const typeListGenerator: CodeGenerator<string, null, null, string[], null> = {
+  id: "type-list",
+  description: "Generates a list of all TailorDB type names",
+
+  processType({ type }) {
+    return type.name;
+  },
+
+  processResolver() {
+    return null;
+  },
+
+  processExecutor() {
+    return null;
+  },
+
+  processTailorDBNamespace({ types }) {
+    return Object.values(types);
+  },
+
+  aggregate({ input }) {
+    const allTypes = input.tailordb.flatMap((ns) => ns.types);
+    const content = `// Generated type list\nexport const types = ${JSON.stringify(allTypes, null, 2)} as const;\n`;
+
+    return {
+      files: [{ path: "generated/types.ts", content }],
+    };
+  },
+};
+```
+
+## Using Custom Generators
+
+Pass the generator object directly to `defineGenerators()`:
+
+```typescript
+import { defineGenerators } from "@tailor-platform/sdk";
+import { typeListGenerator } from "./generators/type-list";
+
+export const generators = defineGenerators(
+  ["@tailor-platform/kysely-type", { distPath: "./generated/tailordb.ts" }],
+  typeListGenerator, // Custom generator
+);
+```
+
+## Available Input Data
+
+### ParsedTailorDBType
+
+Contains full type information including:
+
+- `name`: Type name
+- `fields`: Field definitions with types, validation, and descriptions
+- `relations`: Relationship definitions
+- `indexes`: Index configurations
+- `permission`: Permission rules
+
+### Resolver
+
+Contains resolver configuration:
+
+- `name`: Resolver name
+- `operation`: Query or mutation
+- `input`: Input schema
+- `output`: Output schema
+
+### Executor
+
+Contains executor configuration:
+
+- `name`: Executor name
+- `trigger`: Trigger configuration
+- `operation`: Execution target
+
+### GeneratorAuthInput
+
+Contains authentication configuration when available:
+
+- `name`: Auth service name
+- `userProfile`: User profile type information
+- `machineUsers`: Machine user definitions
+- `oauth2Clients`: OAuth2 client configurations

package/docs/generator/index.md

@@ -0,0 +1,56 @@
+# Generators
+
+Generators analyze your TailorDB types, Resolvers, and Executors to automatically generate TypeScript code.
+
+## Overview
+
+When you run `tailor-sdk generate`, the SDK:
+
+1. Loads all TailorDB types, Resolvers, and Executors from your configuration
+2. Passes each definition to the configured generators
+3. Aggregates the results and writes output files
+
+This enables generators to create derived code based on your application's schema. For example, the `@tailor-platform/kysely-type` generator produces type-safe database access code from your TailorDB definitions.
+
+## Configuration
+
+Define generators in `tailor.config.ts` using `defineGenerators()`:
+
+```typescript
+import { defineConfig, defineGenerators } from "@tailor-platform/sdk";
+
+export const generators = defineGenerators(
+  ["@tailor-platform/kysely-type", { distPath: "./generated/tailordb.ts" }],
+  ["@tailor-platform/enum-constants", { distPath: "./generated/enums.ts" }],
+);
+
+export default defineConfig({
+  name: "my-app",
+  // ...
+});
+```
+
+**Important**: The `generators` export must be a named export (not default).
+
+## CLI Commands
+
+### Generate Files
+
+```bash
+tailor-sdk generate
+```
+
+Generates all configured output files.
+
+### Watch Mode
+
+```bash
+tailor-sdk generate --watch
+```
+
+Watches for file changes and regenerates automatically.
+
+## Generator Types
+
+- [Builtin Generators](./builtin.md) - Ready-to-use generators included with the SDK
+- [Custom Generators](./custom.md) - Create your own generators (Preview)

package/docs/quickstart.md

@@ -1,6 +1,4 @@
-# Tailor Platform SDK
-
-Development kit for building type-safe applications on the Tailor Platform using TypeScript.
+# Quickstart
 
 ## Getting Started
 
@@ -49,7 +47,7 @@ You can now open the GraphQL Playground and execute the `hello` query:
 
 ```graphql
 query {
-  hello(input: { name: "sdk" }) {
+  hello(name: "sdk") {
     message
   }
 }
@@ -94,3 +92,10 @@ export default createResolver({
 ```
 
 Deploy again to see the response.
+
+## Next Steps
+
+- Learn about [TailorDB](./services/tailordb.md) for database schema definition
+- Create custom [Resolvers](./services/resolver.md) with business logic
+- Set up [Executors](./services/executor.md) for event-driven automation
+- Explore [Templates](https://github.com/tailor-platform/sdk/tree/main/packages/create-sdk#available-templates) for more examples