config/skills/invoice-generator/SKILL.md

name	description
invoice-generator	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

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.