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:

   # 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):

   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:

{
  "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:

{
  "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:

   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:

{
  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

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

Testing

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:

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
• Documentation: Handit Docs
• Email: [email protected]