feat(billing): add BillingView — category-grouped billable hours export (#938)

* feat(billing): add BillingView — category-grouped billable hours export

Prototype for #899. Adds a /billing route with a
panel that:
- Queries all active (non-AFK) window events over a selected date range
- Categorizes them using the user's existing AW category rules
- Groups totals by $category (leaf path, e.g. "Work > Programming")
- Lets users set a per-hour rate globally or per category row
- Exports a CSV with: Category, Hours, Rate, Amount

Design decision: grouping unit is the full category path (leaf), not
project or tag, because $category is already first-class in AW and maps
directly to invoice line items without extra watcher setup.

Navigation: added "Billable Hours" entry next to Work Report in the
Tools dropdown.

* fix(billing): fix rate fallback, stale period, and CSV escaping

- getEffectiveRate: treat explicit 0 as 'not billable' not 'unset';
  previously, entering 0 for a category fell back to defaultRate,
  incorrectly billing non-billable time at the default rate
- store queriedPeriod at load time; periodLabel and exportCSV now use
  the actual queried period, not the current moment at display time
- escape double-quotes in CSV category fields per RFC 4180

* fix(billing): use JSON key for category identity, delay queriedPeriod on failure

- Use JSON.stringify(categoryArray) as map key to prevent false collisions
  when a category segment name contains the ' > ' delimiter string
- Move queriedPeriod assignment to after successful query, so that a
  failed refresh does not mislabel the still-visible previous rows
- Separate row.key (identity/rate-lookup) from row.category (display/CSV)

Author: TimeToBuildBob

src/components/Header.vue

@@ -60,6 +60,9 @@ div(:class="{'fixed-top-padding': fixedTopMenu}")
           b-dropdown-item(to="/work-report")
             icon(name="briefcase")
             | {{ $t('nav.workReport') }}
+          b-dropdown-item(to="/billing")
+            icon(name="dollar-sign")
+            | Billable Hours
           b-dropdown-item(to="/analysis/activity" v-if="devmode")
             icon(name="robot")
             | {{ $t('nav.aiSummary') }}
@@ -102,6 +105,7 @@ div(:class="{'fixed-top-padding': fixedTopMenu}")
 // only import the icons you use to reduce bundle size
 import 'vue-awesome/icons/calendar-day';
 import 'vue-awesome/icons/briefcase';
+import 'vue-awesome/icons/dollar-sign';
 import 'vue-awesome/icons/calendar-week';
 import 'vue-awesome/icons/stream';
 import 'vue-awesome/icons/database';

src/route.js

@@ -19,6 +19,7 @@ const Settings = () => import('./views/settings/Settings.vue');
 // pulling a second copy into a separate chunk.
 const Stopwatch = () => import('./views/Stopwatch.vue');
 const WorkReport = () => import('./views/WorkReport.vue');
+const BillingView = () => import('./views/BillingView.vue');
 const AISummaryView = () => import('./views/AISummaryView.vue');
 const Alerts = () => import('./views/Alerts.vue');
 const Search = () => import('./views/Search.vue');
@@ -83,6 +84,7 @@ const router = new VueRouter({
     },
     { path: '/stopwatch', component: Stopwatch },
     { path: '/work-report', component: WorkReport },
+    { path: '/billing', component: BillingView },
     { path: '/analysis/activity', component: AISummaryView },
     { path: '/search', component: Search },
     { path: '/graph', component: Graph },

src/views/BillingView.vue

@@ -0,0 +1,349 @@
+<template lang="pug">
+div
+  h3.mb-3 Billable Hours Export
+
+  div.row.mb-4
+    div.col-md-4
+      b-form-group(label="Hosts" label-class="font-weight-bold")
+        b-form-select(v-model="selectedHosts" :options="hostOptions" multiple :select-size="4")
+        small.text-muted Select devices to include
+
+    div.col-md-4
+      b-form-group(label="Date Range" label-class="font-weight-bold")
+        b-form-select(v-model="dateRange" :options="dateRangeOptions")
+
+    div.col-md-4
+      b-form-group(label="Hourly Rate (optional)" label-class="font-weight-bold")
+        b-input-group(prepend="$")
+          b-form-input(
+            v-model.number="defaultRate"
+            type="number"
+            min="0"
+            step="0.01"
+            placeholder="0.00"
+          )
+        small.text-muted Default rate applied to all categories. Override per row below.
+
+  div.mb-3
+    b-button(@click="loadData" variant="primary" :disabled="loading")
+      icon(name="sync")
+      |  Calculate Hours
+    b-button.ml-2(@click="exportCSV" variant="outline-secondary" :disabled="!hasData")
+      icon(name="download")
+      |  Export CSV
+
+  div(v-if="loading")
+    b-spinner.mr-2
+    | Loading...
+
+  div(v-if="errorMessage")
+    b-alert(variant="danger" show) {{ errorMessage }}
+
+  div(v-if="hasData && !loading")
+    div.row.mb-2
+      div.col
+        small.text-muted
+          | Period: {{ periodLabel }} · Total: {{ formatDuration(totalDuration) }}
+          span(v-if="defaultRate > 0")  · Est. Total: {{ formatAmount(totalAmount) }}
+
+    table.table.table-sm.table-hover
+      thead
+        tr
+          th Category
+          th.text-right Hours
+          th.text-right Rate ($/h)
+          th.text-right Amount
+      tbody
+        tr(v-for="row in categoryRows" :key="row.key")
+          td
+            span.badge.mr-1(:style="{ background: '#6c757d', color: 'white' }") {{ row.depth > 0 ? '↳ ' : '' }}
+            | {{ row.label }}
+          td.text-right {{ formatHours(row.duration) }}
+          td.text-right
+            b-form-input(
+              v-model.number="categoryRates[row.key]"
+              type="number"
+              min="0"
+              step="0.01"
+              size="sm"
+              style="width: 80px; display: inline-block"
+              :placeholder="defaultRate > 0 ? String(defaultRate) : '0.00'"
+            )
+          td.text-right {{ formatAmount(getAmount(row)) }}
+      tfoot
+        tr.font-weight-bold
+          td Total
+          td.text-right {{ formatHours(totalDuration) }}
+          td.text-right —
+          td.text-right {{ formatAmount(totalAmount) }}
+</template>
+
+<script lang="ts">
+import moment from 'moment';
+import { getClient } from '~/util/awclient';
+import { useCategoryStore } from '~/stores/categories';
+import { useSettingsStore } from '~/stores/settings';
+import { useBucketsStore } from '~/stores/buckets';
+import { get_day_start_with_offset, get_day_end_with_offset } from '~/util/time';
+import {
+  getSupportedWorkReportHosts,
+  getWorkReportHostOptions,
+  getUnsupportedWorkReportHosts,
+} from '~/util/workReport';
+
+import 'vue-awesome/icons/sync';
+import 'vue-awesome/icons/download';
+
+interface CategoryRow {
+  key: string; // JSON.stringify(parts) — unambiguous identity for rate lookup
+  category: string; // parts.join(' > ') — display label in UI and CSV
+  label: string;
+  depth: number;
+  duration: number;
+}
+
+function buildBillingQuery(hosts: string[], categoriesStr: string): string {
+  let query = '';
+  for (let hi = 0; hi < hosts.length; hi++) {
+    const h = hosts[hi];
+    query += `
+events_${hi} = flood(query_bucket("aw-watcher-window_${h}"));
+not_afk_${hi} = flood(query_bucket("aw-watcher-afk_${h}"));
+not_afk_${hi} = filter_keyvals(not_afk_${hi}, "status", ["not-afk"]);
+events_${hi} = filter_period_intersect(events_${hi}, not_afk_${hi});
+events_${hi} = categorize(events_${hi}, ${categoriesStr});`;
+  }
+  query += '\nevents = [];';
+  for (let hi = 0; hi < hosts.length; hi++) {
+    query += `\nevents = union_no_overlap(events, events_${hi});`;
+  }
+  query += `
+duration = sum_durations(events);
+RETURN = {"events": events, "duration": duration};`;
+  return query
+    .split('\n')
+    .map(line => line.replace(/\s+$/, ''))
+    .join('\n');
+}
+
+export default {
+  name: 'BillingView',
+  data() {
+    return {
+      categoryStore: useCategoryStore(),
+      settingsStore: useSettingsStore(),
+      bucketsStore: useBucketsStore(),
+
+      selectedHosts: [] as string[],
+      dateRange: 'thisMonth',
+      defaultRate: 0,
+      categoryRates: {} as Record<string, number>,
+
+      loading: false,
+      errorMessage: '',
+      categoryRows: [] as CategoryRow[],
+      totalDuration: 0,
+      queriedPeriod: '' as string,
+    };
+  },
+  computed: {
+    hostOptions() {
+      return getWorkReportHostOptions(this.bucketsStore.buckets || []);
+    },
+    dateRangeOptions() {
+      return [
+        { value: 'thisMonth', text: 'This month' },
+        { value: 'last30d', text: 'Last 30 days' },
+        { value: 'thisWeek', text: 'This week' },
+        { value: 'last7d', text: 'Last 7 days' },
+      ];
+    },
+    hasData() {
+      return this.categoryRows.length > 0;
+    },
+    totalAmount() {
+      return this.categoryRows.reduce((sum, row) => sum + this.getAmount(row), 0);
+    },
+    periodLabel() {
+      const tp = this.queriedPeriod || this.getTimeperiod();
+      const [start, end] = tp.split('/');
+      return `${moment(start).format('MMM D')} – ${moment(end).format('MMM D, YYYY')}`;
+    },
+  },
+  async mounted() {
+    this.categoryStore.load();
+    await this.bucketsStore.ensureLoaded();
+    if (this.hostOptions.length > 0) {
+      this.selectedHosts = this.hostOptions.filter(opt => !opt.disabled).map(opt => opt.value);
+    }
+  },
+  methods: {
+    getTimeperiod(): string {
+      const offset = this.settingsStore.startOfDay;
+      let startDate: moment.Moment;
+      const today = moment();
+
+      if (this.dateRange === 'thisMonth') {
+        startDate = moment().startOf('month');
+      } else if (this.dateRange === 'last30d') {
+        startDate = today.clone().subtract(29, 'days');
+      } else if (this.dateRange === 'thisWeek') {
+        startDate = moment().startOf('isoWeek');
+      } else {
+        startDate = today.clone().subtract(6, 'days');
+      }
+
+      const start = get_day_start_with_offset(startDate, offset);
+      const end = get_day_end_with_offset(today, offset);
+      return `${start}/${end}`;
+    },
+
+    async loadData() {
+      this.loading = true;
+      this.errorMessage = '';
+      try {
+        const client = getClient();
+
+        if (this.selectedHosts.length === 0) {
+          this.errorMessage = 'Please select at least one host.';
+          return;
+        }
+
+        const unsupported = getUnsupportedWorkReportHosts(
+          this.selectedHosts,
+          this.bucketsStore.buckets || []
+        );
+        const hostsToQuery = getSupportedWorkReportHosts(
+          this.selectedHosts,
+          this.bucketsStore.buckets || []
+        );
+        if (hostsToQuery.length === 0) {
+          this.errorMessage = `No supported hosts (require aw-watcher-afk): ${unsupported.join(
+            ', '
+          )}`;
+          return;
+        }
+
+        const categories = this.categoryStore.classes_for_query;
+        const categoriesStr = JSON.stringify(categories).replace(/\\\\/g, '\\');
+        const query = buildBillingQuery(hostsToQuery, categoriesStr);
+        const tp = this.getTimeperiod();
+
+        const [result] = await client.query([tp], [query]);
+        // Only update queriedPeriod after a successful query so that on
+        // failure the existing rows continue to display with their correct period.
+        this.queriedPeriod = tp;
+        const events: any[] = result.events || [];
+        this.totalDuration = result.duration || 0;
+
+        // Aggregate duration by category path.
+        // Key: JSON.stringify(parts) — unambiguous even if a segment contains ' > '.
+        const durationMap: Record<string, number> = {};
+        for (const event of events) {
+          const cat: string[] = event.data?.['$category'] || ['Uncategorized'];
+          const key = JSON.stringify(cat);
+          durationMap[key] = (durationMap[key] || 0) + event.duration;
+        }
+
+        // Build rows sorted by display label.
+        this.categoryRows = Object.entries(durationMap)
+          .sort(([a], [b]) => a.localeCompare(b))
+          .map(([key, duration]) => {
+            const parts: string[] = JSON.parse(key);
+            return {
+              key,
+              category: parts.join(' > '),
+              label: parts[parts.length - 1],
+              depth: parts.length - 1,
+              duration,
+            };
+          });
+      } catch (err: any) {
+        this.errorMessage = `Error loading data: ${err?.message || err}`;
+        console.error(err);
+      } finally {
+        this.loading = false;
+      }
+    },
+
+    getEffectiveRate(row: CategoryRow): number {
+      const explicit = this.categoryRates[row.key];
+      // Treat explicitly-entered 0 as "not billable" (don't fall back to defaultRate).
+      // Only fall back when the field has never been touched (undefined/null/'').
+      if (explicit !== undefined && explicit !== null && explicit !== '') return Number(explicit);
+      return this.defaultRate || 0;
+    },
+
+    getAmount(row: CategoryRow): number {
+      return (row.duration / 3600) * this.getEffectiveRate(row);
+    },
+
+    formatHours(seconds: number): string {
+      return (seconds / 3600).toFixed(2);
+    },
+
+    formatDuration(seconds: number): string {
+      const h = Math.floor(seconds / 3600);
+      const m = Math.floor((seconds % 3600) / 60);
+      return `${h}h ${m}m`;
+    },
+
+    formatAmount(amount: number): string {
+      if (!amount) return '—';
+      return `$${amount.toFixed(2)}`;
+    },
+
+    exportCSV() {
+      const tp = this.queriedPeriod || this.getTimeperiod();
+      const [start, end] = tp.split('/');
+      const header = [
+        `# Billable Hours Export`,
+        `# Period: ${moment(start).format('YYYY-MM-DD')} to ${moment(end).format('YYYY-MM-DD')}`,
+        `# Generated: ${moment().format('YYYY-MM-DD HH:mm')}`,
+        '',
+      ].join('\n');
+
+      const cols = ['Category', 'Hours', 'Rate ($/h)', 'Amount ($)'];
+      const rows = this.categoryRows.map(row => {
+        const rate = this.getEffectiveRate(row);
+        const amount = this.getAmount(row);
+        return [
+          '"' + row.category.replace(/"/g, '""') + '"',
+          (row.duration / 3600).toFixed(2),
+          rate > 0 ? rate.toFixed(2) : '',
+          amount > 0 ? amount.toFixed(2) : '',
+        ].join(',');
+      });
+      const totalRate = '';
+      const totalAmountStr = this.totalAmount > 0 ? this.totalAmount.toFixed(2) : '';
+      const totalsRow = [
+        '"TOTAL"',
+        (this.totalDuration / 3600).toFixed(2),
+        totalRate,
+        totalAmountStr,
+      ].join(',');
+
+      const csv = header + [cols.join(','), ...rows, '', totalsRow].join('\n');
+      this.downloadFile(csv, `billable-hours-${moment(start).format('YYYY-MM')}.csv`, 'text/csv');
+    },
+
+    downloadFile(content: string, filename: string, mimeType: string) {
+      const blob = new Blob([content], { type: mimeType });
+      const url = URL.createObjectURL(blob);
+      const a = document.createElement('a');
+      a.href = url;
+      a.download = filename;
+      document.body.appendChild(a);
+      a.click();
+      document.body.removeChild(a);
+      URL.revokeObjectURL(url);
+    },
+  },
+};
+</script>
+
+<style scoped>
+.table {
+  font-size: 0.9rem;
+}
+</style>