n8n-nodes-handit/README.md

n8n community nodes for Handit tracing and prompt management

![Banner image](https://user-images.githubusercontent.com/10284570/173569848-c624317f-42b1-45a6-ab09-f0ea3c247648.png)

# n8n-nodes-handit

This is an n8n community node package that provides comprehensive Handit integration for workflow analytics and AI prompt management.

## Nodes Included

### 🔍 **Handit Tracing**
- **Workflow Data Collection**: Automatically collects input/output data from specified nodes in your workflow
- **API Integration**: Sends collected data to your Handit API endpoint for analysis
- **Flexible Configuration**: Configure which nodes to trace and add custom metadata
- **Error Handling**: Graceful error handling with detailed error reporting

### 🤖 **Handit Prompt Fetcher**
- **Production Prompt Management**: Fetch production-ready prompts from your Handit API
- **LLM Integration**: Automatically format prompts as variables for easy use in LLM nodes (GPT, Claude, etc.)
- **Multi-Environment Support**: Fetch prompts from different environments (production, staging, development)
- **Flexible Output**: Choose between individual variables, JSON objects, or both

## Installation

### Prerequisites

- n8n installed (version 0.190.0 or later)
- Node.js 18.17.0 or later

### Install the node

1. **For local development/testing:**
   ```bash
   # Clone this repository
   git clone <your-repo-url>
   cd n8n-nodes-handit
   
   # Install dependencies and build
   npm install
   npm run build
   
   # Link the package locally
   npm link
   
   # In your n8n installation directory
   npm link n8n-nodes-handit
   ```

2. **For production (when published to npm):**
   ```bash
   npm install n8n-nodes-handit
   ```

3. **Restart n8n** to load the new node.

## Configuration

### 1. Set up Handit API Credentials

1. In n8n, go to **Settings** > **Credentials**
2. Click **Add Credential** and search for "Handit API"
3. Configure:
   - **API Token**: Your Handit API authentication token
   - **Base URL**: Your Handit API base URL (default: `https://api.handit.com`)

### 2. Add Handit Nodes to Your Workflow

#### **Handit Tracing Node**
1. In your workflow, add the **Handit Tracing** node
2. Configure the node:
   - **API Endpoint**: The specific endpoint for tracing (default: `https://api.handit.com/trace`)
   - **Node Names**: Comma-separated list of node names to trace (leave empty for default)
   - **Additional Fields**: Optional metadata like Workflow ID, User ID, Environment

#### **Handit Prompt Fetcher Node**
1. Add the **Handit Prompt Fetcher** node at the beginning of your workflow
2. Configure the node:
   - **API Endpoint**: The endpoint for fetching prompts (default: `https://api.handit.com/prompts`)
   - **Agent Name/Slug**: The identifier of your agent/assistant
   - **Output Format**: Choose how to format the prompts (Individual Variables, JSON Object, or Both)
   - **Variable Prefix**: Optional prefix for variable names (e.g., "prompt_")
   - **Additional Options**: Environment, version, cache duration

## Usage

### Handit Tracing - Basic Usage

1. Add the Handit Tracing node to your workflow
2. Connect it to receive data from previous nodes
3. Configure your API credentials
4. The node will automatically collect data from specified nodes and send it to your Handit API

### Handit Prompt Fetcher - Basic Usage

1. Add the Handit Prompt Fetcher node at the start of your workflow
2. Configure the agent slug and output format
3. Connect it to your LLM nodes
4. Use the fetched prompts in your LLM nodes with expressions like `{{ $gpt4_prompt }}` or `{{ $claude_prompt }}`

### Advanced Configuration

#### Node Names
Specify which nodes to trace by providing a comma-separated list:
```
Telegram Trigger, Edit Fields, AI Agent, Telegram
```

If left empty, the node will use a default set of common node names.

#### Additional Fields
Add custom metadata to your traces:
- **Workflow ID**: Custom identifier for your workflow
- **User ID**: User identifier for user-specific tracing
- **Environment**: Deployment environment (Development, Staging, Production)

### Example Workflows

#### **Workflow with Prompt Fetcher + LLM + Tracing**
```
[Telegram Trigger] → [Handit Prompt Fetcher] → [OpenAI GPT] → [Handit Tracing] → [Telegram]
```

1. **Handit Prompt Fetcher** fetches production prompts for your agent
2. **OpenAI GPT** uses the fetched prompt: `{{ $gpt4_prompt }}` or `{{ $system_prompt }}`
3. **Handit Tracing** logs the entire workflow execution
4. **Telegram** sends the response back

#### **API Response from Prompt Fetcher**

If your API returns:
```json
{
  "prompts": {
    "gpt4": "You are a helpful assistant specialized in customer support...",
    "claude": "You are an AI assistant focused on providing accurate information...",
    "system": "Always be polite and professional in your responses."
  }
}
```

The node creates these variables:
- `$gpt4` and `$gpt4_prompt`
- `$claude` and `$claude_prompt` 
- `$system` and `$system_prompt`

#### **Tracing Workflow Example**
```
[Telegram Trigger] → [Edit Fields] → [AI Agent] → [Handit Tracing] → [Telegram]
```

The Handit Tracing node will collect data from all specified nodes and send a payload like:

```json
{
  "workflowData": [
    {
      "slug": "Telegram Trigger",
      "input": {
        "nodeName": "Telegram Trigger",
        "timestamp": "2024-01-01T12:00:00.000Z"
      },
      "output": {
        "message": "Hello from Telegram"
      }
    },
    {
      "slug": "Edit Fields",
      "input": {
        "nodeName": "Edit Fields",
        "timestamp": "2024-01-01T12:00:00.000Z"
      },
      "output": {
        "processedMessage": "Processed: Hello from Telegram"
      }
    }
  ],
  "timestamp": "2024-01-01T12:00:00.000Z",
  "executionId": "exec_123",
  "workflowId": "workflow_456",
  "environment": "production"
}
```

## Comparison with Manual Implementation

### Before (Manual Implementation)
You needed two separate nodes:

1. **Code Node** with custom JavaScript:
   ```javascript
   const nodes = ['Telegram Trigger', 'Edit Fields', 'AI Agent', 'Telegram'];
   const workflowDataArray = [];
   
   // Complex logic to collect workflow data...
   // Expression resolution...
   // Data transformation...
   
   return { workflowData: workflowDataArray };
   ```

2. **HTTP Request Node** to send data to Handit API

### After (Handit Tracing Node)
Single node that:
- ✅ Automatically collects workflow data
- ✅ Handles API authentication
- ✅ Provides user-friendly configuration
- ✅ Includes error handling
- ✅ Supports custom metadata
- ✅ Maintains the same data structure you're used to

## API Reference

### Request Format

The node sends POST requests to your configured endpoint with the following structure:

```typescript
{
  workflowData: Array<{
    slug: string;           // Node name
    input: {
      nodeName: string;
      timestamp: string;
      previousSteps?: object;
      [key: string]: any;   // Additional fields
    };
    output: object;         // Node output data
    error?: string;         // Error message if node failed
  }>;
  timestamp: string;        // Execution timestamp
  executionId: string;      // n8n execution ID
  workflowId: string;       // Workflow identifier
  [key: string]: any;       // Additional fields from configuration
}
```

### Authentication

The node uses Bearer token authentication:
```
Authorization: Bearer <your-api-token>
```

## Development

### Building from Source

```bash
git clone <your-repo-url>
cd n8n-nodes-handit
npm install
npm run build
```

### Testing

```bash
npm run lint        # Check code style
npm run format      # Format code
```

### Project Structure

```
n8n-nodes-handit/
├── nodes/
│   └── HanditTracing/
│       ├── HanditTracing.node.ts      # Main node implementation
│       ├── HanditTracing.node.json    # Node metadata
│       └── handit.svg                 # Node icon
├── credentials/
│   └── HanditApi.credentials.ts       # API credentials
├── package.json                       # Package configuration
└── README.md                          # This file
```

## Troubleshooting

### Common Issues

1. **Node not appearing in n8n**
   - Ensure you've restarted n8n after installation
   - Check that the package is properly linked/installed

2. **Authentication errors**
   - Verify your API token is correct
   - Check that the base URL is accessible

3. **Data collection issues**
   - Ensure the node names match exactly (case-sensitive)
   - Check that previous nodes have executed successfully

### Debug Mode

Enable debug logging by setting the environment variable:
```bash
N8N_LOG_LEVEL=debug
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## License

MIT License - see LICENSE file for details.

## Support

For issues and questions:
- GitHub Issues: [Create an issue](https://github.com/handit/n8n-nodes-handit/issues)
- Documentation: [Handit Docs](https://docs.handit.com/integrations/n8n)
- Email: support@handit.com