# Xero Module

This module handles Xero integration functionality for the Seraph3 application with a **simplified, focused approach**.

## Clean Separation of Concerns

### XeroAuthService (Authentication)
**Handles ALL authentication concerns**:
- OAuth2 authorization flow
- Token management and automatic refresh
- Tenant ID management
- Connection status and error handling

### XeroService (API Operations)
**Simple and focused on core business logic**:
- One main method: `sendInvoiceToXero($invoice)` - **Accepts full invoice object**
- Automatic payment creation for paid invoices/sales
- Bank account management for payments
- Zero authentication logic - delegates to XeroAuthService

## Usage

### Simple Integration
```php
// Pass the full invoice object (most efficient)
$xeroService = app(\App\Modules\Xero\Services\XeroService::class);
$result = $xeroService->sendInvoiceToXero($invoice); // $invoice is full object with relationships

// Legacy method (for backward compatibility)
$result = $xeroService->sendInvoiceToXeroById($invoiceId, $type);
```

### Route Examples
```
POST /api/v1/invoices/send-to-xero/{id}      // Regular invoices
POST /api/v1/invoices/sales/send-to-xero/{id} // Sales receipts
```

## How It Works

### Authentication (XeroAuthService)
1. **OAuth Setup**: Admin configures credentials in Integration Settings
2. **Authorization**: Admin clicks "Connect to Xero" button
3. **Token Management**: Service automatically refreshes tokens
4. **Error Handling**: Clear messages for connection issues

### Invoice Sync (XeroService)
1. **Receive**: Full invoice object with client and items already loaded
2. **Check**: Skip if already has `xeroId` (invoice-level check)
3. **Sync**: Create invoice in Xero using client name
4. **Store**: Save `xeroId` locally for future reference
5. **Payment**: For paid sales, auto-create payment with bank account

### Bank Account Handling
- **First Time**: Fetch bank account from Xero and store ID
- **Future Calls**: Use stored bank account ID
- **Auto-Discovery**: Finds first BANK type account in Xero

## Key Features

✅ **Efficient**: Passes full invoice object - no additional database queries  
✅ **Smart**: Checks `invoice->xeroId` to avoid duplicates  
✅ **Automatic**: Handles payments for cash sales  
✅ **Efficient**: Stores bank account ID for reuse  
✅ **Reliable**: XeroAuthService handles all auth complexity  
✅ **Clean**: 85% code reduction (1158 → 180 lines)

## Response Format

```json
{
    "success": true,
    "message": "Invoice successfully sent to Xero",
    "xero_invoice_id": "12345678-1234-1234-1234-123456789012",
    "invoice_number": "INV-001",
    "already_synced": false
}
```

## Architecture Benefits

- **Separation of Concerns**: Auth vs API operations
- **Single Responsibility**: Each service has one job
- **Easy Testing**: Simple methods with clear inputs/outputs
- **Maintainable**: Clean code without auth complexity mixed in
- **Efficient**: No unnecessary database queries when invoice object is already available 