invox

#!/usr/bin/env bash

# Invox: simple invoice formatter
# See usage message for more details

set -eu
set -o pipefail

usage() {
  echo "
  invox
  Simple invoice formatter

  USAGE: invox [OPTIONS]
  NB: Requires bash v4.x or higher

  Requires time period and hours worked to be passed in a pipeline (see example below),
  OR use -a to specify a fixed amount directly.

  OPTIONS
  -i <string> (required)   invoice_id, the identifer for this invoice
  -a <number>              fixed amount (overrides retainer in config, skips hours calculation)
                           if omitted, uses 'retainer' value from config
  -m <string>              month for invoice period (e.g. "january" or "december 2025")
                           auto-calculates start, end, issue date, and due date
  -s <string>              start date (required when using -a without -m)
  -x <string>              end date (required when using -a without -m)
  -l <string>              extra line item title (e.g. "Cursor AI Usage")
  -L <number>              extra line item amount (e.g. 483)
  -d <string>              issue date of the invoice (overrides -m calculation)
  -e <string>              custom due date of the invoice (overrides -m calculation)
  -c <string>              custom config file (auto-detects *.invoxrc in current dir)
  -t <string>              custom html template (auto-detects *.invox_template.html in current dir)
  -n                       no pdf (html only)
  -h                       help (this message)

  EXAMPLES

  With defaults (hours from watson):
  $ watson report -G | invox -i 97

  The invoice will be saved as invoice_97.pdf in the current directory.

  With fixed amount (no watson required):
  $ invox -i 98 -a 1500 -s 2026-01-01 -x 2026-01-31

  The invoice will be saved as invoice_98.pdf with a cost of 1500 (in your configured currency).

  With month-based dates (retainer style):
  $ invox -i 99 -m january -l "Cursor AI Usage" -L 500

  Auto-calculates: period Jan 1-31 (current year), issue date Feb 1, due date Feb 15.

  For a different year (e.g., invoicing late for December):
  $ invox -i 100 -m "december 2025"

  Auto-calculates: period Dec 1-31 2025, issue date Jan 1 2026, due date Jan 15 2026.

  With custom config, template, date, and filename:
  $ watson report -G | ./invox -i MC81 -d \"1 August 2020\" -t ./invox_template.html -c ./.invoxrc -f \"Invoice\"

  The invoice will be saved as Invoice.pdf in the current directory.

  SETUP
  1. Config file located in ~/.config/invox/.invoxrc
  - includes all the variables to be replaced in the template file
  - can be overriden with the -c flag (see above)
  2. Template located in ~/.config/invox/invox_template.html
  - can be overriden with the -t flag (see above)

  You can have whatever variables in the config and template, as long as they are the same. Variables are wrapped in double brackets in the template file, e.g. {{recipient_name}}.
  "
}

# default config and template locations
config=""
template=""
date_issued=$(date "+%d %B %Y")
due_date=$(date -d "+13 days" "+%d %B %Y")
no_pdf=false
fixed_amount=""
month_arg=""
start_date_arg=""
end_date_arg=""
extra_title=""
extra_amount=""

while getopts "i:a:m:s:x:l:L:d:e:t:c:f:nh" opt; do
  case "$opt" in
  i)
    invoice_id="$OPTARG"
    ;;
  a)
    fixed_amount="$OPTARG"
    ;;
  m)
    month_arg="$OPTARG"
    ;;
  s)
    start_date_arg="$OPTARG"
    ;;
  x)
    end_date_arg="$OPTARG"
    ;;
  l)
    extra_title="$OPTARG"
    ;;
  L)
    extra_amount="$OPTARG"
    ;;
  d)
    date_issued="$OPTARG"
    ;;
  e)
    due_date="$OPTARG"
    ;;
  c)
    config="$OPTARG"
    ;;
  t)
    template="$OPTARG"
    ;;
  f)
    filename="$OPTARG"
    ;;
  n)
    no_pdf=true
    ;;
  h)
    usage
    exit 0
    ;;
  \?)
    usage
    exit 1
    ;;
  esac
done
shift $((OPTIND - 1))

if [[ ! ${invoice_id+x} ]]; then
  echo "-i required: set the invoice id" && usage && exit 1
fi

# resolve config: flag > local directory > default
if [[ -z "$config" ]]; then
  local_config=$(find . -maxdepth 1 \( -name "*.invoxrc" -o -name ".invoxrc" \) 2>/dev/null | head -1)
  if [[ -n "$local_config" ]]; then
    config="$local_config"
    echo "Auto-detected config: $config"
  else
    config=~/.config/invox/.invoxrc
  fi
fi

# resolve template: flag > local directory > default
if [[ -z "$template" ]]; then
  local_template=$(find . -maxdepth 1 \( -name "*.invox_template.html" -o -name ".invox_template.html" \) 2>/dev/null | head -1)
  if [[ -n "$local_template" ]]; then
    template="$local_template"
    echo "Auto-detected template: $template"
  else
    template=~/.config/invox/invox_template.html
  fi
fi

# get values for report from config file
declare -A report
while IFS='=' read -d $'\n' -r key value; do
  # skip empty lines and comments
  [[ "$key" =~ ^([[:space:]]*|[[:space:]]*#.*)$ ]] && continue

  report[$key]="$value"
done <"$config"

# format date to YYYY.MM.DD
format_date() {
  date -d "$1" +%Y.%m.%d
}

# format number with thousand separators (20000 → 20,000)
format_number() {
  printf "%'d" "$1"
}

# use retainer from config if no -a flag and not in pipeline mode
if [[ -z "$fixed_amount" ]] && [[ -v "report[retainer]" ]] && [[ -n "${report[retainer]}" ]]; then
  fixed_amount="${report[retainer]}"
fi

# handle fixed amount mode vs watson pipeline mode
if [[ -n "$fixed_amount" ]]; then
  # fixed amount mode - no pipeline required
  
  # if month is provided, calculate all dates from it
  if [[ -n "$month_arg" ]]; then
    # parse month to get first day of month
    # accepts "january" (current year) or "december 2025" (specific year)
    first_of_month=$(date -d "1 $month_arg" +%Y-%m-01)
    
    start_date_arg="$first_of_month"
    end_date_arg=$(date -d "$first_of_month +1 month -1 day" +%Y-%m-%d)
    
    # issue date is 1st of next month (unless overridden by -d)
    if [[ "$date_issued" == $(date "+%d %B %Y") ]]; then
      date_issued=$(date -d "$first_of_month +1 month" "+%d %B %Y")
    fi
    
    # due date is 14 days after issue date (unless overridden by -e)
    if [[ "$due_date" == $(date -d "+13 days" "+%d %B %Y") ]]; then
      due_date=$(date -d "$first_of_month +1 month +14 days" "+%d %B %Y")
    fi
    
    echo "Month: $month_arg"
    echo "  Period: $start_date_arg to $end_date_arg"
    echo "  Issue date: $date_issued"
    echo "  Due date: $due_date"
  elif [[ -z "$start_date_arg" || -z "$end_date_arg" ]]; then
    echo "-s and -x (or -m) required when using -a: set the start and end dates"
    usage
    exit 1
  fi
  
  time_period="$(format_date "$start_date_arg") - $(format_date "$end_date_arg")"
  cost="$fixed_amount"
  echo "Fixed amount: ${report[currency_symbol]}$cost ${report[currency_name]}"
else
  # watson pipeline mode
  if test -t 0; then
    echo "Time sheet required in pipeline. Currently only supports watson."
    echo "Or use -a <amount> -s <start> -x <end> for a fixed amount invoice."
    usage
    exit 1
  fi

  # read time period and hours worked from stdin (piped from `watson report -G`)
  read -r time_period
  read -r _
  read -r details

  start_date=$(echo "$time_period" | grep -o '^[^-]*')
  end_date=$(echo "$time_period" | grep -o '[^>]*$')
  time_period="$(format_date "$start_date") - $(format_date "$end_date")"

  hours=$(perl -ne 'print "$&\n" if /\d+(?=h)/' <<<"$details")
  minutes=$(perl -ne 'print "$&\n" if /\d+(?=m)/' <<<"$details")
  hours=${hours#0}
  minutes=${minutes#0}

  # round up hours (for per-hour commenced billing)
  if [[ $minutes -gt 0 ]]; then
    ((hours = hours + 1))
  fi

  echo "Debug - hours: $hours"
  echo "Debug - hourly rate: ${report[hourly_rate]}"
  # calculate cost as a function of the hours and hourly rate
  cost=$(bc <<<"scale=0; ($hours * ${report[hourly_rate]})/1")
fi

# handle extra line item and calculate total
has_extra=false
if [[ -n "$extra_title" && -n "$extra_amount" ]]; then
  has_extra=true
  total=$((cost + extra_amount))
  echo "Extra line item: $extra_title - ${report[currency_symbol]}$(format_number "$extra_amount") ${report[currency_name]}"
  echo "Total: ${report[currency_symbol]}$(format_number "$total") ${report[currency_name]}"
else
  total="$cost"
fi

# format numbers for display
cost=$(format_number "$cost")
total=$(format_number "$total")
[[ -n "$extra_amount" ]] && extra_amount=$(format_number "$extra_amount")

# add variables to report
report[time_period]="$time_period"
report[cost]="$cost"
report[total]="$total"
report[extra_title]="$extra_title"
report[extra_amount]="$extra_amount"
report[date_issued]="$date_issued"
report[due_date]="$due_date"
report[invoice_id]="$invoice_id"

# get all variable names in template file
vars=$(grep -oE '\{\{([A-Za-z0-9_]+)\}\}' "$template" |
  sed -rn 's/.*\{\{([A-Za-z0-9_]+)\}\}.*/\1/p' |
  sort |
  uniq)

# default filename if no -f flag is set
if [[ ! ${filename+x} ]]; then
  filename="Invoice ${invoice_id} - ${date_issued} - ${report[sender_name]}"
fi

cp "$template" "$filename.html"

# remove conditional sections if not needed
if [[ "$has_extra" == false ]]; then
  sed -i '/<!-- BEGIN extra_row -->/,/<!-- END extra_row -->/d' "$filename.html"
  sed -i '/<!-- BEGIN total_row -->/,/<!-- END total_row -->/d' "$filename.html"
else
  # remove just the comment markers, keep the content
  sed -i '/<!-- BEGIN extra_row -->/d; /<!-- END extra_row -->/d' "$filename.html"
  sed -i '/<!-- BEGIN total_row -->/d; /<!-- END total_row -->/d' "$filename.html"
fi

# escape special sed characters in replacement string
escape_sed() {
  local val="$1"
  # escape backslashes first, then forward slashes, then ampersands
  val="${val//\\/\\\\}"
  val="${val//\//\\/}"
  val="${val//&/\\&}"
  printf '%s' "$val"
}

# substitute all template variables
for var in $vars; do
  # skip optional variables that may be empty
  [[ "$var" == "extra_title" || "$var" == "extra_amount" || "$var" == "total" ]] && [[ "$has_extra" == false ]] && continue
  
  if [[ -v "report[$var]" ]] && [[ -n "${report[$var]}" ]]; then
    escaped_value=$(escape_sed "${report[$var]}")
    sed -i "s/{{$var}}/$escaped_value/" "$filename.html"
  else
    echo "Warning: template variable '{{$var}}' not found in config"
  fi
done

if [[ $no_pdf == false ]]; then
  echo "Creating PDF invoice, saving to $(pwd)/$filename.pdf"
  wkhtmltopdf \
    --page-size "Letter" \
    --margin-top "0mm" \
    --margin-right "0mm" \
    --margin-bottom "0mm" \
    --margin-left "0mm" \
    --quiet \
    "$filename.html" "$filename.pdf" &&
    xdg-open "$filename.pdf" 2>/dev/null ||
    echo "Failed to create invoice PDF. Check filename for formatting errors."

  echo "Removing HTML file"
  rm "$filename.html"
else
  echo "Creating HTML invoice, saving to $(pwd)/$filename.html"
fi