@tailor-platform/sdk 0.16.3 → 0.18.0

package/docs/services/auth.md

@@ -0,0 +1,244 @@
+# Auth
+
+Auth is a service for configuring authentication and authorization in your Tailor Platform application.
+
+## Overview
+
+Auth provides:
+
+- User profile mapping to TailorDB types
+- Machine users for service-to-service authentication
+- OAuth 2.0 client configuration
+- Identity provider integration
+
+For the official Tailor Platform documentation, see [Auth Guide](https://docs.tailor.tech/guides/auth/overview).
+
+## Configuration
+
+Configure Auth service using `defineAuth()`:
+
+```typescript
+import { defineAuth } from "@tailor-platform/sdk";
+import { user } from "./tailordb/user";
+
+const auth = defineAuth("my-auth", {
+  userProfile: {
+    type: user,
+    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"),
+});
+
+export default defineConfig({
+  auth,
+});
+```
+
+## User Profile
+
+Maps authenticated identities to a TailorDB type:
+
+```typescript
+userProfile: {
+  type: user,              // TailorDB type for user records
+  usernameField: "email",  // Field used as username (must be unique)
+  attributes: {
+    role: true,            // Enable 'role' as a user attribute
+  },
+},
+```
+
+Example TailorDB type for user profile:
+
+```typescript
+// tailordb/user.ts
+import { db } from "@tailor-platform/sdk";
+
+export const user = db.type("User", {
+  email: db.string().unique(), // usernameField must have unique constraint
+  role: db.enum(["admin", "user"]),
+  ...db.fields.timestamps(),
+});
+```
+
+**type**: The TailorDB type that stores user records.
+
+**usernameField**: The field in the TailorDB type used as the username. This field must have a unique constraint (`.unique()`) since it is used to uniquely identify users.
+
+**attributes**: Specifies which fields from the TailorDB type are used as user attributes. Set to `true` to enable a field. Enabled attributes must be assigned values in all machine user definitions.
+
+## Machine Users
+
+Service accounts for automated access without user interaction:
+
+```typescript
+machineUsers: {
+  "admin-machine-user": {
+    attributes: { role: "ADMIN" },
+  },
+  "readonly-machine-user": {
+    attributes: { role: "READER" },
+  },
+},
+```
+
+**attributes**: Values for attributes enabled in `userProfile.attributes`. All fields marked as `true` in `userProfile.attributes` must be set here. These values are accessible via `user.attributes`:
+
+```typescript
+// In a resolver
+body: (context) => {
+  const role = context.user.attributes?.role;
+},
+
+// In TailorDB hooks
+.hooks({
+  field: {
+    create: ({ user }) => user.attributes?.role === "ADMIN" ? "default" : null,
+  },
+})
+
+// In TailorDB validate
+.validate({
+  field: [
+    ({ user }) => user.attributes?.role === "ADMIN",
+    "Only admins can set this field",
+  ],
+})
+```
+
+Machine users are useful for:
+
+- CI/CD pipelines
+- Background jobs
+- Service-to-service communication
+- E2E testing
+
+Get a machine user token using the CLI:
+
+```bash
+tailor-sdk machineuser token <name>
+```
+
+### Using auth.invoker()
+
+The `auth.invoker()` method creates a type-safe reference to a machine user for use in workflow triggers. This specifies which machine user's permissions should be used when executing the workflow.
+
+```typescript
+// tailor.config.ts
+export const auth = defineAuth("my-auth", {
+  machineUsers: {
+    "admin-machine-user": {
+      attributes: { role: "ADMIN" },
+    },
+  },
+  // ... other config
+});
+```
+
+```typescript
+// resolvers/trigger-workflow.ts
+import { createResolver, t } from "@tailor-platform/sdk";
+import { auth } from "../tailor.config";
+import myWorkflow from "../workflows/my-workflow";
+
+export default createResolver({
+  name: "triggerMyWorkflow",
+  operation: "mutation",
+  input: {
+    id: t.string(),
+  },
+  body: async ({ input }) => {
+    // Trigger workflow with machine user permissions
+    const workflowRunId = await myWorkflow.trigger(
+      { id: input.id },
+      { authInvoker: auth.invoker("admin-machine-user") },
+    );
+    return { workflowRunId };
+  },
+  output: t.object({
+    workflowRunId: t.string(),
+  }),
+});
+```
+
+The `invoker()` method is type-safe and only accepts machine user names defined in the auth configuration.
+
+## OAuth 2.0 Clients
+
+Configure OAuth 2.0 clients for third-party applications:
+
+```typescript
+oauth2Clients: {
+  "my-oauth2-client": {
+    redirectURIs: [
+      "https://example.com/callback",
+      `${website.url}/callback`,  // Type-safe URL from StaticWebsite
+    ],
+    description: "My OAuth2 client",
+    grantTypes: ["authorization_code", "refresh_token"],
+    accessTokenLifetimeSeconds: 3600,    // 1 hour
+    refreshTokenLifetimeSeconds: 604800, // 7 days
+  },
+},
+```
+
+**redirectURIs**: Allowed redirect URIs after authentication.
+
+**description**: Optional description of the client.
+
+**grantTypes**: Supported OAuth 2.0 grant types:
+
+- `authorization_code` - Standard OAuth 2.0 authorization code flow
+- `refresh_token` - Allow refreshing access tokens
+
+**accessTokenLifetimeSeconds**: Optional access token lifetime in seconds. Minimum: 60 seconds, Maximum: 86400 seconds (1 day). If not specified, uses platform default.
+
+**refreshTokenLifetimeSeconds**: Optional refresh token lifetime in seconds. Minimum: 60 seconds, Maximum: 604800 seconds (7 days). If not specified, uses platform default.
+
+Get OAuth2 client credentials using the CLI:
+
+```bash
+tailor-sdk oauth2client get <name>
+```
+
+## Identity Provider
+
+Connect to an external identity provider:
+
+```typescript
+idProvider: idp.provider("my-provider", "my-client"),
+```
+
+See [IdP](./idp.md) for configuring identity providers.
+
+## CLI Commands
+
+Manage Auth resources using the CLI:
+
+```bash
+# List machine users
+tailor-sdk machineuser list
+
+# Get machine user token
+tailor-sdk machineuser token <name>
+
+# List OAuth2 clients
+tailor-sdk oauth2client list
+
+# Get OAuth2 client credentials
+tailor-sdk oauth2client get <name>
+```
+
+See [Auth Resource Commands](../cli/auth.md) for full documentation.

package/docs/services/executor.md

@@ -0,0 +1,304 @@
+# Executor
+
+Executors are event-driven handlers that automatically trigger in response to data changes, schedules, or external events.
+
+## Overview
+
+Executors provide:
+
+- Automatic triggers on record changes (create, update, delete)
+- Scheduled execution via cron expressions
+- Incoming webhook handlers
+- Post-resolver execution hooks
+- Multiple execution targets (functions, webhooks, GraphQL)
+
+For the official Tailor Platform documentation, see [Executor Guide](https://docs.tailor.tech/guides/executor/overview).
+
+## Creating an Executor
+
+Define executors in files matching glob patterns specified in `tailor.config.ts`.
+
+```typescript
+import { createExecutor, recordCreatedTrigger, t } from "@tailor-platform/sdk";
+import { user } from "../tailordb/user";
+
+export default createExecutor({
+  name: "user-welcome",
+  description: "Send welcome email to new users",
+  trigger: recordCreatedTrigger({
+    type: user,
+    condition: ({ newRecord }) => !!newRecord.email && newRecord.isActive,
+  }),
+  operation: {
+    kind: "function",
+    body: async ({ newRecord }) => {
+      // Send welcome email logic here
+    },
+  },
+});
+```
+
+## Trigger Types
+
+### Record Triggers
+
+Fire when records are created, updated, or deleted:
+
+- `recordCreatedTrigger()`: Fires when a new record is created
+- `recordUpdatedTrigger()`: Fires when a record is updated
+- `recordDeletedTrigger()`: Fires when a record is deleted
+
+Each trigger can include an optional filter function:
+
+```typescript
+recordUpdatedTrigger({
+  type: order,
+  condition: ({ newRecord, oldRecord }) =>
+    newRecord.status === "completed" && oldRecord.status !== "completed",
+});
+```
+
+### Schedule Trigger
+
+Fires on a cron schedule:
+
+```typescript
+scheduleTrigger({ cron: "*/5 * * * *" }); // Every 5 minutes
+scheduleTrigger({ cron: "0 9 * * 1" }); // Every Monday at 9am
+scheduleTrigger({ cron: "0 0 1 * *" }); // First day of every month
+scheduleTrigger({ cron: "0 * * * *", timezone: "Asia/Tokyo" });
+```
+
+### Incoming Webhook Trigger
+
+Fires when an external webhook is received:
+
+```typescript
+incomingWebhookTrigger<WebhookPayload>();
+```
+
+### Resolver Executed Trigger
+
+Fires when a resolver is executed:
+
+```typescript
+resolverExecutedTrigger({
+  resolver: createOrderResolver,
+  condition: ({ result, error }) => !error && result?.order?.id,
+});
+```
+
+## Execution Targets
+
+### Function Execution
+
+Execute JavaScript/TypeScript functions:
+
+```typescript
+createExecutor({
+  operation: {
+    kind: "function",
+    body: async ({ newRecord }) => {
+      console.log("New record created:", newRecord);
+    },
+  },
+});
+```
+
+### Webhook Execution
+
+Call external webhooks with dynamic data:
+
+```typescript
+createExecutor({
+  operation: {
+    kind: "webhook",
+    url: ({ newRecord }) =>
+      `https://api.example.com/webhooks/${newRecord.type}`,
+    headers: {
+      "Content-Type": "application/json",
+      "X-API-Key": { vault: "api-keys", key: "external-api" },
+    },
+    requestBody: ({ newRecord }) => ({
+      id: newRecord.id,
+      timestamp: new Date(),
+      data: newRecord,
+    }),
+  },
+});
+```
+
+### GraphQL Execution
+
+Execute GraphQL queries and mutations:
+
+```typescript
+import { gql } from "@tailor-platform/sdk";
+
+createExecutor({
+  operation: {
+    kind: "graphql",
+    appName: "my-app",
+    query: gql`
+      mutation UpdateUserStatus($id: ID!, $status: String!) {
+        updateUser(id: $id, input: { status: $status }) {
+          id
+          status
+          updatedAt
+        }
+      }
+    `,
+    variables: ({ newRecord }) => ({
+      id: newRecord.userId,
+      status: "active",
+    }),
+  },
+});
+```
+
+## Event Payloads
+
+Each trigger type provides specific context data in the callback functions.
+
+### Record Event Payloads
+
+Record triggers receive context based on the operation type:
+
+#### Created Event
+
+```typescript
+interface RecordCreatedContext<T> {
+  workspaceId: string; // Workspace identifier
+  namespaceName: string; // Application/namespace name
+  typeName: string; // TailorDB type name
+  newRecord: T; // The newly created record
+}
+```
+
+#### Updated Event
+
+```typescript
+interface RecordUpdatedContext<T> {
+  workspaceId: string;
+  namespaceName: string;
+  typeName: string;
+  oldRecord: T; // Previous record state
+  newRecord: T; // Current record state
+}
+```
+
+#### Deleted Event
+
+```typescript
+interface RecordDeletedContext<T> {
+  workspaceId: string;
+  namespaceName: string;
+  typeName: string;
+  oldRecord: T; // The deleted record
+}
+```
+
+**Usage Example:**
+
+```typescript
+import { createExecutor, recordUpdatedTrigger, t } from "@tailor-platform/sdk";
+import { order } from "../tailordb/order";
+
+export default createExecutor({
+  name: "order-status-changed",
+  trigger: recordUpdatedTrigger({
+    type: order,
+    condition: ({ oldRecord, newRecord }) =>
+      oldRecord.status !== newRecord.status,
+  }),
+  operation: {
+    kind: "function",
+    body: async ({ oldRecord, newRecord, typeName }) => {
+      console.log(`${typeName} status changed:`);
+      console.log(`  From: ${oldRecord.status}`);
+      console.log(`  To: ${newRecord.status}`);
+    },
+  },
+});
+```
+
+### Schedule Event Payload
+
+Schedule triggers receive minimal context:
+
+```typescript
+interface ScheduleContext {
+  scheduledTime: string; // ISO 8601 timestamp
+}
+```
+
+### Incoming Webhook Payload
+
+Webhook triggers receive HTTP request data:
+
+```typescript
+interface WebhookContext<T = unknown> {
+  body: T; // Parsed request body
+  headers: Record<string, string>; // Request headers
+  method: string; // HTTP method (POST, etc.)
+  rawBody: string; // Raw request body as string
+}
+```
+
+**Usage Example:**
+
+```typescript
+import { createExecutor, incomingWebhookTrigger } from "@tailor-platform/sdk";
+
+interface StripeWebhook {
+  type: string;
+  data: { object: { id: string; amount: number } };
+}
+
+export default createExecutor({
+  name: "stripe-webhook",
+  trigger: incomingWebhookTrigger<StripeWebhook>(),
+  operation: {
+    kind: "function",
+    body: async ({ body, headers }) => {
+      const signature = headers["stripe-signature"];
+      console.log(`Received ${body.type} event`);
+      // Process webhook...
+    },
+  },
+});
+```
+
+### Resolver Executed Payload
+
+Resolver triggers receive the resolver's result or error:
+
+```typescript
+interface ResolverExecutedContext<TResult> {
+  resolverName: string; // Name of the executed resolver
+  result?: TResult; // Return value (on success)
+  error?: Error; // Error object (on failure)
+}
+```
+
+**Usage Example:**
+
+```typescript
+import { createExecutor, resolverExecutedTrigger } from "@tailor-platform/sdk";
+import { createOrderResolver } from "../resolvers/create-order";
+
+export default createExecutor({
+  name: "order-created-notification",
+  trigger: resolverExecutedTrigger({
+    resolver: createOrderResolver,
+    condition: ({ result, error }) => !error && !!result?.order,
+  }),
+  operation: {
+    kind: "function",
+    body: async ({ result, resolverName }) => {
+      console.log(`${resolverName} completed successfully`);
+      console.log(`Order ID: ${result.order.id}`);
+    },
+  },
+});
+```

package/docs/services/idp.md

@@ -0,0 +1,106 @@
+# IdP (Identity Provider)
+
+IdP is a built-in identity provider service for managing user authentication.
+
+## Overview
+
+The Built-in IdP provides:
+
+- User registration and authentication
+- OAuth client management
+- Integration with Auth service
+
+For the official Tailor Platform documentation, see [Identity Provider Setup](https://docs.tailor.tech/tutorials/setup-auth/setup-identity-provider).
+
+## Configuration
+
+Configure the Built-in IdP using `defineIdp()`:
+
+```typescript
+import { defineIdp, defineConfig } from "@tailor-platform/sdk";
+
+const idp = defineIdp("my-idp", {
+  authorization: "loggedIn",
+  clients: ["my-client"],
+});
+
+export default defineConfig({
+  idp: [idp],
+});
+```
+
+## Options
+
+### authorization
+
+User management permissions. Controls who can manage users in the IdP.
+
+```typescript
+defineIdp("my-idp", {
+  authorization: "loggedIn", // Only logged-in users can manage
+});
+
+defineIdp("my-idp", {
+  authorization: "insecure", // Anyone can manage (development only)
+});
+
+defineIdp("my-idp", {
+  authorization: "user.role == 'admin'", // CEL expression
+});
+```
+
+**Values:**
+
+- `"insecure"` - No authentication required (use only for development)
+- `"loggedIn"` - Requires authenticated user
+- CEL expression - Custom authorization logic
+
+### clients
+
+OAuth client names that can use this IdP:
+
+```typescript
+defineIdp("my-idp", {
+  clients: ["default-client", "mobile-client"],
+});
+```
+
+## Using idp.provider()
+
+The `idp.provider()` method creates a type-safe reference to the IdP for use in Auth configuration. The client name is validated at compile time against the clients defined in the IdP.
+
+```typescript
+import { defineIdp, defineAuth, defineConfig } from "@tailor-platform/sdk";
+import { user } from "./tailordb/user";
+
+const idp = defineIdp("my-idp", {
+  authorization: "loggedIn",
+  clients: ["default-client", "mobile-client"],
+});
+
+const auth = defineAuth("my-auth", {
+  userProfile: {
+    type: user,
+    usernameField: "email",
+    attributes: { role: true },
+  },
+  // Type-safe: only "default-client" or "mobile-client" are allowed
+  idProvider: idp.provider("my-provider", "default-client"),
+});
+
+export default defineConfig({
+  idp: [idp],
+  auth,
+});
+```
+
+**Parameters:**
+
+```typescript
+idp.provider(
+  "provider-name", // Name for the provider reference
+  "client-name", // Must be one of the clients defined in the IdP
+);
+```
+
+The second argument only accepts client names that were defined in the `clients` array of the IdP configuration.