@xentom/integration-framework 0.0.18 → 0.0.19

package/AGENTS.md

@@ -0,0 +1,438 @@
+# @xentom/integration-framework — Agent Guide
+
+Concise, directive reference for AI agents building integrations with this framework.
+This is the only file you need to read. For type-level details, check the `.d.ts` files in `dist/`.
+
+## Import Convention
+
+```typescript
+import * as i from '@xentom/integration-framework'
+import * as v from 'valibot'
+```
+
+Always use namespace imports for the framework (`i`) and validator (`v`).
+Any [Standard Schema](https://github.com/standard-schema/standard-schema)-compatible validator works (e.g. `valibot`, `zod`). Most integrations use `valibot`.
+Never access the validator through the framework (no `i.v.string()`).
+
+## Integration Structure
+
+Every integration default-exports a call to `i.integration()`:
+
+```typescript
+declare module '@xentom/integration-framework' {
+  interface IntegrationState {
+    client: SomeClient
+  }
+}
+
+export default i.integration({
+  nodes,        // required — record of trigger/callable/pure nodes
+  auth,         // optional — i.auth.token(), i.auth.oauth2(), or i.auth.basic()
+  env,          // optional — record of i.env() definitions
+  start(opts) { // optional — initialize shared resources
+    opts.state.client = new SomeClient(opts.auth.token)
+  },
+  stop(opts) {  // optional — tear down resources
+    opts.state.client.close()
+  },
+})
+```
+
+- Augment `IntegrationState` via `declare module` to type the shared `state` object.
+- `start` receives `{ auth, env, state, webhook, kv }`.
+- `stop` receives the same, but `state` values may be undefined (partial).
+- `state` is in-memory only — not persisted across restarts.
+- When using valibot, set global config for early abort at the top of your entry point:
+
+```typescript
+v.setGlobalConfig({ abortEarly: true, abortPipeEarly: true })
+```
+
+## Authentication
+
+Three auth strategies. Pick one per integration.
+
+| Strategy | Builder | Credential access |
+|----------|---------|-------------------|
+| API token | `i.auth.token()` | `opts.auth.token` (string) |
+| OAuth 2.0 | `i.auth.oauth2({ authUrl, tokenUrl, scopes })` | `opts.auth.accessToken` (string) |
+| Basic | `i.auth.basic()` | `opts.auth.username`, `opts.auth.password` |
+
+Token auth supports a `schema` for validation and a `control` for the UI:
+
+```typescript
+auth: i.auth.token({
+  control: i.controls.text({
+    label: 'API Key',
+    placeholder: 'sk_...',
+  }),
+  schema: v.pipeAsync(
+    v.string(),
+    v.startsWith('sk_'),
+    v.checkAsync(async (token) => { /* test call */ return true }, 'Invalid key.'),
+  ),
+})
+```
+
+OAuth2 also supports `grantType`, `pkce`, `pkceMethod`, and `onAccessTokenUpdated`.
+When using OAuth2, implement `onAccessTokenUpdated` to refresh your client when tokens rotate:
+
+```typescript
+auth: i.auth.oauth2({
+  authUrl: 'https://example.com/oauth/authorize',
+  tokenUrl: 'https://example.com/oauth/token',
+  scopes: ['read', 'write'],
+  onAccessTokenUpdated(opts) {
+    opts.state.client.setToken(opts.auth.accessToken)
+  },
+})
+```
+
+## Environment Variables
+
+Use `env` for configuration values that are not authentication credentials.
+
+```typescript
+env: {
+  REGION: i.env({
+    control: i.controls.select({
+      options: [
+        { value: 'us-east-1', label: 'US East' },
+        { value: 'eu-west-1', label: 'EU West' },
+      ],
+    }),
+  }),
+  DEBUG: i.env({
+    control: i.controls.switch({ label: 'Debug Mode', defaultValue: false }),
+    optional: true,
+  }),
+}
+```
+
+Rules:
+- Env vars are available in `start`/`stop` via `opts.env`. They are **not** available inside nodes.
+- To use env values in nodes, read them in `start` and store on `state`.
+- Controls are limited to `text`, `switch`, and `select` (static options only — no async callback).
+- Set `sensitive: true` on text controls for secrets.
+- Add `optional: true` on the env definition itself (not the control) if the value is not required.
+
+## Node Types
+
+### Trigger — workflow entry point
+
+Listens for external events. Implements `subscribe`, which should return a cleanup function.
+
+```typescript
+export const onEvent = nodes.trigger({
+  outputs: {
+    payload: i.pins.data<EventPayload>(),
+  },
+  subscribe(opts) {
+    const unsubscribe = opts.state.client.on('event', (data) => {
+      void opts.next({ payload: data })
+    })
+    return () => unsubscribe()
+  },
+})
+```
+
+- `subscribe` receives `{ next, state, webhook, inputs, variables, kv, node, workflow }`.
+- Call `next(outputs)` to fire the trigger. If exec pins are defined, call `next('pinName', outputs)`.
+- Use `void opts.next(...)` for fire-and-forget, or `await opts.next(...)` when you need to wait for downstream execution.
+- `next` accepts an optional trailing arg for context and dedup: `next(outputs, { ctx, deduplication: { id, ttl? } })` or `next('pinName', outputs, { ctx, deduplication: { id, ttl? } })`.
+- Webhook triggers: call `opts.webhook.subscribe(handler)` — handler receives a `Request`, returns a `Response`.
+- The `workflow.on('start', callback)` hook lets you react to workflow lifecycle events.
+
+### Callable — side-effect action
+
+Invoked by other nodes during a workflow run. Implements `run` and calls `next()` to continue the workflow.
+
+```typescript
+export const createItem = nodes.callable({
+  inputs: {
+    name: pins.item.name,
+  },
+  outputs: {
+    id: pins.item.id.with({ control: false }),
+  },
+  async run(opts) {
+    const result = await opts.state.client.items.create({ name: opts.inputs.name })
+    return opts.next({ id: result.id })
+  },
+})
+```
+
+- `run` receives `{ next, state, inputs, ctx, variables, webhook, kv, node }`.
+- Always `return opts.next(...)` — this is the standard pattern across all integrations.
+- If the node defines exec pins in outputs, call `return opts.next('pinName', outputs)` for the specific branch.
+- Omitting `next()` is valid for terminal/void actions (e.g. delete operations) that have no downstream outputs. The workflow will not continue to connected nodes.
+
+### Pure — deterministic transform
+
+Side-effect-free computation. Assign directly to `outputs` — no `next()` call.
+
+```typescript
+export const formatName = nodes.pure({
+  inputs: {
+    first: i.pins.data({ schema: v.string() }),
+    last: i.pins.data({ schema: v.string() }),
+  },
+  outputs: {
+    full: i.pins.data<string>(),
+  },
+  run(opts) {
+    opts.outputs.full = `${opts.inputs.first} ${opts.inputs.last}`
+  },
+})
+```
+
+- `run` receives `{ inputs, outputs, state, ctx, variables, webhook, kv, node }`.
+- `run` is optional. Data-only pure nodes (e.g. a string constant with just a control) can omit it entirely.
+- Pure nodes cannot have exec pins. Outputs must be data pins only.
+- Evaluated lazily when downstream nodes need their outputs.
+
+### When to pick which
+
+| Need | Node type |
+|------|-----------|
+| React to external events (webhooks, timers, client events) | `trigger` |
+| Call an API, mutate data, produce side effects | `callable` |
+| Transform or compute a value from inputs, no side effects | `pure` |
+
+## Node Groups
+
+Organize nodes into UI categories:
+
+```typescript
+const nodes = i.nodes.group('Emails')
+
+export const sendEmail = nodes.callable({ ... })
+export const listEmails = nodes.callable({ ... })
+```
+
+Use slash-separated names for nested categories:
+
+```typescript
+const nodes = i.nodes.group('Repositories/Issues')
+```
+
+`group()` returns a scoped builder with `trigger`, `callable`, and `pure` — but no nested `group`.
+
+## Pins
+
+### Data Pins
+
+Carry values between nodes.
+
+```typescript
+// Minimal
+i.pins.data()
+
+// Typed (compile-time only)
+i.pins.data<User>()
+
+// With schema (runtime validation)
+i.pins.data({ schema: v.pipe(v.string(), v.email()) })
+
+// With state-dependent schema (function form — receives IntegrationOptions)
+i.pins.data({ schema: ({ state }) => v.pipe(v.string(), v.transform((id) => state.client.getById(id))) })
+
+// With control
+i.pins.data({
+  description: 'Recipient email.',
+  schema: v.pipe(v.string(), v.email()),
+  control: i.controls.text({ placeholder: 'user@example.com' }),
+})
+```
+
+#### Customizing with `.with()`
+
+Always use `.with()` to extend a pin definition. Never destructure or access internal properties.
+
+```typescript
+pins.email.address.with({ optional: true, description: 'CC recipient.' })
+pins.item.id.with({ control: false })  // strip the control (e.g. for output-only pins)
+```
+
+#### Pin definition rules
+
+- **Reusable pins** (in `src/pins/`): never set `optional: true` directly. Apply it via `.with()` at the usage site so the pin stays reusable. Same for `control: false` — use `.with({ control: false })` to strip controls when using a pin as an output.
+- **Inline pins** (created directly in node inputs/outputs): setting `optional: true` or `control: false` directly is fine.
+- Naming: `item` for a single object, `items` for an array, descriptive names for properties (`id`, `name`, `email`).
+- Provide `examples` on complex pins to help users and AI.
+
+### Exec Pins
+
+Control execution branching in trigger and callable nodes.
+
+```typescript
+outputs: {
+  forEach: i.pins.exec({
+    outputs: {
+      item: i.pins.data(),
+      index: i.pins.data(),
+    },
+  }),
+  completed: i.pins.exec(),
+},
+async run(opts) {
+  for (const [index, item] of opts.inputs.items.entries()) {
+    await opts.next('forEach', { item, index })
+  }
+  return opts.next('completed')
+},
+```
+
+**Only use exec pins for:**
+1. Branching logic (conditional paths)
+2. Iteration (forEach patterns)
+3. State machines
+
+**Never use exec pins for error handling.** Throw instead.
+
+## Controls
+
+| Control | Use for | Key options |
+|---------|---------|-------------|
+| `i.controls.text()` | Strings | `placeholder`, `sensitive`, `rows`, `language` (`'plain'`, `'html'`, `'markdown'`, `'javascript'`) |
+| `i.controls.expression()` | Numbers, objects, JS expressions | `placeholder`, `rows`, `defaultValue` |
+| `i.controls.select()` | Enum/choice values | `options` (static array or async callback), `placeholder`, `multiple` |
+| `i.controls.switch()` | Booleans | `defaultValue` |
+
+### Dynamic select options (nodes only)
+
+```typescript
+i.controls.select({
+  async options({ state, pagination, search }) {
+    const res = await state.client.items.list({ limit: pagination.limit, after: pagination.after })
+    return {
+      items: res.data.map((item) => ({ value: item.id, label: item.name, suffix: item.id })),
+      hasMore: res.hasMore,
+    }
+  },
+})
+```
+
+The callback receives `{ state, auth, env, webhook, kv, node, pagination, search }`.
+`pagination` has `limit`, `after?`, `before?`, and `page`.
+Dynamic options are **not** available on env var controls.
+
+## Generic Nodes
+
+Use `i.generic()` when a node's output types depend on its input types at the type level:
+
+```typescript
+export const passthrough = i.generic(<I extends i.GenericInputs<typeof inputs>>() => {
+  const inputs = {
+    value: i.pins.data(),
+  }
+
+  return i.nodes.pure({
+    inputs,
+    outputs: {
+      value: i.pins.data<I['value']>(),
+    },
+    run({ inputs, outputs }) {
+      outputs.value = inputs.value
+    },
+  })
+})
+```
+
+This is an advanced pattern. Use it only when static typing cannot express the relationship between inputs and outputs.
+
+## Key-Value Store
+
+A persistent store available via `opts.kv` in all nodes, triggers, and lifecycle hooks.
+
+```typescript
+await opts.kv.set('cursor', lastCursor)
+const cursor = await opts.kv.get('cursor')    // string | null
+await opts.kv.delete('cursor', 'otherKey')
+```
+
+Values are strings. Persists across restarts. Use for pagination cursors, sync tokens, or cached state.
+
+## Error Handling
+
+**Always throw. Never route errors through exec pins or return values.**
+
+```typescript
+// Correct — throw and let the framework handle it
+async run(opts) {
+  const res = await opts.state.client.items.get(opts.inputs.id)
+  if (!res) throw new Error('Item not found')
+  return opts.next({ item: res })
+}
+```
+
+The framework catches thrown errors and surfaces them to the user.
+
+The only exception is webhook handlers inside triggers, which may catch errors to return an appropriate HTTP response:
+
+```typescript
+subscribe(opts) {
+  const unsub = opts.webhook.subscribe(async (req) => {
+    try {
+      const data = await req.json()
+      opts.next({ data })
+      return new Response('OK')
+    } catch {
+      return new Response('Bad Request', { status: 400 })
+    }
+  })
+  return () => unsub()
+}
+```
+
+## Trigger Cleanup
+
+Every `subscribe` function should return a cleanup function (sync or async). The framework calls it when the workflow stops or reconfigures.
+
+Clean up:
+- `setInterval` / `setTimeout` handles
+- Event listener subscriptions
+- Webhook handlers (the return value of `webhook.subscribe()`)
+- Any open connections or resources
+
+Omitting cleanup is technically allowed (the return type permits `void`), but causes resource leaks in most cases. Only omit it when cleanup is handled centrally (e.g. in `stop()`).
+
+## Webhook Routing in `start()`
+
+For integrations that receive all events through a single webhook endpoint (e.g. GitHub, Stripe), set up central webhook routing in `start()` and distribute events to trigger nodes via shared state:
+
+```typescript
+start(opts) {
+  opts.state.client = new Client(opts.auth.token)
+  opts.state.events = new EventEmitter()
+
+  opts.webhook.subscribe(async (request) => {
+    const signature = request.headers.get('X-Signature')
+    if (!signature) return new Response('Unauthorized', { status: 401 })
+
+    const payload = await request.text()
+    if (!verify(payload, signature)) return new Response('Forbidden', { status: 403 })
+
+    const event = JSON.parse(payload)
+    opts.state.events.emit(event.type, event)
+    return new Response('OK')
+  })
+}
+```
+
+Individual trigger nodes then subscribe to the shared event emitter in their `subscribe()` function.
+
+## Common Mistakes
+
+- **Forgetting `return opts.next()` in callable nodes.** The workflow will not continue to downstream nodes. Always `return opts.next(...)` unless the node is a terminal/void action.
+- **Calling `next()` in pure nodes.** Pure nodes assign to `outputs` directly. They have no `next`.
+- **Using exec pins for error handling.** Throw errors instead. The framework handles them.
+- **Not returning cleanup from `subscribe`.** Causes resource leaks on stop/reconfigure.
+- **Accessing `env` inside nodes.** Env vars are only in `start`/`stop`. Store values on `state` instead.
+- **Setting `optional: true` on reusable pin definitions (in `src/pins/`).** Apply it via `.with()` at the usage site to keep the pin reusable. Inline pins in node definitions may set it directly.
+- **Using `as any`, `@ts-ignore`, or `biome-ignore`.** Fix the type error properly. If stuck after 3 attempts, redesign the approach. The only acceptable escape hatch is `@ts-expect-error` in rare generic type narrowing scenarios.
+- **Using `import type { X } from 'pkg'`.** Use inline type keyword: `import { type X } from 'pkg'`.
+- **Generic export names.** Use `sendEmail`, not `send`. Use `deleteUser`, not `delete`.
+- **Unnecessary `displayName`.** Only set it when auto-generation from the export name is wrong (e.g. acronyms, JS keyword conflicts).
+- **Wrapping everything in try-catch.** Let errors propagate. Only catch when you need to transform the error or handle webhook responses.
+- **Intermediate variables for API calls.** Prefer `opts.state.client.items.create(...)` over `const client = opts.state.client; const items = client.items; ...`.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@xentom/integration-framework",
   "description": "A type-safe, declarative framework for building composable workflow integrations using nodes, pins, and rich controls.",
-  "version": "0.0.18",
+  "version": "0.0.19",
   "license": "MIT",
   "homepage": "https://xentom.com",
   "author": {
@@ -42,7 +42,7 @@
   "sideEffects": false,
   "files": [
     "dist",
-    "CLAUDE.md"
+    "AGENTS.md"
   ],
   "publishConfig": {
     "access": "public"
@@ -58,7 +58,7 @@
   },
   "devDependencies": {
     "@xentom/style-guide": "^0.0.0",
-    "bun-types": "^1.3.6",
+    "@types/bun": "^1.3.10",
     "typescript": "^5.9.3"
   }
-}
+}

package/CLAUDE.md

@@ -1,837 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Integration Development Commands
-
-```bash
-# Build and test your integration
-npm run build
-npm run typecheck
-npm run lint
-```
-
-## Framework Overview
-
-This is the `@xentom/integration-framework` package for building workflow integrations. It provides a declarative,
-type-safe API for creating integrations that can process data through interconnected nodes.
-
-**Core Philosophy:**
-
-- **Type Safety**: Heavy use of TypeScript generics and inference
-- **Declarative**: Define what you want, not how to achieve it
-- **Composable**: Build complex workflows from simple, reusable components
-- **Standard Schema**: Compatible with any validation library using the Standard Schema spec
-
-Import the framework as:
-
-```typescript
-import * as i from '@xentom/integration-framework';
-```
-
-## Integration Architecture
-
-### Integration Structure
-
-Every integration must follow this structure:
-
-```typescript
-export default i.integration({
-  // Environment variables - secure configuration
-  env: {
-    API_KEY: i.env({
-      control: i.controls.text({
-        label: 'API Key',
-        description: 'Your service API key for authentication',
-        sensitive: true, // Hides value in UI
-      }),
-    }),
-  },
-
-  // Workflow nodes - the building blocks
-  nodes: {
-    // Your trigger, callable, and pure nodes
-  },
-
-  // Optional lifecycle hooks
-  start({ state, webhook }) {
-    // Initialize shared resources (API clients, connections, etc.)
-    // This runs when the integration starts
-  },
-
-  stop({ state }) {
-    // Clean up resources (close connections, clear timers, etc.)
-    // This runs when the integration stops
-  },
-});
-```
-
-### Integration State
-
-The integration provides an in-memory state object (`IntegrationState`) that is shared across all nodes:
-
-- **Purpose**: Store shared resources like API clients, caches, or connections
-- **Scope**: Available to all nodes and lifecycle hooks
-- **Lifecycle**: Exists only during integration runtime (not persisted)
-- **Usage**: Access via `state` parameter in node functions
-
-## Node Types Deep Dive
-
-### Trigger Nodes - Workflow Entry Points
-
-Trigger nodes are the **only** way to start a workflow. They listen for events and emit outputs when triggered.
-
-**Key Characteristics:**
-
-- Cannot be invoked by other nodes
-- Can invoke other nodes via their outputs
-- Must implement a `subscribe` function
-- Should return cleanup functions
-
-```typescript
-webhookTrigger: i.nodes.trigger({
-  // Optional: categorize your node in the UI
-  category: { path: ['External', 'HTTP'] },
-
-  // Optional: custom display name (defaults to key name in title case)
-  displayName: 'Webhook Receiver',
-
-  // Optional: description for UI and AI assistance
-  description: 'Receives HTTP requests and processes the payload',
-
-  // Inputs: configuration from user (not runtime data)
-  inputs: {
-    path: i.pins.data({
-      control: i.controls.text({
-        label: 'Webhook Path',
-        placeholder: '/webhook',
-        defaultValue: '/webhook',
-      }),
-    }),
-  },
-
-  // Outputs: data emitted when triggered
-  outputs: {
-    payload: i.pins.data({
-      displayName: 'Request Payload',
-      description: 'The parsed request body',
-    }),
-    headers: i.pins.data({
-      displayName: 'HTTP Headers',
-      description: 'Request headers as key-value pairs',
-    }),
-  },
-
-  // Subscribe function: sets up event listeners
-  subscribe({ next, webhook, inputs, state, variables }) {
-    // Register webhook handler
-    const unsubscribe = webhook.subscribe(async (req) => {
-      try {
-        const payload = await req.json();
-
-        // Emit outputs and start workflow
-        next({
-          payload,
-          headers: Object.fromEntries(req.headers),
-        });
-
-        // Return HTTP response
-        return new Response('OK', { status: 200 });
-      } catch (error) {
-        return new Response('Bad Request', { status: 400 });
-      }
-    });
-
-    // Always return cleanup function
-    return () => unsubscribe();
-  },
-}),
-
-// Timer trigger example
-timerTrigger: i.nodes.trigger({
-  inputs: {
-    interval: i.pins.data({
-      control: i.controls.text({
-        label: 'Interval (seconds)',
-        defaultValue: '60',
-      }),
-    }),
-  },
-  outputs: {
-    timestamp: i.pins.data(),
-  },
-  subscribe({ next, inputs }) {
-    const intervalMs = parseInt(inputs.interval) * 1000;
-
-    const timer = setInterval(() => {
-      next({ timestamp: new Date().toISOString() });
-    }, intervalMs);
-
-    return () => clearInterval(timer);
-  },
-}),
-```
-
-### Callable Nodes - Processing Units
-
-Callable nodes perform operations with side effects and explicitly control workflow execution.
-
-**Key Characteristics:**
-
-- Can be invoked by other nodes
-- Can invoke other nodes via exec pins
-- Must call `next()` to continue execution
-- Use `next()` to pass outputs
-
-```typescript
-apiCall: i.nodes.callable({
-  category: { path: ['API', 'HTTP'] },
-  displayName: 'Make API Call',
-  description: 'Performs HTTP requests to external APIs',
-
-  inputs: {
-    url: i.pins.data({
-      control: i.controls.text({
-        label: 'API Endpoint',
-        placeholder: 'https://api.example.com/data',
-      }),
-    }),
-    method: i.pins.data({
-      control: i.controls.select({
-        options: [
-          { value: 'GET', label: 'GET' },
-          { value: 'POST', label: 'POST' },
-          { value: 'PUT', label: 'PUT' },
-          { value: 'DELETE', label: 'DELETE' },
-        ],
-        placeholder: 'Select HTTP method',
-      }),
-    }),
-    headers: i.pins.data({
-      control: i.controls.expression({
-        defaultValue: { 'Content-Type': 'application/json' },
-      }),
-      optional: true, // Pin won't show initially but can be added
-    }),
-    body: i.pins.data({
-      control: i.controls.text({
-        rows: 4, // Multi-line text area
-        language: 'json', // Syntax highlighting
-      }),
-      optional: true,
-    }),
-  },
-
-  outputs: {
-    data: i.pins.data({
-      displayName: 'Response Data',
-      description: 'The parsed response body',
-    }),
-    status: i.pins.data({
-      displayName: 'HTTP Status',
-      description: 'The HTTP status code',
-    }),
-    headers: i.pins.data({
-      displayName: 'Response Headers',
-      description: 'Response headers as key-value pairs',
-    }),
-  },
-
-  async run({ inputs, next, state, ctx, variables, webhook }) {
-    // Access shared state (API client, etc.)
-    const client = state.httpClient;
-
-    // Perform the API call
-    const response = await client.fetch(inputs.url, {
-      method: inputs.method,
-      headers: inputs.headers,
-      body: inputs.body ? JSON.stringify(inputs.body) : undefined,
-    });
-
-    // Parse response
-    const data = await response.json();
-
-    // Pass outputs via next() - this continues the workflow
-    next({
-      data,
-      status: response.status,
-      headers: Object.fromEntries(response.headers),
-    });
-  },
-}),
-```
-
-### Pure Nodes - Computational Units
-
-Pure nodes are side-effect-free and compute outputs solely from inputs.
-
-**Key Characteristics:**
-
-- Cannot be invoked directly (only via data dependencies)
-- Cannot invoke other nodes
-- Automatically evaluated when their outputs are needed
-- Assign directly to `outputs` object
-
-```typescript
-dataTransform: i.nodes.pure({
-  category: { path: ['Data', 'Transform'] },
-  displayName: 'Transform Data',
-  description: 'Transforms input data using a specified mapping',
-
-  inputs: {
-    data: i.pins.data({
-      control: i.controls.expression({
-        placeholder: 'Enter data to transform',
-      }),
-      examples: [
-        {
-          title: 'Simple Object',
-          value: { name: 'John', age: 30 },
-        },
-        {
-          title: 'Array of Objects',
-          value: [
-            { id: 1, name: 'Alice' },
-            { id: 2, name: 'Bob' },
-          ],
-        },
-      ],
-    }),
-    mapping: i.pins.data({
-      control: i.controls.expression({
-        defaultValue: {
-          newName: 'data.name',
-          ageInMonths: 'data.age * 12',
-        },
-      }),
-    }),
-  },
-
-  outputs: {
-    result: i.pins.data({
-      displayName: 'Transformed Data',
-      description: 'The data after applying the mapping',
-    }),
-  },
-
-  run({ inputs, outputs, state, ctx, variables, webhook }) {
-    // Pure computation - no side effects
-    const { data, mapping } = inputs;
-
-    // Apply transformation
-    const result = applyMapping(data, mapping);
-
-    // Assign to outputs - no next() call needed
-    outputs.result = result;
-  },
-}),
-```
-
-## Pin System Deep Dive
-
-### Data Pins - Information Flow
-
-Data pins handle the flow of information between nodes.
-
-```typescript
-// Basic data pin
-i.pins.data()
-
-// Fully configured data pin
-i.pins.data({
-  // UI Configuration
-  displayName: 'User Input', // Custom label (default: key name)
-  description: 'The user-provided input value',
-
-  // Control for user input
-  control: i.controls.text({
-    label: 'Enter Value',
-    placeholder: 'Type here...',
-    defaultValue: 'Default text',
-  }),
-
-  // Schema validation (Standard Schema compatible)
-  schema: v.pipe(v.string(), v.minLength(1), v.maxLength(100)),
-
-  // Examples for users and AI
-  examples: [
-    { title: 'Simple Text', value: 'Hello World' },
-    { title: 'Template', value: '{{variable}}' },
-  ],
-
-  // Optional pins don't show initially
-  optional: true,
-}),
-
-// Method chaining with .with()
-i.pins.data().with({
-  displayName: 'Custom Label',
-  description: 'Additional configuration',
-}),
-```
-
-### Exec Pins - Execution Flow
-
-Exec pins control the execution flow in trigger and callable nodes.
-
-**Critical Rule: Only use exec pins for:**
-
-1. **Branching Logic**: Conditional execution paths
-2. **Iteration**: Processing arrays/collections
-3. **State Machines**: Complex state transitions
-
-```typescript
-// Branching example
-conditionalProcessor: i.nodes.callable({
-  inputs: {
-    condition: i.pins.data(),
-    trueValue: i.pins.data(),
-    falseValue: i.pins.data(),
-  },
-  outputs: {
-    // Exec pins for different paths
-    whenTrue: i.pins.exec({
-      outputs: {
-        value: i.pins.data(),
-      },
-    }),
-    whenFalse: i.pins.exec({
-      outputs: {
-        value: i.pins.data(),
-      },
-    }),
-  },
-  run({ inputs, next }) {
-    if (inputs.condition) {
-      next('whenTrue', { value: inputs.trueValue });
-    } else {
-      next('whenFalse', { value: inputs.falseValue });
-    }
-  },
-}),
-
-// Iteration example
-arrayProcessor: i.nodes.callable({
-  inputs: {
-    items: i.pins.data(),
-  },
-  outputs: {
-    // Exec pin for each iteration
-    forEach: i.pins.exec({
-      outputs: {
-        item: i.pins.data(),
-        index: i.pins.data(),
-      },
-    }),
-    // Exec pin when all items processed
-    completed: i.pins.exec({
-      outputs: {
-        count: i.pins.data(),
-      },
-    }),
-  },
-  run({ inputs, next }) {
-    const items = inputs.items;
-
-    // Process each item
-    items.forEach((item, index) => {
-      next('forEach', { item, index });
-    });
-
-    // Signal completion
-    next('completed', { count: items.length });
-  },
-}),
-```
-
-## Control System Deep Dive
-
-### Text Controls - String Input
-
-```typescript
-i.controls.text({
-  // Base properties
-  label: 'Input Label',
-  description: 'Help text for the user',
-  defaultValue: 'Default text',
-
-  // Text-specific properties
-  placeholder: 'Enter text here...',
-  sensitive: true, // Hides input value (passwords, API keys)
-  rows: 4, // Multi-line text area
-  language: 'json', // Syntax highlighting: 'plain', 'html', 'markdown'
-});
-```
-
-### Expression Controls - JavaScript Code
-
-```typescript
-i.controls.expression({
-  // Base properties
-  label: 'Expression',
-  description: 'JavaScript expression to evaluate',
-  defaultValue: { result: 'computed value' },
-
-  // Expression-specific properties
-  placeholder: 'Enter JavaScript expression...',
-  rows: 6, // Multi-line code editor
-});
-```
-
-### Select Controls - Dropdown Selection
-
-```typescript
-// Static options
-i.controls.select({
-  label: 'Choose Option',
-  placeholder: 'Select an option...',
-  options: [
-    {
-      value: 'option1',
-      label: 'Option 1',
-      description: 'Description of option 1'
-    },
-    {
-      value: 'option2',
-      label: 'Option 2',
-      description: 'Description of option 2'
-    },
-  ],
-}),
-
-// Dynamic options (only for node pins, not env variables)
-i.controls.select({
-  label: 'API Endpoint',
-  placeholder: 'Select endpoint...',
-  options: async ({ state }) => {
-    // Access shared state to fetch options
-    const endpoints = await state.apiClient.getEndpoints();
-    return endpoints.map(ep => ({
-      value: ep.url,
-      label: ep.name,
-      description: ep.description,
-    }));
-  },
-}),
-```
-
-### Switch Controls - Boolean Toggle
-
-```typescript
-i.controls.switch({
-  label: 'Enable Feature',
-  description: 'Toggle this feature on or off',
-  defaultValue: false,
-});
-```
-
-## Environment Variables
-
-Environment variables are secure configuration values that are set once and used across all nodes.
-
-```typescript
-export default i.integration({
-  env: {
-    API_KEY: i.env({
-      control: i.controls.text({
-        label: 'API Key',
-        description: 'Your service API key for authentication',
-        placeholder: 'sk-...',
-        sensitive: true, // Important: hides the value
-      }),
-      // Optional: validation schema
-      schema: v.pipe(v.string(), v.startsWith('sk-')),
-    }),
-
-    DEBUG_MODE: i.env({
-      control: i.controls.switch({
-        label: 'Debug Mode',
-        description: 'Enable debug logging',
-        defaultValue: false,
-      }),
-    }),
-
-    REGION: i.env({
-      control: i.controls.select({
-        options: [
-          { value: 'us-east-1', label: 'US East 1' },
-          { value: 'us-west-2', label: 'US West 2' },
-          { value: 'eu-west-1', label: 'EU West 1' },
-        ],
-      }),
-    }),
-  },
-
-  // Environment variables are available in start/stop hooks
-  async start({ state, env }) {
-    // Use environment variables to initialize shared resources
-    state.apiClient = new ApiClient({
-      apiKey: env.API_KEY,
-      region: env.REGION,
-      debug: env.DEBUG_MODE,
-    });
-  },
-
-  nodes: {
-    // Environment variables are NOT directly available in nodes
-    // Access them through shared state or pass as inputs
-  },
-});
-```
-
-## Error Handling
-
-**Golden Rule: Always throw errors, never try to handle them with exec pins or return values.**
-
-```typescript
-// Correct error handling in callable nodes
-async run({ inputs, next, state }) {
-  try {
-    const response = await state.apiClient.get(inputs.url);
-
-    // Check for API errors
-    if (!response.ok) {
-      throw new Error(`API request failed: ${response.status} ${response.statusText}`);
-    }
-
-    const data = await response.json();
-    next({ data });
-  } catch (error) {
-    // Let the error bubble up - the framework will handle it
-    throw error;
-  }
-}
-
-// Correct error handling in pure nodes
-run({ inputs, outputs }) {
-  if (!inputs.value) {
-    throw new Error('Value is required');
-  }
-
-  if (typeof inputs.value !== 'string') {
-    throw new Error('Value must be a string');
-  }
-
-  outputs.result = inputs.value.toUpperCase();
-}
-
-// Correct error handling in triggers
-subscribe({ next, webhook, state }) {
-  const unsubscribe = webhook.subscribe(async (req) => {
-    try {
-      const payload = await req.json();
-      next({ payload });
-      return new Response('OK');
-    } catch (error) {
-      // Handle webhook-specific errors
-      console.error('Webhook error:', error);
-      return new Response('Bad Request', { status: 400 });
-    }
-  });
-
-  return () => unsubscribe();
-}
-```
-
-## Advanced Patterns
-
-### State Management with Lifecycle Hooks
-
-```typescript
-export default i.integration({
-  env: {
-    DATABASE_URL: i.env({
-      control: i.controls.text({ sensitive: true }),
-    }),
-  },
-
-  async start({ state, env }) {
-    // Initialize shared resources
-    state.db = new Database(env.DATABASE_URL);
-    state.cache = new Map();
-
-    // Setup connections
-    await state.db.connect();
-
-    // Initialize other services
-    state.emailService = new EmailService();
-  },
-
-  async stop({ state }) {
-    // Clean up resources
-    if (state.db) {
-      await state.db.disconnect();
-    }
-
-    if (state.cache) {
-      state.cache.clear();
-    }
-  },
-
-  nodes: {
-    // Nodes can access shared state
-    dbQuery: i.nodes.callable({
-      inputs: {
-        query: i.pins.data(),
-      },
-      outputs: {
-        result: i.pins.data(),
-      },
-      async run({ inputs, next, state }) {
-        const result = await state.db.query(inputs.query);
-        next({ result });
-      },
-    }),
-  },
-});
-```
-
-### Complex Webhook Handling
-
-```typescript
-webhookProcessor: i.nodes.trigger({
-  inputs: {
-    secretKey: i.pins.data({
-      control: i.controls.text({
-        label: 'Webhook Secret',
-        sensitive: true,
-      }),
-    }),
-  },
-  outputs: {
-    verified: i.pins.exec({
-      outputs: {
-        payload: i.pins.data(),
-        signature: i.pins.data(),
-      },
-    }),
-    invalid: i.pins.exec(),
-  },
-
-  subscribe({ next, webhook, inputs }) {
-    const unsubscribe = webhook.subscribe(async (req) => {
-      try {
-        // Verify webhook signature
-        const signature = req.headers.get('X-Signature');
-        const payload = await req.text();
-
-        if (!verifySignature(payload, signature, inputs.secretKey)) {
-          next('invalid');
-          return new Response('Unauthorized', { status: 401 });
-        }
-
-        // Process verified webhook
-        const data = JSON.parse(payload);
-        next('verified', { payload: data, signature });
-
-        return new Response('OK');
-      } catch (error) {
-        next('invalid');
-        return new Response('Bad Request', { status: 400 });
-      }
-    });
-
-    return () => unsubscribe();
-  },
-}),
-```
-
-### Dynamic Options with Caching
-
-```typescript
-apiEndpointSelector: i.pins.data({
-  control: i.controls.select({
-    options: async ({ state }) => {
-      // Check cache first
-      if (state.endpointCache) {
-        return state.endpointCache;
-      }
-
-      // Fetch from API
-      const endpoints = await state.apiClient.getEndpoints();
-      const options = endpoints.map(ep => ({
-        value: ep.id,
-        label: ep.name,
-        description: `${ep.method} ${ep.path}`,
-      }));
-
-      // Cache results
-      state.endpointCache = options;
-
-      return options;
-    },
-  }),
-}),
-```
-
-## Type Safety and Inference
-
-The framework provides comprehensive TypeScript support:
-
-```typescript
-// Type inference from integration definition
-const myIntegration = i.integration({
-  nodes: {
-    processor: i.nodes.callable({
-      inputs: {
-        data: i.pins.data(),
-      },
-      outputs: {
-        result: i.pins.data(),
-      },
-      run({ inputs, next }) {
-        // inputs.data is properly typed
-        // next is properly typed
-        next({ result: inputs.data });
-      },
-    }),
-  },
-});
-
-// Extract types from integration
-type IntegrationOutput = typeof myIntegration.$infer;
-// IntegrationOutput.nodes.processor.inputs.data is typed
-// IntegrationOutput.nodes.processor.outputs.result is typed
-```
-
-## Development Best Practices
-
-1. **Use TypeScript**: The framework is built for TypeScript - use it
-2. **Descriptive Names**: Use clear, descriptive names for nodes, pins, and variables
-3. **Categories**: Organize nodes with categories for better UX
-4. **Documentation**: Add descriptions to nodes and pins for AI assistance
-5. **Examples**: Provide examples for complex data pins
-6. **State Management**: Use integration state for shared resources
-7. **Error Handling**: Always throw errors, never handle them with exec pins
-8. **Cleanup**: Always return cleanup functions from trigger subscriptions
-9. **Optional Pins**: Use optional pins to reduce UI clutter
-10. **Validation**: Use schema validation for robust data handling
-
-## Testing Guidelines
-
-```typescript
-// Test pure nodes easily
-import { describe, expect, it } from 'vitest';
-
-import { integration } from './my-integration';
-
-describe('Data Transform Node', () => {
-  it('should transform data correctly', () => {
-    const node = integration.nodes.dataTransform;
-    const outputs = {};
-
-    node.run({
-      inputs: { data: { name: 'John' }, mapping: { title: 'data.name' } },
-      outputs,
-      state: {},
-      ctx: {},
-      variables: {},
-      webhook: { url: 'http://test' },
-    });
-
-    expect(outputs.result).toEqual({ title: 'John' });
-  });
-});
-```
-
-This framework enables you to build powerful, type-safe integrations with clear separation of concerns and excellent developer experience.