---
name: invoice-generator
description: Generate and send time tracking invoice Excel files from FreeScout data. Use when the user asks for an invoice, time report, or hours summary for a customer and time period.
---

# Invoice Generator

Generate Excel invoices from FreeScout time tracking data and send them via WhatsApp.

## Workflow

1. Identify customer name and date range from the user's request
2. Run: `bin/freescout excel --from YYYY-MM-DD --to YYYY-MM-DD --customer "NAME" --output /tmp/invoice-CUSTOMER-PERIOD.xlsx`
3. Send the file to the user via the `message` tool
4. Reply with NO_REPLY (the file message is the reply)

## CLI Reference

```bash
freescout mailboxes                          # List mailboxes
freescout users                              # List users
freescout report --from DATE --to DATE       # Show time report (tab-separated)
  [--mailbox ID] [--user ID] [--customer NAME]
freescout excel --from DATE --to DATE        # Generate invoice Excel
  [--mailbox ID] [--user ID] [--customer NAME] [--output file.xlsx]
```

## Technical Details

- Credentials: `.credentials/services.env` (CLOONAR_DB_* + FREESCOUT_DB_NAME)
- Queries timelogs table directly (API doesn't expose time tracking)
- Excel groups by conversation, shows subject, customer, website, hours
- Customer and Website are custom field dropdowns (resolved to labels)
- `time_spent` is stored in seconds, displayed as decimal hours
- Only timelogs within the date range are counted (not conversation dates)

## Finding Customers

Pass a wrong `--customer` name — the script prints all available customers.