@xentom/integration-framework 0.0.0 → 0.0.2

package/CLAUDE.md

@@ -1,836 +1,837 @@
-# 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, it, expect } 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.
+# 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.