@tailor-platform/sdk 0.16.3 → 0.18.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
@@ -51,9 +62,35 @@ export default defineConfig({
 
 **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.
 
+### 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
+
 ### 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 +105,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 +119,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 +127,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 +143,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 +172,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 +196,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