@tailor-platform/sdk 0.16.3 → 0.18.0

package/docs/services/resolver.md

@@ -0,0 +1,213 @@
+# Resolver
+
+Resolvers are custom GraphQL endpoints with business logic that execute on the Tailor Platform.
+
+## Overview
+
+Resolvers provide:
+
+- Custom GraphQL queries and mutations
+- Type-safe input/output schemas
+- Access to TailorDB via Kysely query builder
+- User context for authentication/authorization
+
+## Comparison with Tailor Platform Pipeline Resolver
+
+The SDK's Resolver is a simplified version of Tailor Platform's [Pipeline Resolver](https://docs.tailor.tech/guides/pipeline).
+
+| Pipeline Resolver                        | SDK Resolver                      |
+| ---------------------------------------- | --------------------------------- |
+| Multiple steps with different operations | Single `body` function            |
+| Declarative step configuration           | Imperative TypeScript code        |
+| Built-in TailorDB/GraphQL steps          | Direct database access via Kysely |
+| CEL expressions for data transformation  | Native TypeScript transformations |
+
+### Example Comparison
+
+**Pipeline Resolver (Tailor Platform native):**
+
+```yaml
+steps:
+  - name: getUser
+    operation: tailordb.query
+    params:
+      type: User
+      filter:
+        email: { eq: "{{ input.email }}" }
+  - name: updateAge
+    operation: tailordb.mutation
+    params:
+      type: User
+      id: "{{ steps.getUser.id }}"
+      input:
+        age: "{{ steps.getUser.age + 1 }}"
+```
+
+**Resolver (SDK):**
+
+```typescript
+createResolver({
+  name: "incrementUserAge",
+  operation: "mutation",
+  input: { email: t.string() },
+  body: async (context) => {
+    const db = getDB("tailordb");
+    const user = await db
+      .selectFrom("User")
+      .selectAll()
+      .where("email", "=", context.input.email)
+      .executeTakeFirstOrThrow();
+
+    await db
+      .updateTable("User")
+      .set({ age: user.age + 1 })
+      .where("id", "=", user.id)
+      .execute();
+
+    return { oldAge: user.age, newAge: user.age + 1 };
+  },
+  output: t.object({ oldAge: t.int(), newAge: t.int() }),
+});
+```
+
+## Creating a Resolver
+
+Define resolvers in files matching glob patterns specified in `tailor.config.ts`.
+
+```typescript
+import { createResolver, t } from "@tailor-platform/sdk";
+
+export default createResolver({
+  name: "add",
+  operation: "query",
+  input: {
+    left: t.int(),
+    right: t.int(),
+  },
+  body: (context) => {
+    return {
+      result: context.input.left + context.input.right,
+    };
+  },
+  output: t.object({
+    result: t.int(),
+  }),
+});
+```
+
+## Input/Output Schemas
+
+Define input/output schemas using methods of `t` object. Basic usage and supported field types are the same as TailorDB. TailorDB-specific options (e.g., index, relation) are not supported.
+
+You can reuse fields defined with `db` object, but note that unsupported options will be ignored:
+
+```typescript
+const user = db.type("User", {
+  name: db.string().unique(),
+  age: db.int(),
+});
+
+createResolver({
+  input: {
+    name: user.fields.name,
+  },
+});
+```
+
+## Input Validation
+
+Add validation rules to input fields using the `validate` method:
+
+```typescript
+createResolver({
+  name: "createUser",
+  operation: "mutation",
+  input: {
+    email: t
+      .string()
+      .validate(
+        ({ value }) => value.includes("@"),
+        [
+          ({ value }) => value.length <= 255,
+          "Email must be 255 characters or less",
+        ],
+      ),
+    age: t.int().validate(({ value }) => value >= 0 && value <= 150),
+  },
+  body: (context) => {
+    // Input is validated before body executes
+    return { email: context.input.email };
+  },
+  output: t.object({ email: t.string() }),
+});
+```
+
+Validation functions receive:
+
+- `value` - The field value being validated
+- `data` - The entire input object
+- `user` - The user performing the operation
+
+You can specify validation as:
+
+- A function returning `boolean` (uses default error message)
+- A tuple of `[function, errorMessage]` for custom error messages
+- Multiple validators (pass multiple arguments to `validate`)
+
+## Body Function
+
+Define actual resolver logic in the `body` function. Function arguments include:
+
+- `input` - Input data from GraphQL request
+- `user` - User performing the operation
+
+### Using Kysely for Database Access
+
+If you're generating Kysely types with a generator, you can use `getDB` to execute typed queries:
+
+```typescript
+import { getDB } from "../generated/tailordb";
+
+createResolver({
+  name: "getUser",
+  operation: "query",
+  input: {
+    name: t.string(),
+  },
+  body: async (context) => {
+    const db = getDB("tailordb");
+    const result = await db
+      .selectFrom("User")
+      .select("id")
+      .where("name", "=", context.input.name)
+      .limit(1)
+      .executeTakeFirstOrThrow();
+    return {
+      result: result.id,
+    };
+  },
+  output: t.object({
+    result: t.uuid(),
+  }),
+});
+```
+
+## Query vs Mutation
+
+Use `operation: "query"` for read operations and `operation: "mutation"` for write operations:
+
+```typescript
+// Query - for reading data
+createResolver({
+  name: "getUsers",
+  operation: "query",
+  // ...
+});
+
+// Mutation - for creating, updating, or deleting data
+createResolver({
+  name: "createUser",
+  operation: "mutation",
+  // ...
+});
+```

package/docs/services/secret.md

@@ -0,0 +1,116 @@
+# Secret Manager
+
+Secret Manager provides secure storage for sensitive values like API keys, tokens, and credentials that your application needs at runtime.
+
+## Overview
+
+Secret Manager provides:
+
+- Secure storage for sensitive configuration values
+- Organized secrets within named vaults
+- Runtime access from executors and workflows
+- CLI management for secrets lifecycle
+
+## Concepts
+
+### Vaults
+
+Vaults are containers that group related secrets together. Each workspace can have multiple vaults, typically organized by purpose or environment.
+
+```
+workspace/
+├── vault: api-keys
+│   ├── stripe-secret-key
+│   ├── sendgrid-api-key
+│   └── external-service-token
+└── vault: database
+    ├── read-replica-password
+    └── analytics-connection-string
+```
+
+### Secrets
+
+Secrets are key-value pairs stored within a vault. Secret values are encrypted at rest and only accessible at runtime by authorized services.
+
+## Using Secrets
+
+### In Webhook Operations
+
+Reference secrets in webhook headers using the vault/key syntax:
+
+```typescript
+import { createExecutor, recordCreatedTrigger } from "@tailor-platform/sdk";
+import { order } from "../tailordb/order";
+
+export default createExecutor({
+  name: "notify-external-service",
+  trigger: recordCreatedTrigger({ type: order }),
+  operation: {
+    kind: "webhook",
+    url: "https://api.example.com/orders",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: { vault: "api-keys", key: "external-api-token" },
+      "X-API-Key": { vault: "api-keys", key: "api-secret" },
+    },
+    requestBody: ({ newRecord }) => ({
+      orderId: newRecord.id,
+      amount: newRecord.total,
+    }),
+  },
+});
+```
+
+The secret reference format:
+
+```typescript
+{ vault: "vault-name", key: "secret-name" }
+```
+
+At runtime, these references are replaced with the actual secret values.
+
+## CLI Management
+
+### Create a Vault
+
+```bash
+tailor-sdk secret vault create --name api-keys
+```
+
+### Add Secrets
+
+```bash
+# Create a secret
+tailor-sdk secret create \
+  --vault-name api-keys \
+  --name stripe-secret-key \
+  --value sk_live_xxxxx
+
+# Update a secret
+tailor-sdk secret update \
+  --vault-name api-keys \
+  --name stripe-secret-key \
+  --value sk_live_yyyyy
+```
+
+### List Secrets
+
+```bash
+# List vaults
+tailor-sdk secret vault list
+
+# List secrets in a vault (values are hidden)
+tailor-sdk secret list --vault-name api-keys
+```
+
+### Delete Secrets
+
+```bash
+# Delete a secret
+tailor-sdk secret delete --vault-name api-keys --name old-key --yes
+
+# Delete a vault (must be empty)
+tailor-sdk secret vault delete --name old-vault --yes
+```
+
+See [Secret CLI Commands](../cli/secret.md) for full documentation.

package/docs/services/staticwebsite.md

@@ -0,0 +1,132 @@
+# Static Website
+
+Static Website is a service for hosting static web applications on the Tailor Platform.
+
+## Overview
+
+Static Website provides:
+
+- Static file hosting
+- Type-safe URL references for configuration
+- IP address restrictions
+
+For the official Tailor Platform documentation, see [Static Website Guide](https://docs.tailor.tech/guides/static-website-hosting).
+
+## Configuration
+
+Configure static website hosting using `defineStaticWebSite()`:
+
+```typescript
+import { defineStaticWebSite, defineConfig } from "@tailor-platform/sdk";
+
+const website = defineStaticWebSite("my-website", {
+  description: "My Static Website",
+});
+
+export default defineConfig({
+  staticWebsites: [website],
+});
+```
+
+## Options
+
+### description
+
+A description of the static website:
+
+```typescript
+defineStaticWebSite("my-website", {
+  description: "Frontend application for my service",
+});
+```
+
+### allowedIPAddresses
+
+Restrict access to specific IP addresses in CIDR format:
+
+```typescript
+defineStaticWebSite("my-website", {
+  allowedIPAddresses: ["192.168.0.0/24", "10.0.0.0/8"],
+});
+```
+
+## Type-safe URL References
+
+The returned website object provides a `url` property that resolves to the actual URL at deployment time. Use this for type-safe configuration:
+
+### CORS Settings
+
+```typescript
+const website = defineStaticWebSite("my-frontend", {
+  description: "Frontend application",
+});
+
+export default defineConfig({
+  cors: [website.url], // Resolved at deployment
+  staticWebsites: [website],
+});
+```
+
+### OAuth2 Redirect URIs
+
+```typescript
+const website = defineStaticWebSite("my-frontend", {
+  description: "Frontend application",
+});
+
+const auth = defineAuth("my-auth", {
+  oauth2Clients: {
+    "my-client": {
+      redirectURIs: [
+        `${website.url}/callback`, // https://my-frontend.example.com/callback
+        `${website.url}/auth/complete`, // https://my-frontend.example.com/auth/complete
+      ],
+      grantTypes: ["authorization_code", "refresh_token"],
+    },
+  },
+});
+```
+
+## Complete Example
+
+```typescript
+import {
+  defineConfig,
+  defineAuth,
+  defineIdp,
+  defineStaticWebSite,
+} from "@tailor-platform/sdk";
+import { user } from "./tailordb/user";
+
+const website = defineStaticWebSite("my-frontend", {
+  description: "Frontend application",
+});
+
+const idp = defineIdp("my-idp", {
+  authorization: "loggedIn",
+  clients: ["default-client"],
+});
+
+const auth = defineAuth("my-auth", {
+  userProfile: {
+    type: user,
+    usernameField: "email",
+    attributes: { role: true },
+  },
+  oauth2Clients: {
+    "frontend-client": {
+      redirectURIs: [`${website.url}/callback`],
+      grantTypes: ["authorization_code", "refresh_token"],
+    },
+  },
+  idProvider: idp.provider("default", "default-client"),
+});
+
+export default defineConfig({
+  name: "my-app",
+  cors: [website.url],
+  idp: [idp],
+  auth,
+  staticWebsites: [website],
+});
+```