// BEFORE: Insufficient validation led to NaN IDs
if (!tableId || isNaN(tableId)) { ... }

// AFTER: Robust validation against ALL NaN sources
if (resourceLocator === null || resourceLocator === undefined || 
    resourceLocator === 'null' || resourceLocator === 'undefined' ||
    resourceLocator === 'NaN' || 
    (typeof resourceLocator === 'number' && isNaN(resourceLocator))) {
    throw new Error('Resource Locator is required but not set or invalid');
}
Hardened Validation in Load Options

    ✅ Table ID Extraction: Robust handling of __rl resource locators

    ✅ Column/View Loading: Validation prevents /tables/NaN/columns requests

    ✅ Error Messages: Helpful debugging information

    ✅ String-to-Number Conversion: Safe parseInt() with validation

🤖 AI-Agent Optimized ⭐

Unique: This is the first n8n community node specifically optimized for AI agents!
Problem Solved:

Standard n8n nodes use displayOptions to dynamically hide parameters. AI agents can't see these.
Solution: AI-Friendly Operations

    ✅ All parameters visible at once

    ✅ No UI dependencies for AI agents

    ✅ String-based IDs instead of dropdown navigation

    ✅ Flat parameter structure without nesting

    ✅ Robust NaN protection in v2.4.7

Available AI-Friendly Operations:
Column Management (AI-Optimized)

// Optimized for AI agents - ALL parameters visible
Operation: "Create Column (AI-Friendly)"
{
  "tableIdAI": "123",
  "columnType": "selection", 
  "columnTitle": "Status",
  "columnMandatory": true,

  // All type-specific parameters available at once:
  "selectionOptionsAI": "[\"Open\", \"In Progress\", \"Done\"]",
  "selectionDefaultAI": "Open",
  "selectionMultipleAI": false,

  // Text parameters (ignored for other types):
  "textSubtypeAI": "line",
  "textMaxLengthAI": 255
  // ... all other parameters available
}

// Full updates possible
Operation: "Update Column (AI-Friendly)"
{
  "columnIdAI": "456",
  "columnType": "text",           // Change type
  "columnTitle": "New Name",      // Change title
  "textSubtypeAI": "long",        // Text-specific
  "textMaxLengthAI": 500          // Change max length
  // Only relevant parameters are used
}

Benefits for AI Agents:

    🔍 Parameter transparency: 24 parameters visible at once

    🎯 Autonomous operations: No UI interaction required

    🚀 String-based inputs: No dropdowns, maximum flexibility

    🛡️ NaN protection: Robust validation prevents API errors (v2.4.7)

    ↩️ Backward compatible: Human UI remains unchanged

📊 Feature Overview & Test Status
🏗️ Table Operations

    ✅ Get all tables: Tested, production-ready

    ✅ Get table: Tested, production-ready

    ⚠️ Create table: Implemented, untested

    ⚠️ Update table: Implemented, untested

    ⚠️ Delete table: Implemented, untested

📋 Column Management ✅ FULLY TESTED & AI-OPTIMIZED

Standard operations:

    ✅ Get all columns: Tested, production-ready

    ✅ Get column: Tested, production-ready

    ✅ Create column: Tested, production-ready

    ⚠️ Update column: Implemented, untested

    ⚠️ Delete column: Implemented, untested

🤖 AI-Friendly Operations:

    ✅ Create Column (AI-Friendly): Tested, production-ready - 23 parameters visible

    ⚠️ Update Column (AI-Friendly): Implemented, untested - 24 parameters for full updates

5 fully supported column types:

    ✅ Text: Tested - pattern validation, max length, subtypes (single/multiline)

    ✅ Number: Tested - min/max, decimals, prefix/suffix, validation

    ✅ DateTime: Tested - default date, flexible input formats

    ✅ Selection: Tested - dropdown options, default values, multi-select

    ✅ UserGroup: Tested - user/group selection, multi-select, teams

🎯 Row Operations

    ✅ Get all rows: Tested, production-ready

    ✅ Get row: Tested, production-ready (client-side filtering)

    ✅ Create row: Tested, production-ready

    ⚠️ Update row: Implemented, untested

    ❌ Delete row: Not supported by Nextcloud Tables API

Advanced row features (untested):

    ⚠️ Smart pagination: Optimized for 1-1000 rows

    ⚠️ 11 filter operators: =, !=, >, >=, <, <=, LIKE, starts_with, ends_with, is_empty, is_not_empty

    ⚠️ Multi-column sorting: Priority-based sorting

    ⚠️ Full-text search: Case-sensitive/insensitive, column-specific

    ✅ Automatic validation: Column-based data formatting

📋 Views Management

    ✅ Get views: Tested, production-ready

    ✅ Create view: Tested, production-ready

    ⚠️ Get view (single): Implemented, untested

    ⚠️ Update view: Implemented, untested

    ⚠️ Delete view: Implemented, untested

    ⚠️ Get rows from view: Implemented, untested

🤝 Collaboration Features

    ✅ Get shares: Tested, production-ready

    ✅ Create share: Tested, production-ready (users & groups)

    ⚠️ Update share: Implemented, untested

    ⚠️ Delete share: Implemented, untested

    ✅ Get users/groups: Tested, production-ready

📥 CSV Import ⚠️ UNTESTED

    ⚠️ Flexible options: Header detection, delimiter selection

    ⚠️ Column mapping: Automatic or manual mapping

    ⚠️ Data type conversion: Auto, text, number, datetime, boolean

    ⚠️ Import status: Monitoring and error handling

🌐 App-Context Integration ⚠️ UNTESTED

    ⚠️ Context navigation: Seamless Nextcloud app integration

    ⚠️ Context tables: Filtered views by app context

    ⚠️ Context pages: App page management

## Installation

```bash
npm install n8n-nodes-nextcloud-tables

Restart n8n to load the new node.
Configuration
Credentials

Create new credentials of type Nextcloud Tables API:

    Nextcloud URL: Full URL (e.g. https://cloud.example.com)

    Username: Your Nextcloud username

    Password: App password (recommended) or normal password

🔒 Security Tip: Use App Passwords:

    Nextcloud → Settings → Security → App Passwords

    Create a new app password for n8n

🤖 AI-Agent Usage Examples
Create Column (AI-Friendly)

{
  "resource": "Column",
  "operation": "Create Column (AI-Friendly)",
  "tableIdAI": "123",
  "columnType": "selection",
  "columnTitle": "Project Status", 
  "columnDescription": "Current status of the project",
  "columnMandatory": true,
  "selectionOptionsAI": "[\"Planned\", \"In Progress\", \"Testing\", \"Done\", \"Archived\"]",
  "selectionDefaultAI": "Planned",
  "selectionMultipleAI": false
}

Update Column (AI-Friendly)

{
  "resource": "Column", 
  "operation": "Update Column (AI-Friendly)",
  "columnIdAI": "456",
  "columnTitle": "Advanced Project Status",
  "selectionOptionsAI": "[\"Backlog\", \"Sprint\", \"Review\", \"Done\", \"Cancelled\"]",
  "selectionDefaultAI": "Backlog"
}

Various Column Types for AI Agents

// Create Text Column
{
  "columnType": "text",
  "columnTitle": "Description",
  "textSubtypeAI": "long",
  "textMaxLengthAI": 1000,
  "textPatternAI": "^[A-Za-z0-9\\s]+$"
}

// Create Number Column  
{
  "columnType": "number",
  "columnTitle": "Budget",
  "numberMinAI": 0,
  "numberMaxAI": 100000,
  "numberDecimalsAI": 2,
  "numberPrefixAI": "€"
}

// Create User/Group Column
{
  "columnType": "usergroup", 
  "columnTitle": "Responsible",
  "usergroupTypeAI": "user",
  "usergroupMultipleAI": false
}

Human vs. AI-Agent Comparison

// HUMAN (UI-optimized) - Parameters appear dynamically
Operation: "Create Column"
Table: [Dropdown Selection]
Type: "Selection" 
// → Then type-specific parameters appear

// AI-AGENT (AI-optimized) - All parameters visible
Operation: "Create Column (AI-Friendly)"  
// → ALL 23 parameters immediately visible and usable
// → String-based inputs instead of dropdowns
// → Maximum flexibility for autonomous execution

🔧 Advanced Usage
Advanced Row Query with Filters

{
  "resource": "Row",
  "operation": "Get All Rows",
  "source": "table",
  "tableId": "123",
  "useFiltering": true,
  "filters": [
    {
      "columnId": "5",
      "operator": "EQ", 
      "value": "Active"
    },
    {
      "columnId": "8",
      "operator": "GT",
      "value": "2024-01-01"
    }
  ],
  "useSorting": true,
  "sorting": [
    {
      "columnId": "10",
      "direction": "DESC"
    }
  ]
}

CSV Import with Column Mapping

{
  "resource": "Import",
  "operation": "Import CSV to Table",
  "tableId": "123",
  "csvData": "[Binary CSV Data]",
  "hasHeader": true,
  "delimiter": ";",
  "columnMapping": [
    {
      "csvColumn": "Customer Name",
      "tableColumn": "1",
      "dataType": "text"
    },
    {
      "csvColumn": "Created Date", 
      "tableColumn": "2",
      "dataType": "datetime"
    }
  ]
}

📊 Full API Coverage
✅ Implemented Endpoints

    Tables: /tables/* (full CRUD)

    Rows: /tables/{id}/rows, /views/{id}/rows (full CRUD except DELETE*)

    Views: /tables/{id}/views, /views/{id} (full CRUD)

    Columns: /tables/{id}/columns, /columns/{id} (full CRUD + AI-friendly)

    Shares: /tables/{id}/shares, /shares/{id} (full CRUD)

    Import: /tables/{id}/import (POST + status monitoring)

    Context: /contexts/* (GET operations)

*Note: Row DELETE is not supported by the Nextcloud Tables API
🔧 Compatibility

    Nextcloud: 28+ (tested)

    Tables App: 0.6+ (tested)

    n8n: 1.0+ (tested)

🛠️ Technical Details

    API Version: Hybrid v1/v2 (optimized per operation)

    Authentication: Basic Auth with app-password support

    Error Handling: 10 HTTP status codes with specific messages

    Retry Logic: 3 attempts with exponential backoff

    Validation: Column-based real-time validation

Development & Testing
Setup

npm install          # Install dependencies
npm run build        # Compile TypeScript  
npm run dev          # Development mode
npm run lint         # Lint code
npm run format       # Format code

Project Structure

nodes/NextcloudTables/
├── NextcloudTables.node.ts           # Main node
├── descriptions/                     # UI definitions
│   ├── column.ts     ← AI-OPTIMIZED
│   ├── table.ts      ├── row.ts
│   ├── view.ts       ├── share.ts  
│   ├── import.ts     └── context.ts
├── handlers/                         # Business logic
│   ├── column.handler.ts ← AI-FRIENDLY LOGIC
│   └── *.handler.ts
├── helpers/                          # Core utilities
│   ├── api.helper.ts                 # HTTP + error handling
│   ├── data.formatter.ts             # Validation
│   └── node.methods.ts               # Dynamic dropdowns
└── interfaces/                       # TypeScript types

🛠️ Troubleshooting
Logging & Debugging

🔍 Improved Log Labeling (New in v2.4.8)
All node logs are now clearly labeled for better grepping:

# All Nextcloud Tables node logs
grep "N8N-NEXTCLOUD-TABLES" /path/to/n8n/logs

# Only API errors
grep "N8N-NEXTCLOUD-TABLES.*API-ERROR" /path/to/n8n/logs

# Only validation errors
grep "N8N-NEXTCLOUD-TABLES.*VALIDATION-ERROR" /path/to/n8n/logs

# Operation-specific logs
grep "N8N-NEXTCLOUD-TABLES.*OPERATION-" /path/to/n8n/logs

# Resource Locator debugging
grep "N8N-NEXTCLOUD-TABLES.*RESOURCE-VALIDATION" /path/to/n8n/logs

Log Categories:

    [N8N-NEXTCLOUD-TABLES] [DEBUG] [API-REQUEST] - API requests

    [N8N-NEXTCLOUD-TABLES] [DEBUG] [API-RESPONSE] - API responses

    [N8N-NEXTCLOUD-TABLES] [INFO] [OPERATION-START] - Operation started

    [N8N-NEXTCLOUD-TABLES] [INFO] [OPERATION-SUCCESS] - Operation successful

    [N8N-NEXTCLOUD-TABLES] [ERROR] [OPERATION-ERROR] - Operation failed

    [N8N-NEXTCLOUD-TABLES] [WARN] [VALIDATION-ERROR] - Validation error

    [N8N-NEXTCLOUD-TABLES] [DEBUG] [RESOURCE-VALIDATION] - Resource locator debugging

Example Logs:

2024-01-15T10:30:45.123Z [N8N-NEXTCLOUD-TABLES] [INFO] [OPERATION-START] table.getAll
2024-01-15T10:30:45.124Z [N8N-NEXTCLOUD-TABLES] [DEBUG] [API-REQUEST] GET /tables
2024-01-15T10:30:45.234Z [N8N-NEXTCLOUD-TABLES] [DEBUG] [API-RESPONSE] GET /tables -> 200 (110ms)
2024-01-15T10:30:45.235Z [N8N-NEXTCLOUD-TABLES] [INFO] [OPERATION-SUCCESS] table.getAll completed (112ms)

### Common Issues

**401 Unauthorized**  
✅ **Solution**: Use an app password, check permissions.

**AI Agent can't see parameters**  
✅ **Solution**: Use AI-Friendly operations (`createAIFriendly`, `updateAIFriendly`).

**🚨 NaN Table ID Errors (FIXED in v2.4.7)**  
❌ **Symptom**: Nextcloud logs show `table id = NaN` or `table id = 0`.  
✅ **Solution**: Update to v2.4.7 – robust Resource Locator validation implemented.

**Filters not working**  
✅ **Solution**: Use column IDs instead of names, ensure correct operators.

**Column creation failed**  
✅ **Fixed**: Uses optimized API v1 with query parameters.

**Resource Locator Validation Errors**  
✅ **New in v2.4.7**: Detailed error messages to help with debugging:

"Resource Locator is required but not set or invalid"
"Invalid ID in Resource Locator: 'undefined' is not a valid number"


### Error Handling
Detailed error messages for all HTTP status codes:
- **400–404**: Client errors with suggested fixes
- **429**: Rate-limiting with automatic retry
- **5xx**: Server errors with retry logic
- **Resource Locator**: Specific validation and helpful debugging (v2.4.7)

## 🎯 **Roadmap**

### ✅ **Version 2.4.8 (Current)**
- ✅ **Improved Log Labeling** – clear `[N8N-NEXTCLOUD-TABLES]` prefixes
- ✅ **Structured Logging** – Debug, Info, Warn, Error levels with context
- ✅ **API Request/Response Logging** – detailed debugging information
- ✅ **Operation Tracking** – start, success, error logging with timestamps
- ✅ **Validation Logging** – resource locator and parameter validation
- ✅ **Grep-friendly logs** – easy filtering by category

### ✅ **Version 2.4.7**
- 🛡️ **Critical NaN Bug Fixes**: Robust resource locator validation
- 🧹 **Production Cleanup**: Removed all debug tools and legacy code
- ⚡ **Enhanced Error Handling**: Helpful messages and validation
- 📦 **Optimized Builds**: Clean TypeScript compilation without warnings

### ✅ **Version 2.4.6 (Previous)**
- Full AI-Agent optimization
- 24 AI parameters with systematic separation
- Robust validation and error handling
- Clean UX for all operations

### 🔮 **Future Versions**
- More AI-Friendly operations for other resources
- Extended AI features (bulk operations, schema inference)
- Performance optimizations for large datasets
- Extended context integration with more Nextcloud apps

## Contributing

**Contributions welcome!** Especially:
- 🤖 **AI-Agent Testing**: Help test the AI-friendly operations
- 🐛 **Bug Reports**: Use GitHub Issues
- 💻 **Code**: Improvements and new features
- 📝 **Documentation**: Examples and best practices

## License

MIT

## Support

- **GitHub**: [Issues & Discussions](https://github.com/terschawebIT/n8n-nodes-nextcloud-tables)
- **n8n Community**: [Community Forum](https://community.n8n.io/)
- **Documentation**: [Nextcloud Tables API](https://github.com/nextcloud/tables/blob/main/docs/API.md)

---

**🤖 This node is the first AI-Agent-optimized n8n community node!**  
**Try the AI-friendly operations and experience fully autonomous table mana