npm package: @ninjadoc-ai/n8n
Description: Actions to access Ninjadoc AI API
Author: Ninjadoc AI
Latest version: 1.0.2

# @ninjadoc-ai/n8n

N8n integration package for Ninjadoc AI - the first Document Q&A platform that extracts structured data from documents using natural language questions and AI-powered extraction with coordinate proof.

## Node

### Ninjadoc AI
**Action Node** - Complete document processing solution with three powerful actions in one unified interface.

#### Actions

**1. Ask Question**
Ask natural language questions about documents and get answers with coordinate proof.

**Inputs:**
- Question (natural language): "What is the total invoice amount?"
- Document Source: Binary data from previous node or file upload
- Include Coordinates: Get bounding box coordinates showing where answers were found

**Outputs:**
- Answer with confidence score and optional coordinate proof
- Page candidates for multi-page documents

**2. Process with Template**
Extract multiple fields from documents using pre-configured processor templates.

**Inputs:**
- Processor ID: UUID of your processor template from Ninjadoc dashboard
- Document Source: Binary data from previous node or file upload

**Outputs:**
- Structured data extraction with all defined fields
- Confidence scores and coordinates for each field
- Automatic polling for job completion

**3. Convert to Markdown**
Transform documents into markdown format with AI-powered structure detection.

**Inputs:**
- Document Source: Binary data from previous node or file upload
- Use AI Parse: Enable intelligent structure detection for tables and lists

**Outputs:**
- Clean markdown representation of document content
- Processing metadata and timing information

#### Output Formats

Choose how you want response data formatted:

- **Full Response**: Complete API response with all metadata and processing details
- **Essential Data Only**: Extracted values, confidence scores, and coordinates without extra metadata
- **Answer Only**: Just the extracted text values without additional information
- **Structured Data**: Flat key-value object optimized for further processing (ideal for batch operations)

#### Key Features

- **Zero Training Required**: Works out-of-the-box without model training or setup
- **Layout-Aware Processing**: Handles document variations without rigid templates
- **Coordinate Proof**: Get exact bounding box coordinates showing where answers were found
- **Developer-First API**: Clean integration with structured JSON responses
- **Automatic Retry Logic**: Built-in retry with exponential backoff for reliability
- **Multiple Document Sources**: Support for binary data from previous nodes or direct file upload
- **Flexible Output Formats**: Choose the data format that best fits your workflow

## Credentials

### Ninjadoc API
Required credentials for the node:
- **API Key**: Your Ninjadoc API key from the dashboard
- **Base URL**: API base URL (default: https://api.ninjadoc.ai)

## Installation

1. Install the package:
```bash
npm install @ninjadoc-ai/n8n
```

2. Configure credentials in n8n:
   - Add Ninjadoc API credentials
   - Enter your API key and base URL

3. Add the Ninjadoc AI node to your workflows

## Usage Examples

### Simple Q&A Workflow
1. **Read Binary File**: Load a PDF document
2. **Ninjadoc AI**: Ask question action with natural language query
3. **Process results**: Use extracted data in subsequent nodes

### Batch Processing Workflow
1. **Read Binary File**: Load a PDF document
2. **Ninjadoc AI**: Process with template action using processor ID
3. **Auto-polling**: Node automatically waits for completion
4. **Extract structured data**: Get all fields with confidence scores

### Document Conversion Workflow
1. **Read Binary File**: Load a PDF document
2. **Ninjadoc AI**: Convert to markdown action with AI parsing
3. **Save or process**: Use markdown content in documentation workflows

## Error Handling

The unified node includes comprehensive error handling:
- **Automatic Retry Logic**: Exponential backoff with jitter for network issues
- **Rate Limit Handling**: Intelligent retry on 429 responses
- **Timeout Management**: Configurable timeouts with graceful failure
- **Continue on Fail**: Option to continue workflow execution on errors
- **Detailed Error Messages**: Specific guidance for different error types
- **Input Validation**: PDF validation and file size checks

## Advanced Features

### Coordinate Integration
When coordinates are enabled, you get both raw pixel coordinates and percentage-based coordinates for easy UI integration:

```json
{
  "coordinates": [{
    "text": "Total: $1,234.56",
    "page": 1,
    "confidence": 0.95,
    "bbox_raw": [100, 200, 300, 220],
    "bbox_percentage": {
      "x1": 12.5, "y1": 25.0,
      "x2": 37.5, "y2": 27.5
    }
  }]
}
```

### Auto-Polling for Async Operations
For processor template operations, the node automatically handles job polling:
- Starts with 2-second intervals
- Exponential backoff up to 30 seconds
- 5-minute maximum processing time
- Real-time status updates in execution log

### Document Source Flexibility
- **Binary Data**: Seamlessly integrate with file reading nodes
- **File Upload**: Direct file path support for development and testing
- **Validation**: Automatic PDF validation and size checking (10MB limit)