n8n-nodes-hubitat/README.md

n8n nodes to integrate with Hubitat smart home platform

# n8n-nodes-hubitat
This n8n integration allows you to interact with your Hubitat devices directly from your n8n workflows.

## Installation
### Method 1: Local Installation
```bash
npm install n8n-nodes-hubitat
```
### Method 2: Development Installation
```bash
git clone https://github.com/sboily/n8n-nodes-hubitat.git
cd n8n-nodes-hubitat
npm install
npm run build
npm link
```
Then, in your n8n installation folder:
```bash
cd ~/.n8n
npm link n8n-nodes-hubitat
```
### Compatibility Note
This node is compatible with n8n version 1.0.0 and above. For older versions of n8n, please check the releases for a compatible version.

## Configuration
### Prerequisites
1. A Hubitat hub configured and accessible on your network
2. The Maker API app installed and configured on your Hubitat
3. An Access Token for the Maker API

### Credential Setup
In n8n, add a new credential of type "Hubitat API" with:
- **Hubitat Host**: The complete URL of your Hubitat (e.g., `http://192.168.0.100`)
- **App ID**: The ID of your Maker API application
- **Access Token**: The access token generated by the Maker API application

## Features

### Hubitat Node
This node allows you to:
- **Get All Devices**: Retrieve a list of all available devices
- **Get a Specific Device**: Get details of a particular device
- **Send Command**: Send commands to Hubitat devices

### Hubitat Trigger
This node allows you to:
- **Listen for Events**: Create a webhook endpoint that Hubitat can send events to
- **Filter by Event Type**: Choose to listen for all events, device events, mode events, or location events
- **Filter by Device**: Optionally filter device events by specific devices
- **Custom Event Types**: Listen for custom event types from your Hubitat hub

### Hubitat Tool
This node allows you to expose Hubitat functionalities as a tool for AI agents:
- **Multiple Capabilities Support**: List devices, get device details, send commands, and manage modes

## Usage Examples
### Example 1: Get the status of all devices
1. Add a trigger node (such as "Cron" to execute at regular intervals)
2. Connect it to a "Hubitat" node
3. Configure the Hubitat node:
   - Resource: Device
   - Operation: Get All

### Example 2: Turn on a light
1. Add a trigger node (such as "Webhook" for an external API)
2. Connect it to a "Hubitat" node
3. Configure the Hubitat node:
   - Resource: Device
   - Operation: Send Command
   - Device: [Select your light from dropdown]
   - Command: on

### Example 3: Automation triggered by Hubitat events
1. Add a "Hubitat Trigger" node as the start of your workflow
2. Configure the trigger:
   - Event Type: Device Event
   - Filter by Device: Yes
   - Devices: [Select devices to monitor]
3. Add subsequent nodes to process the events and perform actions

### Example 4: Create a mode-based automation
1. Add a "Hubitat Trigger" node
2. Configure it to listen for "Mode Event"
3. Connect it to a "Switch" node to perform different actions based on the mode value
4. Add action nodes for each mode scenario

## AI Agent Integration Example
### Example 1: Create an AI Agent to Control Hubitat
1. Add a "Hubitat Tool" node
2. Configure it with the desired capabilities:
   - Tool Name: hubitat
   - Capabilities: List Devices, Get Device, Send Command
3. The AI can now control your Hubitat devices using natural language


## Troubleshooting
- **Connection Issues**: Verify that the hub URL is correct and that the Maker API is properly configured
- **Authentication Errors**: Make sure your App ID and Access Token are correct
- **Command Not Working**: Check that the device ID exists and the command is supported by that device
- **Webhook Not Triggering**: Verify that the webhook URL is correctly configured in your Hubitat Maker API settings
- **Build Errors**: If you encounter build errors:
  - Make sure you're using compatible versions of n8n-core and n8n-workflow
  - Check the console output for specific error messages
  - Try running with `npm run build -- --skipLibCheck true` if you have type declaration issues

## Development
### Building the module
```bash
npm run build
```
### Linting
```bash
npm run lint
```
### Fix linting issues
```bash
npm run lintfix
```

## Testing
This package includes comprehensive unit and integration tests to ensure reliability in production environments.

### Running tests
Run all tests:
```bash
npm test
```
Run only unit tests:
```bash
npm run test:unit
```
Run only integration tests:
```bash
npm run test:integration
```
Generate test coverage report:
```bash
npm run test:coverage
```

### Test architecture
The tests are organized as follows:
- **Unit tests**: Test individual components in isolation with mocks
  - `test/unit/nodes/`: Tests for node functionality
  - `test/unit/credentials/`: Tests for credential handling
- **Integration tests**: Test components working together
  - `test/integration/`: End-to-end testing of nodes working together
- **Mocks and test data**: 
  - `test/mocks/`: Mock implementations and test data

### Continuous Integration
For production deployments, we recommend setting up a CI pipeline that:
1. Builds the package
2. Runs all tests
3. Checks code coverage
4. Performs linting

### Dealing with Type Errors
If you encounter type errors during compilation:
1. Make sure you have the correct dependencies installed:
   ```bash
   npm install request request-promise-native @n8n_io/riot-tmpl --save
   npm install @types/request @types/request-promise-native --save-dev
   ```
2. The repository includes type declarations in the `src/types` folder to address common typing issues with n8n dependencies.

## Project Structure
```
n8n-nodes-hubitat/
├── src/
│   ├── nodes/
│   │   └── Hubitat/
│   │       ├── Hubitat.node.ts           # Main node for Hubitat API operations
│   │       ├── HubitatTrigger.node.ts    # Webhook trigger node for Hubitat events
│   │       └── hubitat.svg               # Icon for the nodes
│   ├── credentials/
│   │   └── HubitatApi.credentials.ts     # Credential definition for Hubitat API
│   └── types/
│       └── custom.d.ts                   # Custom type declarations
├── test/
│   ├── unit/                             # Unit tests
│   ├── integration/                      # Integration tests
│   └── mocks/                            # Test mocks and fixtures
├── .github/                              # GitHub configuration (actions, templates)
├── package.json                          # Project dependencies and scripts
├── tsconfig.json                         # TypeScript configuration
├── jest.config.js                        # Jest test configuration
├── .eslintrc.js                          # ESLint configuration
├── CODE_OF_CONDUCT.md                    # Community guidelines
└── index.js                              # Main entry point
```

## License
MIT

## Credits
This node is based on the [node-red-contrib-hubitat](https://github.com/fblackburn1/node-red-contrib-hubitat) project, converted for use with n8n.