@ev1lc0rp/n8n-nodes-ninjaone/CLAUDE.md

Professional NinjaOne RMM integration for n8n with complete ticketing and device management

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is an n8n community node package for NinjaOne RMM integration. It provides professional-grade ticketing and device management capabilities through the NinjaOne API using OAuth2 authentication.

## Development Commands

### Build and Development
- `npm run build` - Build the project (removes dist, compiles TypeScript, builds icons)
- `npm run dev` - Development mode with TypeScript watch
- `npm run test` - Run Jest tests

### Code Quality
- `npm run lint` - Run ESLint on nodes, credentials, and package.json
- `npm run lintfix` - Auto-fix ESLint issues
- `npm run format` - Format code with Prettier

### Publishing
- `npm run prepublishOnly` - Pre-publish checks (build + lint with strict config)

## Architecture

### Core Components

**Main Node**: `/nodes/NinjaOne/NinjaOne.node.ts`
- Central n8n node implementation
- Handles three main resources: Device, Ticket, Organization
- Uses modular operation definitions from `./operations/`

**Operations Structure**: `/nodes/NinjaOne/operations/`
- `device.ts` - Device management operations (get, list, activities, alerts, custom fields, etc.)
- `ticket.ts` - Complete CRUD ticketing operations (create, read, update, comment)
- `organization.ts` - Organization management
- `index.ts` - Exports all operations

**Authentication**: `/credentials/NinjaOneOAuth2Api.credentials.ts`
- OAuth2 Client Credentials flow implementation
- Regional endpoint support (api.ninjaone.com, eu-api.ninjaone.com)
- Requires scope: "monitoring management"

### API Integration Patterns

The node follows n8n community standards:
- Uses `INodeTypeDescription` for UI definition
- Implements `requestDefaults` for common API settings
- Supports regional base URLs via credentials
- Uses display options to show/hide fields based on resource/operation

### Key Implementation Details

**Ticket Management**:
- Field names match real API responses ("summary" not "subject")
- Status mapping: 1000 (New), 2000 (Open), 3000 (Waiting), 4000 (Hold)
- Severity levels: NONE, MINOR, MODERATE, MAJOR, CRITICAL
- Supports parent/sub-ticket relationships, time tracking, CC lists

**Device Operations**:
- Comprehensive device info retrieval
- Hardware inventory (disks, processors, network interfaces)
- Software management and patch tracking
- Policy overrides and compliance status

## Testing

Tests are located in `__tests__/` directory:
- `NinjaOne.node.test.ts` - Main node tests
- `device.test.ts` - Device operation tests
- `ticket.test.ts` - Ticket operation tests
- `organization.test.ts` - Organization operation tests

Jest configuration in `jest.config.js` with TypeScript support via ts-jest.

## TypeScript Configuration

Strict TypeScript settings in `tsconfig.json`:
- Target: ES2019
- Strict mode enabled
- Compiles to `./dist/` directory
- Includes source maps and declarations

## Package Structure

Built for n8n community node standards:
- Main entry: `dist/nodes/NinjaOne/NinjaOne.node.js`
- Credentials: `dist/credentials/NinjaOneOAuth2Api.credentials.js`
- Icon files and documentation included in distribution

## Important Notes

- Always verify OAuth2 credentials have correct regional endpoints
- Ticket operations require proper field validation based on real API responses
- Time tracking uses seconds (not minutes/hours)
- All API calls use JSON content-type with Accept headers
- The node supports being used as a tool (`usableAsTool: true`)