@arcforgelabs/flow 2026.10.26 → 2026.10.29

package/server/ui/invoicing-settings.js

@@ -0,0 +1,110 @@
+// Settings, Invoicing (/invoicing-settings): payment terms, the draft
+// automation, and the lab's own rules a ready job passes before Flow drafts
+// its invoice (invoice-rules.js, docs/INVOICE_RULES.md). Invoicing needs no integration: how an invoice
+// goes to Xero is on the Xero integration page (sendModeSection).
+// Draft when ready is an automation (server/core/automations.js); the
+// Seazona integration page holds the rule that marks a job ready.
+// One row for each setting: its name, one short line, and its control. A
+// change saves at once. Everyone can read them; an owner or admin changes
+// them. The full rules are in docs/INVOICING_RULES.md. app.js passes in its
+// shared pieces as `ui`.
+
+import { automationSection } from '/assets/ui/automations.js';
+import { rulesSection } from '/assets/ui/invoice-rules.js';
+import { lineMappingSection } from '/assets/ui/line-mappings.js';
+
+const DOCS = 'https://github.com/arcforgelabs/flow/blob/main/docs/INVOICING_RULES.md';
+
+const SEND_MODES = [
+  { value: 'accounting_draft', label: 'Xero draft' },
+  { value: 'approve_and_email', label: 'Approved and emailed' },
+];
+
+export async function renderInvoicingSettings(main, ui) {
+  const { h, flow, toast, notice, pageHeader, me } = ui;
+  const host = h('div', { class: 'fx-card', style: { padding: '8px 20px 16px' } }, h('div', { class: 'fx-skeleton' }));
+  main.append(pageHeader('Invoicing', { subtitle: 'How Flow drafts invoices. No integration needed.' }), host);
+  let body;
+  try {
+    body = await flow('/api/invoicing/settings');
+  } catch (error) {
+    host.replaceChildren(notice(error.message, 'danger'));
+    return;
+  }
+  const disabled = !['owner', 'admin'].includes(me?.person.role);
+  let saved = body.settings;
+
+  async function save(changes, control) {
+    control.disabled = true;
+    try {
+      saved = (await flow('/api/invoicing/settings', { method: 'PUT', body: JSON.stringify(changes) })).settings;
+      toast('Saved.', 'success');
+      return true;
+    } catch (error) {
+      toast(error.message, 'danger');
+      return false;
+    } finally {
+      control.disabled = false;
+    }
+  }
+
+  const row = (name, hint, control) => h('div', { class: 'fx-set__row' },
+    h('div', { class: 'fx-set__text' }, h('span', { class: 'fx-set__name' }, name), h('span', { class: 'fx-set__hint' }, hint)),
+    h('div', { class: 'fx-set__control' }, control));
+
+  // A text or number box saves when it loses focus with a new value.
+  const box = (key, label, { type = 'text', read = (v) => v, show = (v) => v ?? '', placeholder } = {}) => {
+    const input = h('input', { class: 'fx-input', type, value: show(saved[key]), 'aria-label': label, disabled, placeholder });
+    input.addEventListener('change', async () => {
+      if (!(await save({ [key]: read(input.value) }, input))) input.value = show(saved[key]);
+    });
+    return input;
+  };
+  const days = (key, label) => box(key, label, { type: 'number', read: Number });
+
+  const section = (title, ...rows) => h('section', { class: 'fx-set' }, h('h2', { class: 'fx-set__title' }, title), ...rows);
+  host.replaceChildren(...[
+    disabled ? notice('Only an owner or admin can change these.', 'info') : null,
+    section('Drafts',
+      row('Payment terms', 'Days from invoice to due date.', days('paymentTermsDays', 'Payment terms in days'))),
+    lineMappingSection(ui),
+    automationSection(ui, 'invoicing', 'Automations'),
+    rulesSection(ui),
+  ].filter(Boolean));
+}
+
+// The Xero integration page's "Sending" section: how a checked invoice goes to
+// Xero. A customer can have its own mode (/api/invoicing/contacts/:id/billing).
+export function sendModeSection(ui) {
+  const { h, flow, toast, notice, me } = ui;
+  const disabled = !['owner', 'admin'].includes(me?.person.role);
+  const select = h('select', { class: 'fx-select', 'aria-label': 'Send to Xero as', disabled },
+    SEND_MODES.map((m) => h('option', { value: m.value }, m.label)));
+  const section = h('section', { class: 'fx-set' }, h('h2', { class: 'fx-set__title' }, 'Sending'),
+    h('div', { class: 'fx-set__row' },
+      h('div', { class: 'fx-set__text' }, h('span', { class: 'fx-set__name' }, 'Send to Xero as'), h('span', { class: 'fx-set__hint' }, 'Draft: approve in Xero. Approved: Xero emails it.')),
+      h('div', { class: 'fx-set__control' }, select)),
+    h('p', { class: 'fx-dim', style: { margin: '8px 0 0' } }, h('a', { href: DOCS, target: '_blank', rel: 'noopener' }, 'How sending works')));
+  let saved = null;
+  (async () => {
+    try {
+      saved = (await flow('/api/invoicing/settings')).settings;
+      select.value = saved.sendMode;
+    } catch (error) {
+      section.append(notice(error.message, 'danger'));
+    }
+  })();
+  select.addEventListener('change', async () => {
+    select.disabled = true;
+    try {
+      saved = (await flow('/api/invoicing/settings', { method: 'PUT', body: JSON.stringify({ sendMode: select.value }) })).settings;
+      toast('Saved.', 'success');
+    } catch (error) {
+      toast(error.message, 'danger');
+      if (saved) select.value = saved.sendMode;
+    } finally {
+      select.disabled = disabled;
+    }
+  });
+  return section;
+}

package/server/ui/invoicing.js

@@ -8,7 +8,20 @@
 
 const STATUS_LABEL = { draft: 'Draft', issued: 'Issued', void: 'Void' };
 const STATUS_TONE = { draft: 'info', issued: 'success', void: 'mute' };
-const TABS = [['draft', 'Drafts'], ['issued', 'Issued'], ['void', 'Void']];
+// Drafts (to check), Problem and Ready are views (server/core/sending.js):
+// every draft is in one of them. A person marks a checked draft ready; any
+// later change sends it back. An issued invoice that failed to send is a
+// problem.
+const TABS = [['to_check', 'Drafts'], ['problem', 'Problem'], ['ready', 'Ready'], ['issued', 'Issued'], ['void', 'Void']];
+const VIEW_LABEL = { problem: 'Problem', ready: 'Ready', sending: 'Sending', to_check: 'Draft' };
+const VIEW_TONE = { problem: 'danger', ready: 'success', sending: 'info', to_check: 'info' };
+const EMPTY = {
+  to_check: 'No drafts to check. Press New invoice to start one.',
+  problem: 'No problems.',
+  ready: 'Nothing is ready. Tick drafts and press Mark ready.',
+};
+// Tabs whose rows can be ticked, and what the ticked rows can do.
+const TICKS = { to_check: true, ready: true };
 
 const money = new Intl.NumberFormat('en-AU', { style: 'currency', currency: 'AUD' });
 export const formatCents = (cents) => money.format((cents ?? 0) / 100);
@@ -38,16 +51,21 @@ const showDate = (iso) => (iso ? new Date(`${iso}T00:00:00`).toLocaleDateString(
 // ── The list ───────────────────────────────────────────────────────────────
 
 export async function renderInvoiceList(main, ui) {
-  const { h, flow, pageHeader, notice, go } = ui;
-  const state = { status: sessionStorage.getItem('flow_invoice_tab') || 'draft', q: '' };
+  const { h, flow, pageHeader, notice, go, toast } = ui;
+  const saved = sessionStorage.getItem('flow_invoice_tab');
+  const state = { status: TABS.some(([id]) => id === saved) ? saved : 'to_check', q: '', ticked: new Set() };
   const tabs = h('div', { class: 'fx-tabs', role: 'tablist' });
   const search = h('input', { class: 'fx-input fx-search', type: 'search', placeholder: 'Find a number, client or reference', 'aria-label': 'Find an invoice' });
+  const bar = h('div', { class: 'fx-sendbar', hidden: true });
   const host = h('div', { class: 'fx-panel' }, h('div', { class: 'fx-skeleton' }));
+  const context = await flow('/api/invoicing/context').catch(() => ({ canIssue: false }));
+  let body = null;
   main.append(
     pageHeader('Invoices', {
       actions: [h('a', { class: 'fx-btn fx-btn--primary', href: '/invoices/new', onclick: go }, 'New invoice')],
     }),
     h('div', { class: 'fx-toolbar' }, tabs, search),
+    bar,
     host);
 
   let timer;
@@ -56,8 +74,62 @@ export async function renderInvoiceList(main, ui) {
     timer = setTimeout(() => { state.q = search.value.trim(); load(); }, 200);
   });
 
+  const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;
+  const action = (label, path, payload, done, tone = 'primary') => {
+    const el = h('button', {
+      class: `fx-btn fx-btn--${tone}`, type: 'button',
+      onclick: async () => {
+        el.disabled = true;
+        try {
+          const res = await flow(`/api/invoicing/invoices/${path}`, { method: 'POST', body: JSON.stringify(payload()) });
+          toast(...done(res));
+          state.ticked.clear();
+          await load();
+        } catch (error) {
+          toast(error.message, 'danger');
+          el.disabled = false;
+        }
+      },
+    }, label);
+    return el;
+  };
+
+  // The bar above the list: what a person can do with this view.
+  function drawBar() {
+    const to = body.sendsTo;
+    const ticked = [...state.ticked];
+    const parts = [];
+    if (state.status === 'to_check') {
+      parts.push(h('p', { class: 'fx-dim' }, ticked.length ? `${plural(ticked.length, 'draft', 'drafts')} ticked.` : 'Check each draft, tick it, then mark it ready.'));
+      if (ticked.length) {
+        parts.push(action(`Mark ${ticked.length} ready`, 'mark-ready', () => ({ invoiceIds: ticked }), (res) => (res.refused.length
+          ? [`${res.marked} ready. ${plural(res.refused.length, 'draft has', 'drafts have')} a problem and moved to Problem.`, 'danger']
+          : [`${plural(res.marked, 'draft', 'drafts')} ready.`, 'success'])));
+      }
+    } else if (state.status === 'ready') {
+      parts.push(h('p', { class: 'fx-dim' }, to ? `Each invoice is issued, then goes to ${to}.` : 'Each invoice is issued. No accounting system is on.'));
+      const buttons = [];
+      if (ticked.length) {
+        buttons.push(action(`Back to drafts (${ticked.length})`, 'mark-not-ready', () => ({ invoiceIds: ticked }),
+          (res) => [`${plural(res.moved, 'invoice', 'invoices')} back in Drafts.`, 'success'], 'ghost'));
+      }
+      if (context.canIssue && body.counts.ready > 0) {
+        buttons.push(action(to ? `Send all ${body.counts.ready} ready to ${to}` : `Issue all ${body.counts.ready} ready`, 'send-ready', () => ({ issueDate: localDate() }),
+          (res) => [`${res.issued} issued.${to ? ` They are on the way to ${to}.` : ''}${res.remaining ? ` ${res.remaining} more are ready: press again.` : ''}`, 'success']));
+      }
+      if (buttons.length) parts.push(h('div', { class: 'fx-sendbar__actions' }, buttons));
+    } else if (state.status === 'problem') {
+      const failed = body.invoices.filter((i) => i.status === 'issued').length;
+      if (context.canIssue && to && failed > 0) {
+        parts.push(h('p', { class: 'fx-dim' }, `${plural(failed, 'issued invoice', 'issued invoices')} did not reach ${to}. Fix the cause, then send again.`));
+        parts.push(action('Send again', 'send-again', () => ({}), (res) => [`${res.queued} on the way to ${to} again.`, 'success']));
+      }
+    }
+    bar.replaceChildren(...parts);
+    bar.hidden = !parts.length;
+  }
+
   async function load() {
-    let body;
     try {
       const query = new URLSearchParams({ status: state.status, ...(state.q ? { q: state.q } : {}) });
       body = await flow(`/api/invoicing/invoices?${query}`);
@@ -65,31 +137,65 @@ export async function renderInvoiceList(main, ui) {
       host.replaceChildren(notice(error.message, 'danger'));
       return;
     }
+    const shown = new Set(body.invoices.map((i) => i.id));
+    for (const id of state.ticked) if (!shown.has(id)) state.ticked.delete(id);
     tabs.replaceChildren(...TABS.map(([id, label]) => h('button', {
       type: 'button',
       role: 'tab',
       'aria-selected': String(state.status === id),
-      onclick: () => { state.status = id; sessionStorage.setItem('flow_invoice_tab', id); load(); },
+      ...(id === 'problem' && body.counts?.problem ? { 'data-tone': 'danger' } : {}),
+      onclick: () => { state.status = id; state.ticked.clear(); sessionStorage.setItem('flow_invoice_tab', id); load(); },
     }, label, h('span', { class: 'fx-tabs__count' }, String(body.counts?.[id] ?? 0)))));
+    drawBar();
     if (!body.invoices.length) {
       host.replaceChildren(h('p', { class: 'fx-empty' }, state.q
         ? 'No invoice matches that search.'
-        : state.status === 'draft' ? 'No drafts. Press New invoice to start one.' : `No ${STATUS_LABEL[state.status].toLowerCase()} invoices yet.`));
+        : EMPTY[state.status] ?? `No ${STATUS_LABEL[state.status].toLowerCase()} invoices yet.`));
       return;
     }
+    const ticks = TICKS[state.status];
+    const showProblem = state.status === 'problem';
+    const created = ['to_check', 'problem', 'ready'].includes(state.status);
+    const boxes = [];
+    const tickBox = (invoice) => {
+      const box = h('input', {
+        type: 'checkbox', class: 'fx-tick', 'aria-label': `Tick ${invoice.number ?? 'draft'} for ${invoice.contactName ?? 'no client'}`,
+        ...(state.ticked.has(invoice.id) ? { checked: true } : {}),
+        onclick: (event) => event.stopPropagation(),
+        onchange: () => { if (box.checked) state.ticked.add(invoice.id); else state.ticked.delete(invoice.id); all.checked = state.ticked.size === body.invoices.length; drawBar(); },
+      });
+      boxes.push(box);
+      return box;
+    };
+    const all = h('input', {
+      type: 'checkbox', class: 'fx-tick', 'aria-label': 'Tick every invoice shown',
+      onchange: () => {
+        for (const invoice of body.invoices) { if (all.checked) state.ticked.add(invoice.id); else state.ticked.delete(invoice.id); }
+        for (const box of boxes) box.checked = all.checked;
+        drawBar();
+      },
+    });
     host.replaceChildren(h('table', { class: 'fx-table fx-table--rows' },
       h('thead', {}, h('tr', {},
-        h('th', {}, 'Number'), h('th', {}, 'Client'), h('th', {}, 'Reference'),
-        h('th', {}, state.status === 'draft' ? 'Created' : 'Issued'), h('th', { class: 'fx-num' }, 'Total'), h('th', {}, 'Status'))),
+        ticks ? h('th', { class: 'fx-tick-cell' }, all) : null,
+        h('th', {}, 'Number'), h('th', {}, 'Client'), h('th', {}, showProblem ? 'Problem' : 'Reference'),
+        h('th', {}, created ? 'Created' : 'Issued'), h('th', { class: 'fx-num' }, 'Total'), h('th', {}, 'Status'))),
       h('tbody', {}, body.invoices.map((invoice) => {
         const href = `/invoices/${invoice.id}`;
+        const first = invoice.problems?.[0];
+        const view = invoice.status === 'void' ? null : invoice.view;
         return h('tr', { tabindex: '0', onclick: () => go(href), onkeydown: (event) => { if (event.key === 'Enter') go(href); } },
+          ticks ? h('td', { class: 'fx-tick-cell', onclick: (event) => event.stopPropagation() }, tickBox(invoice)) : null,
           h('td', {}, h('a', { class: 'fx-strong', href, onclick: go }, invoice.number ?? 'Draft')),
           h('td', {}, invoice.contactName ?? '—'),
-          h('td', { class: 'fx-dim' }, invoice.job?.caseRef ?? invoice.reference ?? '—'),
+          showProblem
+            ? h('td', { class: 'fx-problem' }, first?.message ?? '—', invoice.problems.length > 1 ? h('span', { class: 'fx-dim' }, ` +${invoice.problems.length - 1} more`) : null)
+            : h('td', { class: 'fx-dim' }, invoice.job?.caseRef ?? invoice.reference ?? '—'),
           h('td', { class: 'fx-dim' }, showDate(invoice.issueDate ?? invoice.createdAt?.slice(0, 10))),
           h('td', { class: 'fx-num fx-strong' }, formatCents(invoice.totalCents)),
-          h('td', {}, h('span', { class: 'fx-status', 'data-tone': STATUS_TONE[invoice.status] }, STATUS_LABEL[invoice.status])));
+          h('td', {}, view
+            ? h('span', { class: 'fx-status', 'data-tone': VIEW_TONE[view] }, VIEW_LABEL[view])
+            : h('span', { class: 'fx-status', 'data-tone': STATUS_TONE[invoice.status] }, STATUS_LABEL[invoice.status])));
       }))));
   }
   await load();
@@ -152,7 +258,7 @@ function jobCard(ui, job) {
 
 // A draft, or a new invoice before its first save.
 function draftView(invoice, ui, context, redraw) {
-  const { h, flow, toast, go } = ui;
+  const { h, flow, toast, go, notice } = ui;
   const isNew = !invoice;
   const lines = (invoice?.lines ?? []).map((line) => ({ ...line }));
   if (!lines.length) lines.push({ description: '', quantity: 1, unitAmountCents: null, taxCode: 'GST', priceItemId: null });
@@ -337,13 +443,42 @@ function draftView(invoice, ui, context, redraw) {
     },
   }, 'Issue invoice') : null;
 
+  // Mark ready: the draft is saved, then Flow checks it; one with a problem
+  // stays a draft. Back to drafts undoes it.
+  const ready = invoice?.view === 'ready';
+  const readyButton = isNew ? null : h('button', {
+    class: 'fx-btn', type: 'button',
+    onclick: async () => {
+      const current = ready ? invoice : await save();
+      if (!current) return;
+      try {
+        if (ready) {
+          await flow('/api/invoicing/invoices/mark-not-ready', { method: 'POST', body: JSON.stringify({ invoiceIds: [invoice.id] }) });
+          toast('Back in Drafts.', 'success');
+        } else {
+          const res = await flow('/api/invoicing/invoices/mark-ready', { method: 'POST', body: JSON.stringify({ invoiceIds: [invoice.id] }) });
+          if (res.marked) toast('Ready to send.', 'success');
+          else toast(res.refused[0]?.problems.map((p) => p.message).join(' ') ?? 'It has a problem.', 'danger');
+        }
+        const { invoice: fresh } = await flow(`/api/invoicing/invoices/${invoice.id}`);
+        redraw(fresh);
+      } catch (error) {
+        toast(error.message, 'danger');
+      }
+    },
+  }, ready ? 'Back to drafts' : 'Mark ready');
+  const problems = invoice?.problems?.length
+    ? notice(invoice.problems.map((p) => p.message).join(' '), 'danger', 'Problem.')
+    : null;
+
   return [
-    crumbs(ui, isNew ? 'New invoice' : 'Draft'),
+    crumbs(ui, isNew ? 'New invoice' : ready ? 'Ready' : 'Draft'),
     h('header', { class: 'fx-ph' },
       h('div', { class: 'fx-ph__text' },
-        h('h1', { class: 'fx-title' }, isNew ? 'New invoice' : 'Draft invoice'),
-        h('p', { class: 'fx-ph__sub' }, 'The number is given when you issue it.')),
-      h('div', { class: 'fx-ph__actions' }, saveButton, issueButton)),
+        h('h1', { class: 'fx-title' }, isNew ? 'New invoice' : ready ? 'Ready invoice' : 'Draft invoice'),
+        h('p', { class: 'fx-ph__sub' }, ready ? 'A person checked it. Send all ready issues it. A change sends it back to Drafts.' : 'The number is given when you issue it.')),
+      h('div', { class: 'fx-ph__actions' }, saveButton, readyButton, issueButton)),
+    problems,
     h('div', { class: 'fx-invoice__grid' },
       h('div', { class: 'fx-invoice__main' },
         h('section', { class: 'fx-card fx-invoice__head' },
@@ -425,20 +560,24 @@ function issuedView(invoice, ui, context, redraw) {
   ];
 }
 
-// Send to Xero: a draft in Xero from the issued invoice (POST /api/xero/invoices/push).
+// Send to Xero (POST /api/xero/invoices/push). The customer's send mode
+// (Settings, Invoicing) decides what Xero gets: a draft that a person approves
+// there, or an approved invoice that Xero emails to the customer.
 function sendToXero(invoice, ui, context) {
   const { h, flow, toast } = ui;
   const organisationId = context.organisations[0]?.id;
   if (!organisationId || !context.xero) return null;
-  return h('button', {
+  const button = h('button', {
     class: 'fx-btn fx-btn--primary', type: 'button',
-    onclick: async (event) => {
-      const button = event.currentTarget;
+    onclick: async () => {
       button.disabled = true;
       try {
         const res = await flow('/api/xero/invoices/push', { method: 'POST', body: JSON.stringify({ organisationId, invoiceIds: [invoice.id] }) });
         const result = res.invoices?.[0];
-        if (['created', 'reconciled', 'existing'].includes(result?.outcome)) toast(`${invoice.number} is in Xero as a draft.`, 'success');
+        const email = result?.email;
+        if (email && ['failed', 'unknown'].includes(email.state)) toast(email.error, 'danger');
+        else if (email?.state === 'sent') toast(`${invoice.number} is approved in Xero, and Xero emailed it to the customer.`, 'success');
+        else if (['created', 'reconciled', 'existing'].includes(result?.outcome)) toast(`${invoice.number} is in Xero as a draft.`, 'success');
         else if (result?.outcome === 'already_in_xero') toast(`Xero already has ${invoice.number}.`, 'info');
         else toast(result?.error?.message ?? 'Xero did not take it.', 'danger');
       } catch (error) {
@@ -448,4 +587,11 @@ function sendToXero(invoice, ui, context) {
       }
     },
   }, 'Send to Xero');
+  // The preview reads only Flow's copy of Xero: it costs no Xero calls.
+  flow('/api/xero/invoices/preview', { method: 'POST', body: JSON.stringify({ organisationId, invoiceIds: [invoice.id] }) })
+    .then((res) => {
+      if (res.invoices?.[0]?.sendMode === 'approve_and_email') button.textContent = 'Send to Xero and email';
+    })
+    .catch(() => {});
+  return button;
 }

package/server/ui/job-board.js

@@ -0,0 +1,155 @@
+// The Jobs board's rules, with no page code, so tests can read them
+// (test/job-board.test.js). server/ui/jobs.js draws the page.
+//
+// The board's columns are the work system's own job statuses, one to one.
+// A job's invoice has a stage of its own (invoiceStage), shown in the job's
+// detail panel; a job whose invoice needs a person has a problem (fixes).
+
+// Where a status sits on the board when the work system gives no order:
+// first the statuses of new work, then the ones Flow does not know (in the
+// order Flow first saw them), then checking, complete, shipped, delivered,
+// and cancelled last.
+const STATUS_RANKS = [
+  [/\b(new|draft|received|booked|submitted|ordered|pending)\b/i, 0],
+  [/\b(scan|scanned|design|designed|model|wax|impression)/i, 1],
+  [/\b(qc|quality|check|checked|checking|finish|finished|finishing)\b/i, 3],
+  [/\bcomplete(d)?\b|\bready\b/i, 4],
+  [/\b(shipped|dispatched|sent)\b/i, 5],
+  [/\bdelivered\b/i, 6],
+  [/\b(cancell?ed|void|closed|archived|deleted)\b/i, 7],
+];
+const UNKNOWN_RANK = 2;
+// From this rank on, the work is out of the lab: shipped, delivered, cancelled.
+export const FINAL_RANK = 5;
+export const NO_STATUS = 'No status';
+
+export function statusRank(label) {
+  return STATUS_RANKS.find(([pattern]) => pattern.test(label ?? ''))?.[1] ?? UNKNOWN_RANK;
+}
+
+// The board's column labels, left to right. `statuses` is the work system's
+// list ({ label, firstSeenAt }); `jobs` adds any status only a job names.
+export function orderStatuses(statuses = [], jobs = []) {
+  const seen = new Map();
+  for (const s of statuses) if (s?.label && !seen.has(s.label)) seen.set(s.label, s.firstSeenAt ?? null);
+  for (const job of jobs) {
+    const label = job.status ?? NO_STATUS;
+    if (!seen.has(label)) seen.set(label, null);
+  }
+  return [...seen].sort(([a, at], [b, bt]) => statusRank(a) - statusRank(b)
+    || String(at ?? '9').localeCompare(String(bt ?? '9'))
+    || a.localeCompare(b)).map(([label]) => label);
+}
+
+export const INVOICE_STAGES = {
+  drafted: 'Drafted', problem: 'Problem', ready: 'Ready to invoice', invoiced: 'Invoiced', paid: 'Paid',
+};
+
+const PROBLEM_VIEWS = ['pending', 'review_required', 'held'];
+// A rule's reason, as ruleBlockers writes it (server/core/invoicing-rules.js).
+const isRule = (reason) => reason !== 'the job is not marked ready to invoice';
+
+// The stage of a job's invoice, from its billing obligation (the API's job
+// shape, server/core/job-board.js), or null while the job has none or is
+// still in work.
+//   Drafted           a draft in Flow that nobody marked ready, or a job
+//                     that passes every check and waits for the automation
+//   Problem           something a person must fix: the job's checks, a rule
+//                     that stops the draft, or a problem with the draft
+//   Ready to invoice  a person marked the draft ready
+//   Invoiced          issued, sent, or in the accounting system
+//   Paid              paid in full
+export function invoiceStage(o) {
+  if (!o || o.view === 'in_work') return null;
+  if (o.view === 'paid') return 'paid';
+  if (PROBLEM_VIEWS.includes(o.view)) return 'problem';
+  if (o.view === 'invoiced') return 'invoiced';
+  if (o.invoiceView === 'problem' || o.invoiceStatus === 'void') return 'problem';
+  if (o.invoiceStatus === 'issued') return 'invoiced';
+  if (o.invoiceView === 'ready') return 'ready';
+  if (o.view === 'ready') return (o.waitingFor ?? []).some(isRule) ? 'problem' : 'drafted';
+  if (o.view === 'drafted') return 'drafted';
+  return null;
+}
+
+const capital = (text) => (text ? text[0].toUpperCase() + text.slice(1) : text);
+const sentence = (text) => capital(String(text).trim().replace(/\.?$/, '.'));
+
+// One ledger reason (server/core/ledger.js) as a fix: a short label, what is
+// wrong, and what to do.
+function reasonFix(reason, acct) {
+  const fix = (label, todo) => ({ label, text: sentence(reason), todo });
+  if (reason === 'the accounting system was not checked') {
+    return { label: `Not checked in ${acct}`, text: `Flow did not check ${acct} for an invoice for this job yet.`, todo: `Wait for the next check, a few minutes. If it stays, check ${acct} under Settings, Integrations.` };
+  }
+  if (reason === 'a line does not map to a price item') {
+    return { label: 'No price code', text: 'A line has a code that is not in the price list.', todo: 'Add the code to the price list, or correct the code in the work system.' };
+  }
+  if (reason === 'the job has no customer contact') {
+    return { label: 'Client not linked', text: 'The client is not linked to a customer in Flow.', todo: 'Link the client to a customer in Flow.' };
+  }
+  if (reason === 'the work system report is out of date') {
+    return { label: 'Out of date', text: 'Flow has no news of this job from the work system for more than a day.', todo: 'Check the work system under Settings, Integrations.' };
+  }
+  if (reason === 'the job changed after its invoice was made') return fix('Job changed', 'Compare the invoice with the job, then correct the invoice.');
+  if (/deleted in /i.test(reason)) return fix('Deleted', 'Check the job in the work system. Void its invoice if it has one.');
+  if (/^the accounting evidence is ambiguous/.test(reason)) return fix(`${acct} match unclear`, `Find the invoice for this job in ${acct}, then link it.`);
+  if (/^the accounting evidence is conflict/.test(reason)) return fix(`Two ${acct} invoices`, `Find the right invoice for this job in ${acct}. Void the other.`);
+  if (/^invoice .* was (voided|deleted)$/.test(reason)) return fix(`Invoice ${/voided$/.test(reason) ? 'voided' : 'deleted'}`, 'Make a new invoice, or close the job.');
+  if (/^the accounting system reports /.test(reason)) return fix(`Already in ${acct}`, `Check the invoice in ${acct}. Link it to this job if it is the right one.`);
+  if (/^the job is held$/.test(reason)) return fix('On hold', 'Release the hold when the job can be invoiced.');
+  if (/^the job is review$/.test(reason)) return fix('Needs review', 'Check the job and its invoice.');
+  if (reason === 'held') return fix('On hold', 'Release the hold when the job can be invoiced.');
+  return fix('Needs review', 'Check the job and its invoice.');
+}
+
+// One draft problem (server/core/sending.js, and the accounting system's) as a fix.
+function draftFix(problem, acct) {
+  const code = problem.code ?? '';
+  const fix = (label, todo) => ({ label, text: sentence(problem.message ?? label), todo });
+  if (code === 'no_lines') return fix('No lines', 'Open the invoice and add the lines.');
+  if (code === 'no_amount') return fix('Total is $0', 'Open the invoice and correct the amounts.');
+  if (code === 'line_no_item') return fix('No price code', 'Open the invoice and choose a price item for each line.');
+  if (code.endsWith('_item_missing')) return fix(`Item not in ${acct}`, `Add the item in ${acct}, then sync.`);
+  if (code.endsWith('_contact_missing')) return fix(`Client not in ${acct}`, `Add the client in ${acct}, then sync.`);
+  if (code.endsWith('_contact_ambiguous')) return fix(`Two ${acct} clients`, `Merge or rename the clients in ${acct}, then sync.`);
+  if (code.includes('earlier_version')) return fix(`Old copy in ${acct}`, 'Open the invoice for the steps.');
+  if (code.startsWith('send_') || code.endsWith('_push_failed') || code.endsWith('_outcome_unknown')) return fix('Not sent', 'Open the invoice and send it again.');
+  return fix('Invoice problem', 'Open the invoice to correct it.');
+}
+
+// What a person must fix on a job, in order: [{ label, text, todo }]. Empty
+// unless invoiceStage is Problem. `accountingName` names the accounting
+// system (for example Xero).
+export function fixes(o, { accountingName = null } = {}) {
+  if (invoiceStage(o) !== 'problem') return [];
+  const acct = accountingName ?? 'the accounting system';
+  const found = [];
+  if (PROBLEM_VIEWS.includes(o.view)) found.push(...(o.reasons ?? []).map((r) => reasonFix(r, acct)));
+  if (o.view === 'ready') {
+    found.push(...(o.waitingFor ?? []).filter(isRule).map((r) => ({
+      label: 'Stopped by a rule', text: sentence(r), todo: 'Draft the invoice here, or change the rule under Settings, Invoicing, Rules.',
+    })));
+  }
+  if (o.invoiceStatus === 'void') {
+    found.push({ label: 'Invoice void', text: 'The invoice for this job is void.', todo: 'Make a new invoice, or close the job.' });
+  }
+  found.push(...(o.invoiceProblems ?? []).map((p) => draftFix(p, acct)));
+  return found;
+}
+
+// The short words for a job's problems: the first label, and "+N" for more.
+export function problemSummary(found) {
+  const labels = [...new Set(found.map((f) => f.label))];
+  if (!labels.length) return '';
+  return labels.length > 1 ? `${labels[0]} +${labels.length - 1}` : labels[0];
+}
+
+// Does a job match the search text? Case, client, practitioner or invoice
+// number; the case is not shown on the board, but a person can find it.
+export function matches(job, q) {
+  if (!q) return true;
+  const needle = q.toLowerCase();
+  return [job.caseRef, job.sourceJobRef, job.clientName, job.workClientName, job.practitioner, job.obligation?.invoiceNumber]
+    .some((value) => value && String(value).toLowerCase().includes(needle));
+}