@arathron/n8n-nodes-zoho-books/CHANGELOG.md

n8n community nodes for Zoho Books and Zoho Inventory API integration - Complete CRUD operations for Sales Orders, Invoices, Items, Vendors, Credit Notes, Payments, Purchase Orders, Bills, Composite Items, and Assemblies

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [2.7.7] - 2025-01-08

### Added
- **Reason Field for Sent Invoice Updates**: Added required reason field when updating sent invoices to comply with Zoho Books API requirements
  - **NEW FIELD**: Added "Reason for Update" field in invoice update operation UI
  - **VALIDATION**: Automatically validates reason is provided when updating sent invoices
  - **ERROR HANDLING**: Enhanced error messages for Zoho error code 110701 (reason required for sent invoice updates)
  - **USER EXPERIENCE**: Clear guidance when reason is missing for sent invoice updates

### Fixed
- **Form-data Encoding**: Requests that only contain `JSONString` are now sent as form data (URL-encoded / multipart) instead of raw JSON.
  - Automatically handled in `zohoApiRequest` when the body shape is `{ JSONString: ... }`.
  - Ensures Zoho Books interprets payload correctly on create/update endpoints.

## [2.7.6] - 2025-08-04

### Fixed
- **Form-data Encoding**: Requests that only contain `JSONString` are now sent as form data (URL-encoded / multipart) instead of raw JSON.
  - Automatically handled in `zohoApiRequest` when the body shape is `{ JSONString: ... }`.
  - Ensures Zoho Books interprets payload correctly on create/update endpoints.

## [2.7.5] - 2025-01-28

### Fixed
- **Invoice Date Update Issue**: Fixed critical bug where invoice date updates were being silently ignored by Zoho API
  - **ROOT CAUSE**: Zoho Books API requires complete payload with all mandatory fields for successful updates
  - **COMPREHENSIVE SOLUTION**: Implemented fetch-then-update pattern that includes all required fields:
    - `customer_id` (required at all times)
    - `currency_id` (required for foreign currency invoices)
    - `line_items` (at least one item required)
    - `date` and `due_date` (must be a valid pair)
    - All other fields being updated
  - **REMOVED ARTIFICIAL LIMITS**: Eliminated 100-character JSONString limit that was preventing proper updates
  - **ENHANCED ERROR HANDLING**: Added proper validation for missing invoices and line items
  - **BACKWARD COMPATIBLE**: Maintains existing behavior while ensuring date updates work correctly
  - **COMPREHENSIVE TESTS**: Updated both unit and integration tests to reflect new behavior

## [2.7.4] - 2025-01-28

### Fixed
- **Invoice Update JSONString Limit**: Fixed "JSONString has more than 100 characters" error (Zoho API error code 15)
  - **100-CHARACTER LIMIT**: Implemented smart payload sizing to stay under Zoho's JSONString character limit
  - **MINIMAL PAYLOAD**: Creates optimal payload with essential fields (customer_id) and update fields only
  - **ADAPTIVE LOGIC**: Dynamically adjusts payload size by removing optional fields when approaching limit
  - **ERROR HANDLING**: Clear error messages when update data exceeds limit constraints
  - **MAINTAINED FIX**: Preserves the date update fix while complying with API character restrictions
  - **COMPREHENSIVE TESTS**: Updated all tests to verify 100-character limit compliance

## [2.7.3] - 2025-01-28

### Fixed
- **Invoice Update Date Issue**: Fixed critical bug where invoice date updates were being silently ignored
  - **MANDATORY FIELDS**: Modified invoice update to fetch existing invoice data first and include all mandatory fields (customer_id, line_items)
  - **API COMPLIANCE**: Ensures Zoho Books API requirements are met for successful date updates  
  - **DATA PRESERVATION**: Existing line items and essential fields are preserved during updates
  - **BACKWARD COMPATIBLE**: Maintains existing behavior while fixing the date update issue
  - **COMPREHENSIVE TESTS**: Updated test suite to verify the new fetch-then-update pattern
  - **ERROR HANDLING**: Added proper error handling when invoice is not found during update

## [2.7.2] - 2025-01-28

### Fixed
- **Invoice Update Date Handling**: Fixed timezone-related date issues for IST (India Standard Time)
  - **DATE PROCESSING**: Improved date field processing to avoid timezone conversion issues
  - **IST SUPPORT**: All dates now properly handled assuming India Time zone (IST +05:30)
  - **TIMEZONE SAFETY**: Prevents off-by-one day errors when updating invoices with ISO datetime strings
  - **STRING EXTRACTION**: Uses string slicing instead of Date constructor to maintain calendar date accuracy
  - **COMPREHENSIVE TESTS**: Added unit tests covering various date input formats

## [2.7.1] - 2025-01-26

### Fixed
- **UI Configuration**: Fixed "Mark as Sent" operation to only appear for Invoice resources
  - **RESOURCE FILTERING**: Separated Invoice operations from general operations list
  - **USER EXPERIENCE**: "Mark as Sent" operation now only shows when Invoice resource is selected
  - **INVOICE ID FIELD**: Invoice ID parameter now properly displays for markAsSent operation

## [2.7.0] - 2025-01-26

### Added
- **Invoice Mark as Sent Operation**: Added ability to mark invoices as sent
  - **NEW OPERATION**: "Mark as Sent" operation for invoices to track delivery status
  - **API ENDPOINT**: POST `/invoices/{invoice_id}/status/sent` integration
  - **STATUS TRACKING**: Changes invoice status to "sent" for workflow management
  - **DOCUMENTATION**: Complete operation guide with examples in OPERATIONS.md
  - **TESTING**: Full unit test coverage for markAsSent functionality

### Enhanced
- **Invoice Resource**: Added markAsSent method to Invoice.resource.ts
- **Node Interface**: Updated ZohoBooks.node.ts with new operation option
- **User Experience**: Clear operation description and validation

## [2.6.0] - 2025-01-08

### Added
- **Invoice Update Operations**: Enhanced update functionality with comprehensive field support
  - **NEW FIELDS**: Added editable fields for invoice updates:
    - Date (invoice date in YYYY-MM-DD format)
    - Invoice Number (custom invoice numbering)
    - Place of Supply (for tax calculations)
    - GST Treatment (business_gst, consumer, overseas, sezwp, sez, unregistered)
    - GST Number (GSTIN for tax compliance)
    - Due Date, Reference Number, Notes, and Terms
  - **LINE ITEMS**: Added support for updating invoice line items during update operation
  - **FLEXIBLE UPDATES**: All update fields are optional - only provide fields you want to change
  - **GST COMPLIANCE**: Enhanced support for Indian tax requirements with GST treatment options
  - **DOCUMENTATION**: Comprehensive examples and workflow guides for invoice updates
  - **TESTING**: Full unit and integration test coverage for all new update fields

### Enhanced
- **Invoice Resource**: Improved update method to handle new field collection seamlessly
- **User Experience**: Clear field descriptions and validation messages
- **API Integration**: Maintains backward compatibility while adding powerful new capabilities

## [2.5.5] - 2025-01-08

### Fixed
- **Invoice Operations**: ULTIMATE FIX for "Create invoice from sales order" operation
  - **CRITICAL CHANGE**: Changed `salesorder_id` from request body to query parameter as per Zoho API documentation
  - Now sends `salesorder_id` as URL query parameter: `/invoices/fromsalesorder?salesorder_id=123456`
  - This resolves the "Invalid value passed for salesorder_id" error (code 4)
  - Enhanced sales order validation to check status before invoice creation
  - Improved error handling with more specific validation messages
  - Updated all test cases to reflect the correct API usage

## [2.5.4] - 2025-01-08

### Fixed
- **Invoice Operations**: Previous attempt using body parameters (superseded by 2.5.5)

## [2.5.3] - 2025-01-08

### Fixed
- **Invoice Operations**: Previous iteration (superseded by 2.5.4)

## [2.5.2] - 2025-01-08

### Fixed
- **Invoice Operations**: Incorrect attempt using `salesorder_ids` parameter (superseded by 2.5.3)

## [2.5.1] - 2025-01-08

### Fixed
- **Invoice Operations**: Partial fix for "Create invoice from sales order" operation (superseded by 2.5.2)

## [2.4.0] - 2025-01-22

### Added
- **Invoice Operations**: Complete invoice management functionality
  - Added new Invoice resource with full CRUD operations (create, get, getAll, update, delete, list)
  - **Create Instant Invoice from Sales Order**: New operation to convert sales orders to invoices instantly
    - Uses Zoho's `/invoices/fromsalesorder` endpoint for efficient conversion
    - Supports additional fields like due date, notes, terms, discount, and exchange rate
    - Includes automatic sales order validation before invoice creation
    - Provides detailed error handling and user-friendly error messages
  - Added comprehensive invoice utility functions for validation and data normalization
  - Full test coverage with 26+ unit tests and 5 integration tests
  - Enhanced error handling with context-aware error messages

### Enhanced
- **Node Structure**: Updated ZohoBooks node to properly handle invoice operations
  - Added dynamic Invoice resource importing for better performance
  - Integrated invoice operations with existing node architecture
  - Improved parameter validation for invoice-specific fields

## [2.3.2] - 2025-03-08

### Fixed
- **Contact Date Filtering**: Fixed Contact getAll operation with proper Zoho API parameters
  - Added `filter_by: 'Last Modified Time'` parameter required by Zoho Books API
  - Updated date formatting to use ISO-8601 timestamps instead of plain dates
  - Fixed "Invalid value passed for last_modified_time" error when using "Updated After" filter
  - Enhanced date handling to support both date-only and full timestamp inputs
  - Improved empty/whitespace parameter validation to prevent API errors

### Enhanced
- **Date Formatting**: Added new `formatDateTime()` function for ISO-8601 timestamp conversion
  - Converts any valid date/time input to proper ISO-8601 format
  - Handles plain dates (YYYY-MM-DD) by adding time component
  - Removes milliseconds for Zoho API compatibility
  - Maintains backward compatibility with existing `formatDate()` function

### Technical
- **API Compatibility**: Updated Contact getAll operation to use correct Zoho Books API parameters
- **Test Coverage**: Updated all Contact-related tests to reflect new API parameter structure
- **Error Handling**: Improved validation to prevent empty parameter errors
- **Type Safety**: Enhanced type checking for date parameters and API responses

## [2.3.1] - 2025-03-08

### Fixed
- **Contact Date Filtering**: Fixed Contact getAll operation error with empty `last_modified_time` parameter
- **Parameter Validation**: Improved date filtering logic to only include `last_modified_time` when valid date is provided
- **Error Handling**: Added proper validation for empty and whitespace `updatedAfter` parameters
- **Date Formatting**: Enhanced `formatDate` function to handle edge cases better
- **Test Coverage**: Fixed test expectations to match actual function call signatures
- **Edge Cases**: Added comprehensive tests for empty and invalid date parameter handling

### Technical
- **Test Suite**: All 27 ContactsUtils tests now passing with proper error handling
- **Validation**: Enhanced parameter validation in getAllContacts function
- **Type Safety**: Improved type checking for date parameters

## [2.3.0] - 2025-03-08

### Added
- **Contact Search by Name**: New search operation for Contact resource
  - Search contacts by full or partial name using Zoho Books search API
  - Returns normalized contact data in camelCase format
  - Includes raw API response for advanced processing
  - Supports partial name matching (e.g., "John" finds "John Doe", "John Smith")
  - Auto-pagination for complete search results
  - Comprehensive error handling and validation

### Enhanced
- **Contact Operations**: Extended Contact resource with search functionality
  - Added "Search" operation to Contact resource options
  - New "Search Name" parameter for contact name search
  - Integrated with existing Contact utilities and normalization
  - Maintains consistency with other Contact operations

### Documentation
- **Search Documentation**: Added search operation to OPERATIONS.md Contact section
- **JSON Guide Update**: Enhanced CONTACT_JSON_GUIDE.md with search examples
- **Response Examples**: Detailed examples of search request and response formats
- **Best Practices**: Guidelines for effective contact searching

### Testing
- **Search Tests**: Comprehensive unit tests for search functionality
  - Tests for successful search with multiple results
  - Error handling tests for empty search terms
  - Mock coverage for search API calls and response handling

## [2.2.1] - 2025-03-08

### Fixed
- **Contact Date Filtering**: Fixed Contact getAll operation error with empty `last_modified_time` parameter
  - Improved date filtering logic to only include `last_modified_time` when valid date is provided
  - Added proper validation for empty and whitespace `updatedAfter` parameters
  - Prevents API errors when no date filter is specified

## [2.2.0] - 2025-01-15

### Added
- **NEW FEATURE**: Contact Resource with Full CRUD Operations
  - Complete Contact management with Create, Read, Update, Delete operations
  - Support for all Contact fields: name, company, email, phone, website, currency, balance
  - Billing and Shipping address management with structured address fields
  - Custom fields support for flexible contact data
  - Pagination support with "Return All" and "Limit" options
  - Date filtering with "Updated After" parameter
  - Normalized response format with camelCase keys for easier integration
  - Comprehensive error handling and validation
  - Full TypeScript support with proper type definitions

### Enhanced
- **Contact Utilities**: New `ContactsUtils.ts` with helper functions
  - `buildContactPayload()` for parameter to API payload conversion
  - `normalizeContact()` for response normalization
  - `createContact()`, `getContact()`, `getAllContacts()`, `updateContact()`, `deleteContact()` API functions
  - Proper error handling with NodeApiError for validation failures
  - Support for address structures and custom fields

### Documentation
- **Contact Operations Guide**: Added comprehensive Contact section to OPERATIONS.md
- **Contact JSON Guide**: New CONTACT_JSON_GUIDE.md with detailed examples
- **Field Descriptions**: Complete documentation of all Contact fields and their usage
- **Integration Examples**: CRM and e-commerce integration examples
- **Best Practices**: Contact naming, email validation, address formatting guidelines
- **Troubleshooting**: Common issues and validation checklist

### Testing
- **Unit Tests**: Comprehensive test coverage for ContactsUtils functions
- **Resource Tests**: Full test suite for Contact resource operations
- **Error Handling**: Tests for validation errors, API errors, and edge cases
- **Mock Coverage**: Proper mocking of API calls and response handling

### Technical Changes
- Added Contact resource to node JSON configuration
- Extended execute method with Contact operation handling
- Added Contact fields with proper displayOptions and validation
- Implemented dynamic import for ContactsUtils to maintain performance
- Added Contact to resource options and operation display conditions

## [2.1.1] - 2025-01-15

### Fixed
- **Customer Dropdown Population**: Improved customer field loading in Form and Hybrid modes
  - Now specifically queries for `contact_type=customer` to ensure proper customer list
  - Added fallback to all contacts if no customers found
  - Enhanced error handling to prevent UI issues when API calls fail
  - Better reliability for customer dropdown pre-population

## [2.1.0] - 2025-01-15

### Added
- **Enhanced Form Fields**: Added Sales Order Date and Sales Order Number fields to Form and Hybrid input methods
  - Sales Order Date: Document date field with automatic YYYY-MM-DD formatting
  - Sales Order Number: Custom sales order number field (auto-numbered if left blank)
  - Both fields are available in Form and Hybrid input methods
  - In Hybrid mode, form fields override corresponding JSON values for better user control
- **Date Formatting Utility**: New `formatDate` helper function for consistent date formatting across input methods

### Enhanced
- **Hybrid Method**: Form fields now take precedence over JSON data for date and sales order number
- **Customer Field**: Pre-populated customer dropdown now consistently available in Hybrid mode
- **Documentation**: Updated sales order guide with new field descriptions and usage examples

## [1.4.1] - 2024-12-19

### Fixed
- **Sales Order Search by Number**: Fixed exact matching issue where partial matches were returned
  - Now performs client-side filtering to ensure exact sales order number matches
  - Uses dual approach: criteria search first, then fallback to search_text with exact filtering
  - Prevents returning wrong sales orders with similar numbers (e.g., searching for "404-3495320-8661951" no longer returns "408-0914562-5185938")
  - Enhanced test coverage for exact matching scenarios

## [1.4.0] - 2024-12-19

### Added
- **Enhanced Sales Order Get Operation**: Added flexible search capabilities
  - New "Search Type" option allows searching by Sales Order ID or Sales Order Number
  - Search by Sales Order Number uses Zoho's criteria API for exact matches
  - Graceful "not found" handling: Returns `{ sales_order_found: false }` instead of throwing errors
  - Backward compatible: Existing workflows using ID search continue to work unchanged
  - New utility function `findSalesOrderByNumber()` for reusable number-based lookups
  - Comprehensive test coverage for both search modes and edge cases

### Fixed
- Added legacy compatibility exports for existing test infrastructure
- Improved error handling for resource not found scenarios
- Added missing `getTaxes` load options method for form dropdowns

## [1.3.11] - 2024-08-02

### Added
- **NEW FEATURE**: Get Item by SKU operation for both Zoho Books and Zoho Inventory
  - Added `getBySku` operation to Item resource in both nodes
  - Supports case-insensitive SKU code lookup
  - Comprehensive error handling for edge cases:
    - Empty or whitespace SKU codes
    - SKU not found scenarios
    - Multiple items with duplicate SKUs
    - Invalid API response handling
  - Performance optimized with single API call and client-side filtering
  - Full test coverage with 40+ unit tests covering all scenarios

### Enhanced
- Added Item resource support to ZohoInventory node with full CRUD operations
- Improved error messages with specific HTTP status codes
- Added support for special characters and Unicode in SKU codes
- Enhanced documentation with usage examples and troubleshooting guide

### Technical Changes
- Created `getItemBySku` helper function in GenericFunctions for both nodes
- Added comprehensive TypeScript type definitions
- Implemented proper error wrapping with NodeApiError
- Added SKU input field with validation and placeholder text
- Extended execute methods to handle new getBySku operation

## [1.2.7] - 2024-12-19

### Fixed
- **CRITICAL**: Fixed parameter dependency resolution error for Bill Create Record operation
- Resolved "Could not resolve parameter dependencies. Max iterations reached!" error
- Split single additionalFields collection into resource-specific collections to eliminate displayOptions on child parameters
- Updated all execute method references to use new parameter names
- Added proper TypeScript type casting for all additionalFields parameters

### Technical Changes
- Replaced single additionalFields collection with separate collections for each resource:
  - billAdditionalFields
  - invoiceAdditionalFields  
  - salesOrderAdditionalFields
  - purchaseOrderAdditionalFields
  - itemAdditionalFields
  - compositeItemAdditionalFields
  - vendorAdditionalFields
  - paymentAdditionalFields
  - creditNoteAdditionalFields
- Removed all displayOptions from child parameters in collection/fixedCollection types
- Added proper IDataObject type casting for all additionalFields parameters

## [Unreleased]

### Added
- Initial release of n8n-nodes-zoho-books
- OAuth2 authentication support for all Zoho data centers
- Support for 6 main resources:
  - Sales Orders - Create, read, update, and void operations
  - Invoices - Full CRUD operations with line items support
  - Items - Complete product/service management
  - Payments - Customer payment recording and tracking
  - Vendors - Supplier management functionality
  - Credit Notes - Returns and adjustments handling
- Rate limiting with automatic retry and exponential backoff
- Comprehensive error handling with detailed messages
- Load options for dynamic dropdowns (customers, items, taxes)
- Pagination support for all list operations
- Filtering capabilities for date ranges and status
- Additional fields support for extended functionality
- Full test coverage with unit and integration tests

### Security
- Secure OAuth2 implementation
- Organization ID validation
- Proper credential handling

## [0.1.0] - 2024-01-XX

### Added
- Beta release for testing
- Core functionality for all 6 resources
- Basic documentation and examples

### Known Issues
- Some advanced Zoho Books features not yet implemented
- Custom fields support is limited

## Roadmap

### Version 0.2.0 (Planned)
- [ ] Purchase Order support
- [ ] Bill management
- [ ] Bank transaction reconciliation
- [ ] Journal entries
- [ ] Enhanced custom field support

### Version 0.3.0 (Planned)
- [ ] Bulk operations support
- [ ] Webhook trigger node
- [ ] Report generation
- [ ] Tax configuration management
- [ ] Multi-currency support

### Version 1.0.0 (Planned)
- [ ] Complete API coverage
- [ ] Performance optimizations
- [ ] Advanced filtering options
- [ ] Comprehensive error recovery
- [ ] Production-ready release

## Contributing

Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to contribute to this project.

## Support

For issues and feature requests, please use the [GitHub issue tracker](https://github.com/your-username/n8n-nodes-zoho-books/issues).