Enhance list-invoices with advanced filtering (Type, status, dates, amounts)

[cesarho]

Add advanced filtering capabilities to list-invoices tool

Summary

This PR enhances the list-invoices tool with comprehensive filtering options, enabling more precise invoice queries through the Xero API. The changes add support for filtering by invoice IDs, statuses, custom where clauses, and customizable ordering.

Changes

New Filtering Parameters

• invoiceIds: Filter invoices by specific invoice IDs (array of strings)
• statuses: Filter by invoice statuses - DRAFT, SUBMITTED, DELETED, AUTHORISED, PAID, VOIDED (array of strings)
• where: Advanced filtering using Xero's where clause syntax for complex queries including:
  • Invoice Type (ACCREC for sales invoices, ACCPAY for bills)
  • Date ranges (Date, DueDate)
  • Amount filtering (AmountDue)
  • Contact name filtering
  • Complex logical combinations (AND, OR)
• order: Customizable ordering (defaults to "UpdatedDateUTC DESC")

Implementation Details

• Refactored listXeroInvoices handler to use a ListInvoicesParams interface for better type safety
• Made page parameter optional with default value of 1
• Enhanced tool description with comprehensive AI agent guidance, including:
  • Decision guide for choosing the right parameter
  • Common query examples
  • Critical notes about filtering by invoice Type (must use where parameter)
  • Performance recommendations (prefer dedicated array parameters for multiple IDs/statuses)

Updated Files

• src/tools/list/list-invoices.tool.ts: Added new parameters and comprehensive documentation
• src/handlers/list-xero-invoices.handler.ts: Refactored to support new filtering options
• README.md: Updated tool description to reflect advanced filtering capabilities

Benefits

• More flexible queries: Users can now filter invoices by Type, status, dates, amounts, and more
• Better AI agent support: Comprehensive documentation helps AI agents make optimal parameter choices
• Performance optimized: Dedicated array parameters for common use cases (IDs, statuses)
• Type safety: New interface ensures proper parameter handling

Example Use Cases

• Filter sales invoices: where=Type=="ACCREC"
• Filter bills: where=Type=="ACCPAY"
• Find overdue invoices: where=DueDate<DateTime(2024,12,01) AND Status=="AUTHORISED"
• Filter by multiple statuses: statuses=["AUTHORISED","PAID"]
• Complex queries: where=Type=="ACCREC" AND Status=="AUTHORISED" AND AmountDue>1000