@arcforgelabs/flow 2026.10.25 → 2026.10.26

package/server/ui/invoicing.js

@@ -0,0 +1,451 @@
+// Invoices: the list (/invoices) and one invoice (/invoices/new,
+// /invoices/<id>). A draft is edited in place; issuing gives it its number
+// and keeps the document exactly as sent. Money is whole cents on the wire
+// and dollars on screen. The server works out every total; the totals here
+// are a preview with the same rule (GST 10% per line, rounded half away from
+// zero, server/core/money.js). Data comes from /api/invoicing
+// (server/api/invoicing.js). app.js passes in its shared pieces as `ui`.
+
+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']];
+
+const money = new Intl.NumberFormat('en-AU', { style: 'currency', currency: 'AUD' });
+export const formatCents = (cents) => money.format((cents ?? 0) / 100);
+
+function gstCents(lineAmountCents) {
+  const sign = Math.sign(lineAmountCents);
+  const abs = Math.abs(lineAmountCents) * 1000;
+  return sign * Math.floor((abs * 2 + 10_000) / 20_000);
+}
+
+// Dollars typed by a person, to whole cents; null when it is not a number.
+function toCents(text) {
+  const clean = String(text ?? '').replace(/[$,\s]/g, '');
+  if (!/^-?\d+(\.\d{0,2})?$/.test(clean)) return null;
+  return Math.round(Number(clean) * 100);
+}
+
+const fromCents = (cents) => (cents == null ? '' : (cents / 100).toFixed(2));
+
+function localDate(date = new Date()) {
+  const pad = (n) => String(n).padStart(2, '0');
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+}
+
+const showDate = (iso) => (iso ? new Date(`${iso}T00:00:00`).toLocaleDateString('en-AU', { day: 'numeric', month: 'short', year: 'numeric' }) : '—');
+
+// ── 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 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 host = h('div', { class: 'fx-panel' }, h('div', { class: 'fx-skeleton' }));
+  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),
+    host);
+
+  let timer;
+  search.addEventListener('input', () => {
+    clearTimeout(timer);
+    timer = setTimeout(() => { state.q = search.value.trim(); load(); }, 200);
+  });
+
+  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}`);
+    } catch (error) {
+      host.replaceChildren(notice(error.message, 'danger'));
+      return;
+    }
+    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(); },
+    }, label, h('span', { class: 'fx-tabs__count' }, String(body.counts?.[id] ?? 0)))));
+    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.`));
+      return;
+    }
+    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'))),
+      h('tbody', {}, body.invoices.map((invoice) => {
+        const href = `/invoices/${invoice.id}`;
+        return h('tr', { tabindex: '0', onclick: () => go(href), onkeydown: (event) => { if (event.key === 'Enter') go(href); } },
+          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 ?? '—'),
+          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])));
+      }))));
+  }
+  await load();
+}
+
+// ── One invoice ────────────────────────────────────────────────────────────
+
+export async function renderInvoice(main, ui, id) {
+  const { h, flow, notice } = ui;
+  const host = h('div', { class: 'fx-invoice' }, h('div', { class: 'fx-skeleton' }));
+  main.append(host);
+  let context;
+  let invoice = null;
+  try {
+    [context, invoice] = await Promise.all([
+      flow('/api/invoicing/context'),
+      id === 'new' ? null : flow(`/api/invoicing/invoices/${id}`).then((body) => body.invoice),
+    ]);
+  } catch (error) {
+    host.replaceChildren(notice(error.status === 404 ? 'No invoice here. It may have been removed.' : error.message, 'danger'));
+    return;
+  }
+  // Send to Xero shows only when Xero is on and connected (404 while it is off).
+  const organisationId = context.organisations[0]?.id;
+  const xero = organisationId ? await flow(`/api/xero/status?organisationId=${organisationId}`).catch(() => null) : null;
+  context.xero = Boolean(xero?.connected);
+  const draw = (current) => {
+    host.replaceChildren(...(current?.status && current.status !== 'draft'
+      ? issuedView(current, ui, context, draw)
+      : draftView(current, ui, context, draw)));
+  };
+  draw(invoice);
+}
+
+function crumbs(ui, label) {
+  const { h, go } = ui;
+  return h('nav', { class: 'fx-crumbs', 'aria-label': 'Breadcrumb' },
+    h('a', { href: '/invoices', onclick: go }, 'Invoices'), h('span', { 'aria-hidden': 'true' }, '/'), h('span', {}, label));
+}
+
+function totalsBox(ui, { subtotalCents, taxCents, totalCents }) {
+  const { h } = ui;
+  return h('dl', { class: 'fx-totals' },
+    h('dt', {}, 'Subtotal'), h('dd', {}, formatCents(subtotalCents)),
+    h('dt', {}, 'GST'), h('dd', {}, formatCents(taxCents)),
+    h('dt', { class: 'fx-totals__grand' }, 'Total'), h('dd', { class: 'fx-totals__grand' }, formatCents(totalCents)));
+}
+
+function jobCard(ui, job) {
+  const { h } = ui;
+  if (!job) return null;
+  return h('section', { class: 'fx-card fx-side-card' },
+    h('h3', { class: 'fx-label' }, 'Job'),
+    h('dl', { class: 'fx-facts' },
+      h('dt', {}, 'Case'), h('dd', {}, job.caseRef ?? job.sourceJobRef),
+      job.practitioner ? [h('dt', {}, 'Practitioner'), h('dd', {}, job.practitioner)] : null,
+      job.shippedOn ? [h('dt', {}, 'Shipped'), h('dd', {}, showDate(job.shippedOn))] : null,
+      h('dt', {}, 'From'), h('dd', {}, job.sourceSystem === 'seazona' ? 'Seazona' : job.sourceSystem)));
+}
+
+// A draft, or a new invoice before its first save.
+function draftView(invoice, ui, context, redraw) {
+  const { h, flow, toast, go } = 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 });
+  let contact = invoice?.contact ?? null;
+
+  // Client: type to find a customer.
+  const clientInput = h('input', { class: 'fx-input', type: 'text', autocomplete: 'off', placeholder: 'Type a client name', value: contact?.name ?? '', 'aria-label': 'Client' });
+  const clientList = h('div', { class: 'fx-suggest', role: 'listbox', hidden: true });
+  let clientTimer;
+  clientInput.addEventListener('input', () => {
+    contact = null;
+    clearTimeout(clientTimer);
+    clientTimer = setTimeout(async () => {
+      const q = clientInput.value.trim();
+      if (!q) { clientList.hidden = true; return; }
+      try {
+        const { contacts } = await flow(`/api/invoicing/contacts?${new URLSearchParams({ q, limit: '8' })}`);
+        clientList.replaceChildren(...(contacts.length ? contacts.map((c) => h('button', {
+          type: 'button',
+          role: 'option',
+          onmousedown: (event) => {
+            event.preventDefault();
+            contact = c;
+            clientInput.value = c.name;
+            clientList.hidden = true;
+          },
+        }, c.name, c.email ? h('span', { class: 'fx-dim' }, c.email) : null)) : [h('p', { class: 'fx-dim fx-suggest__none' }, 'No client by that name.')]));
+        clientList.hidden = false;
+      } catch (error) {
+        toast(error.message, 'danger');
+      }
+    }, 180);
+  });
+  clientInput.addEventListener('blur', () => { setTimeout(() => { clientList.hidden = true; }, 120); });
+
+  const reference = h('input', { class: 'fx-input', type: 'text', value: invoice?.reference ?? '', placeholder: 'Case or order number' });
+  const dueDate = h('input', { class: 'fx-input', type: 'date', value: invoice?.dueDate ?? '' });
+
+  // Lines.
+  let items = null;
+  const itemsReady = flow('/api/invoicing/price-items').then((body) => { items = body.priceItems ?? body.items ?? []; return items; }).catch(() => { items = []; return items; });
+  const tbody = h('tbody');
+  const datalist = h('datalist', { id: 'fx-price-items' });
+  const totalsHost = h('div');
+  const preview = () => {
+    let subtotalCents = 0;
+    let taxCents = 0;
+    for (const line of lines) {
+      if (line.unitAmountCents == null || !(line.quantity > 0)) continue;
+      const amount = line.quantity * line.unitAmountCents;
+      subtotalCents += amount;
+      taxCents += line.taxCode === 'GST' ? gstCents(amount) : 0;
+    }
+    totalsHost.replaceChildren(totalsBox(ui, { subtotalCents, taxCents, totalCents: subtotalCents + taxCents }));
+  };
+
+  const drawLines = () => {
+    tbody.replaceChildren(...lines.map((line, index) => {
+      const amount = h('td', { class: 'fx-num fx-strong' });
+      const showAmount = () => {
+        amount.textContent = line.unitAmountCents == null || !(line.quantity > 0) ? '—' : formatCents(line.quantity * line.unitAmountCents);
+      };
+      showAmount();
+      const item = h('input', {
+        class: 'fx-input', type: 'text', list: 'fx-price-items', placeholder: 'Code or name', autocomplete: 'off',
+        value: line.itemCode ?? '', 'aria-label': `Item, line ${index + 1}`,
+      });
+      const description = h('input', { class: 'fx-input', type: 'text', value: line.description ?? '', 'aria-label': `Description, line ${index + 1}` });
+      const quantity = h('input', { class: 'fx-input fx-num', type: 'number', min: '1', step: '1', value: String(line.quantity ?? 1), 'aria-label': `Quantity, line ${index + 1}` });
+      const price = h('input', { class: 'fx-input fx-num', type: 'text', inputmode: 'decimal', value: fromCents(line.unitAmountCents), placeholder: '0.00', 'aria-label': `Unit price, line ${index + 1}` });
+      const gst = h('select', { class: 'fx-select', 'aria-label': `GST, line ${index + 1}` },
+        h('option', { value: 'GST', selected: line.taxCode !== 'GST_FREE' }, 'GST'),
+        h('option', { value: 'GST_FREE', selected: line.taxCode === 'GST_FREE' }, 'GST free'));
+      item.addEventListener('change', async () => {
+        const list = items ?? await itemsReady;
+        const typed = item.value.trim().toLowerCase();
+        const match = list.find((i) => i.code.toLowerCase() === typed || `${i.code} · ${i.name}`.toLowerCase() === typed || i.name.toLowerCase() === typed);
+        if (!match) { line.priceItemId = null; line.itemCode = null; return; }
+        Object.assign(line, { priceItemId: match.id, itemCode: match.code, description: match.name, unitAmountCents: match.unitAmountCents, taxCode: match.taxCode });
+        item.value = match.code;
+        description.value = match.name;
+        price.value = fromCents(match.unitAmountCents);
+        gst.value = match.taxCode;
+        showAmount();
+        preview();
+      });
+      description.addEventListener('input', () => { line.description = description.value; });
+      quantity.addEventListener('input', () => { line.quantity = Number.parseInt(quantity.value, 10); showAmount(); preview(); });
+      price.addEventListener('input', () => { line.unitAmountCents = toCents(price.value); showAmount(); preview(); });
+      gst.addEventListener('change', () => { line.taxCode = gst.value; preview(); });
+      const remove = h('button', {
+        class: 'fx-btn fx-btn--ghost fx-btn--sm fx-btn--icon', type: 'button', title: 'Remove line', 'aria-label': `Remove line ${index + 1}`,
+        onclick: () => { lines.splice(index, 1); if (!lines.length) lines.push({ description: '', quantity: 1, unitAmountCents: null, taxCode: 'GST', priceItemId: null }); drawLines(); preview(); },
+      }, '×');
+      return h('tr', {},
+        h('td', { class: 'fx-lines__item' }, item),
+        h('td', {}, description),
+        h('td', { class: 'fx-lines__qty' }, quantity),
+        h('td', { class: 'fx-lines__price' }, price),
+        h('td', { class: 'fx-lines__gst' }, gst),
+        amount,
+        h('td', {}, remove));
+    }));
+  };
+  drawLines();
+  preview();
+  itemsReady.then((list) => {
+    // A saved line knows its price item by id; show the item's code.
+    const codes = new Map(list.map((i) => [i.id, i.code]));
+    let named = false;
+    for (const line of lines) {
+      if (line.priceItemId && !line.itemCode && codes.has(line.priceItemId)) { line.itemCode = codes.get(line.priceItemId); named = true; }
+    }
+    if (named) drawLines();
+    datalist.replaceChildren(...list.map((i) => h('option', { value: i.code }, `${i.name} · ${formatCents(i.unitAmountCents)}`)));
+  });
+
+  const body = () => ({
+    contactId: contact?.id,
+    reference: reference.value.trim() || null,
+    dueDate: dueDate.value || null,
+    lines: lines
+      .filter((line) => line.description?.trim() || line.priceItemId || line.unitAmountCents != null)
+      .map(({ priceItemId, description, quantity, unitAmountCents, taxCode }) => ({
+        ...(priceItemId ? { priceItemId } : {}),
+        description: description?.trim() || undefined,
+        quantity: Number.isInteger(quantity) && quantity > 0 ? quantity : 1,
+        ...(unitAmountCents == null ? {} : { unitAmountCents }),
+        taxCode,
+      })),
+  });
+
+  const check = () => {
+    if (!contact) return 'Choose a client from the list.';
+    if (lines.some((line) => (line.description?.trim() || line.priceItemId) && line.unitAmountCents == null)) return 'Each line needs a price.';
+    return null;
+  };
+
+  const save = async () => {
+    const problem = check();
+    if (problem) { toast(problem, 'danger'); return null; }
+    try {
+      const res = isNew
+        ? await flow('/api/invoicing/invoices', { method: 'POST', body: JSON.stringify(body()) })
+        : await flow(`/api/invoicing/invoices/${invoice.id}`, { method: 'PATCH', body: JSON.stringify(body()) });
+      return res.invoice;
+    } catch (error) {
+      toast(error.message, 'danger');
+      return null;
+    }
+  };
+
+  const saveButton = h('button', {
+    class: 'fx-btn', type: 'button',
+    onclick: async () => {
+      const saved = await save();
+      if (!saved) return;
+      toast('Draft saved.', 'success');
+      if (isNew) go(`/invoices/${saved.id}`, { replace: true });
+      else redraw(saved);
+    },
+  }, 'Save draft');
+  const issueButton = context.canIssue ? h('button', {
+    class: 'fx-btn fx-btn--primary', type: 'button',
+    onclick: async () => {
+      const saved = await save();
+      if (!saved) return;
+      const ok = await ui.dialog({
+        title: 'Issue this invoice?',
+        body: h('p', {}, `It gets the next number (${context.organisations[0]?.invoicePrefix ?? ''}${String(context.organisations[0]?.nextInvoiceNumber ?? '').padStart(4, '0')}) and is kept exactly as issued. To change it later, revise it.`),
+        confirm: 'Issue',
+      });
+      if (!ok) { if (isNew) go(`/invoices/${saved.id}`, { replace: true }); else redraw(saved); return; }
+      try {
+        const { invoice: issued } = await flow(`/api/invoicing/invoices/${saved.id}/issue`, { method: 'POST', body: JSON.stringify({ issueDate: localDate() }) });
+        toast(`${issued.number} issued.`, 'success');
+        if (isNew) go(`/invoices/${issued.id}`, { replace: true });
+        else redraw(issued);
+      } catch (error) {
+        toast(error.message, 'danger');
+      }
+    },
+  }, 'Issue invoice') : null;
+
+  return [
+    crumbs(ui, isNew ? 'New invoice' : '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('div', { class: 'fx-invoice__grid' },
+      h('div', { class: 'fx-invoice__main' },
+        h('section', { class: 'fx-card fx-invoice__head' },
+          h('label', { class: 'fx-field fx-field--client' }, h('span', { class: 'fx-label' }, 'Client'), h('div', { class: 'fx-suggest-host' }, clientInput, clientList)),
+          h('label', { class: 'fx-field' }, h('span', { class: 'fx-label' }, 'Reference'), reference),
+          h('label', { class: 'fx-field' }, h('span', { class: 'fx-label' }, 'Due date'), dueDate)),
+        h('section', { class: 'fx-card fx-lines' },
+          datalist,
+          h('table', { class: 'fx-lines__table' },
+            h('thead', {}, h('tr', {},
+              h('th', {}, 'Item'), h('th', {}, 'Description'), h('th', { class: 'fx-num' }, 'Qty'),
+              h('th', { class: 'fx-num' }, 'Unit price'), h('th', {}, 'Tax'), h('th', { class: 'fx-num' }, 'Amount'),
+              h('th', {}, h('span', { class: 'fx-sr' }, 'Remove')))),
+            tbody),
+          h('div', { class: 'fx-lines__foot' },
+            h('button', { class: 'fx-btn fx-btn--ghost fx-btn--sm', type: 'button', onclick: () => { lines.push({ description: '', quantity: 1, unitAmountCents: null, taxCode: 'GST', priceItemId: null }); drawLines(); } }, '+ Add line'),
+            totalsHost))),
+      h('aside', { class: 'fx-invoice__aside' }, jobCard(ui, invoice?.job))),
+  ];
+}
+
+// An issued or void invoice: the document as sent, and what can happen next.
+function issuedView(invoice, ui, context, redraw) {
+  const { h, flow, toast } = ui;
+  const act = async (path, done, confirmText) => {
+    if (confirmText) {
+      const ok = await ui.dialog(confirmText);
+      if (!ok) return;
+    }
+    try {
+      const res = await flow(`/api/invoicing/invoices/${invoice.id}/${path}`, { method: 'POST', body: '{}' });
+      toast(done, 'success');
+      redraw(res.invoice);
+    } catch (error) {
+      toast(error.message, 'danger');
+    }
+  };
+  const actions = invoice.status === 'issued' && context.canIssue ? [
+    h('button', {
+      class: 'fx-btn fx-btn--ghost fx-btn--danger', type: 'button',
+      onclick: () => act('void', `${invoice.number} is void.`, { title: `Void ${invoice.number}?`, body: h('p', {}, 'The number stays used. A void invoice cannot be issued again.'), confirm: 'Void', tone: 'danger' }),
+    }, 'Void'),
+    h('button', { class: 'fx-btn', type: 'button', onclick: () => act('revise', `${invoice.number} is a draft again.`) }, 'Revise'),
+    sendToXero(invoice, ui, context),
+  ] : [];
+  return [
+    crumbs(ui, invoice.number),
+    h('header', { class: 'fx-ph' },
+      h('div', { class: 'fx-ph__text' },
+        h('div', { class: 'fx-row' },
+          h('h1', { class: 'fx-title' }, invoice.number),
+          h('span', { class: 'fx-status', 'data-tone': STATUS_TONE[invoice.status] }, STATUS_LABEL[invoice.status])),
+        h('p', { class: 'fx-ph__sub' }, `${invoice.contact?.name ?? ''} · issued ${showDate(invoice.issueDate)}`)),
+      h('div', { class: 'fx-ph__actions' }, actions)),
+    h('div', { class: 'fx-invoice__grid' },
+      h('div', { class: 'fx-invoice__main' },
+        h('section', { class: 'fx-card fx-doc' },
+          h('dl', { class: 'fx-doc__meta' },
+            h('div', {}, h('dt', { class: 'fx-label' }, 'Bill to'), h('dd', {}, invoice.contact?.name ?? '—', invoice.contact?.email ? h('span', { class: 'fx-dim' }, invoice.contact.email) : null)),
+            h('div', {}, h('dt', { class: 'fx-label' }, 'Reference'), h('dd', {}, invoice.reference ?? '—')),
+            h('div', {}, h('dt', { class: 'fx-label' }, 'Issued'), h('dd', {}, showDate(invoice.issueDate))),
+            h('div', {}, h('dt', { class: 'fx-label' }, 'Due'), h('dd', {}, showDate(invoice.dueDate)))),
+          h('table', { class: 'fx-lines__table fx-lines__table--read' },
+            h('thead', {}, h('tr', {}, h('th', {}, 'Description'), h('th', { class: 'fx-num' }, 'Qty'), h('th', { class: 'fx-num' }, 'Unit price'), h('th', {}, 'Tax'), h('th', { class: 'fx-num' }, 'Amount'))),
+            h('tbody', {}, invoice.lines.map((line) => h('tr', {},
+              h('td', {}, line.description),
+              h('td', { class: 'fx-num' }, String(line.quantity)),
+              h('td', { class: 'fx-num' }, formatCents(line.unitAmountCents)),
+              h('td', { class: 'fx-dim' }, line.taxCode === 'GST' ? 'GST' : 'GST free'),
+              h('td', { class: 'fx-num fx-strong' }, formatCents(line.lineAmountCents)))))),
+          h('div', { class: 'fx-lines__foot' }, h('span'), totalsBox(ui, invoice)))),
+      h('aside', { class: 'fx-invoice__aside' },
+        jobCard(ui, invoice.job),
+        invoice.versions?.length ? h('section', { class: 'fx-card fx-side-card' },
+          h('h3', { class: 'fx-label' }, 'History'),
+          h('ol', { class: 'fx-timeline' }, invoice.versions.map((v) => h('li', {},
+            h('span', { class: 'fx-strong' }, v.version === 1 ? 'Issued' : `Reissued (version ${v.version})`),
+            h('span', { class: 'fx-dim' }, new Date(v.issuedAt).toLocaleString('en-AU', { dateStyle: 'medium', timeStyle: 'short' })))))) : null)),
+  ];
+}
+
+// Send to Xero: a draft in Xero from the issued invoice (POST /api/xero/invoices/push).
+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', {
+    class: 'fx-btn fx-btn--primary', type: 'button',
+    onclick: async (event) => {
+      const button = event.currentTarget;
+      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');
+        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) {
+        toast(error.message, 'danger');
+      } finally {
+        button.disabled = false;
+      }
+    },
+  }, 'Send to Xero');
+}

package/server/ui/jobs.js

@@ -0,0 +1,153 @@
+// Jobs (/jobs): every billable job from the lab system, as a board with one
+// column per billing stage, or as a list. A job's stage follows from its
+// evidence (server/core/ledger.js ledgerView), so cards are not dragged: a
+// job moves when its evidence changes, or when someone drafts its invoice
+// here. Data comes from /api/invoicing/jobs (server/api/invoicing.js).
+
+import { formatCents } from '/assets/ui/invoicing.js';
+
+// Board columns, left to right. Held jobs sit with the jobs that need review.
+const STAGES = [
+  { id: 'review', label: 'Needs review', views: ['review_required', 'held'], tone: 'warn' },
+  { id: 'pending', label: 'Checking', views: ['pending'], tone: 'mute' },
+  { id: 'ready', label: 'Ready to bill', views: ['ready'], tone: 'info' },
+  { id: 'drafted', label: 'Drafted', views: ['drafted'], tone: 'info' },
+  { id: 'invoiced', label: 'Invoiced', views: ['invoiced'], tone: 'success' },
+  { id: 'paid', label: 'Paid', views: ['paid'], tone: 'success' },
+];
+const STAGE_OF = Object.fromEntries(STAGES.flatMap((stage) => stage.views.map((view) => [view, stage])));
+const LAYOUT_KEY = 'flow_jobs_layout';
+
+const showDate = (iso) => (iso ? new Date(`${iso}T00:00:00`).toLocaleDateString('en-AU', { day: 'numeric', month: 'short' }) : '—');
+
+function readLayout() {
+  try { return localStorage.getItem(LAYOUT_KEY) === 'list' ? 'list' : 'board'; } catch { return 'board'; }
+}
+
+function saveLayout(layout) {
+  try { localStorage.setItem(LAYOUT_KEY, layout); } catch { /* the choice is only a convenience */ }
+}
+
+export async function renderJobs(main, ui) {
+  const { h, flow, pageHeader, notice } = ui;
+  const state = { layout: readLayout(), q: '', jobs: [], canDraft: false };
+  const toggle = h('div', { class: 'fx-seg', role: 'radiogroup', 'aria-label': 'Layout' });
+  const search = h('input', { class: 'fx-input fx-search', type: 'search', placeholder: 'Find a case, client or practitioner', 'aria-label': 'Find a job' });
+  const host = h('div', { class: 'fx-jobs' }, h('div', { class: 'fx-skeleton' }));
+  main.classList.add('fx-main--wide');
+  main.append(
+    pageHeader('Jobs', { subtitle: 'Every billable job from the lab system, by billing stage.' }),
+    h('div', { class: 'fx-toolbar fx-toolbar--plain' }, search, toggle),
+    host);
+
+  const drawToggle = () => toggle.replaceChildren(...[['board', 'Board'], ['list', 'List']].map(([id, label]) => h('button', {
+    type: 'button', role: 'radio', class: 'fx-seg__item', 'aria-checked': String(state.layout === id),
+    onclick: () => { state.layout = id; saveLayout(id); drawToggle(); draw(); },
+  }, label)));
+  drawToggle();
+  search.addEventListener('input', () => { state.q = search.value.trim().toLowerCase(); draw(); });
+
+  const visible = () => (state.q
+    ? state.jobs.filter((job) => [job.caseRef, job.sourceJobRef, job.contactName, job.practitioner, job.invoiceNumber]
+      .some((value) => value && String(value).toLowerCase().includes(state.q)))
+    : state.jobs);
+
+  function draw() {
+    if (!state.jobs.length) {
+      host.replaceChildren(h('div', { class: 'fx-panel fx-empty' },
+        h('p', {}, 'No jobs yet. Jobs appear here once the lab system is connected under Integrations.'),
+        h('a', { class: 'fx-btn', href: '/invoices/new', onclick: ui.go }, 'Make an invoice by hand')));
+      return;
+    }
+    host.replaceChildren(state.layout === 'list' ? list(visible()) : board(visible()));
+  }
+
+  async function load() {
+    try {
+      const [{ jobs }, context] = await Promise.all([flow('/api/invoicing/jobs'), flow('/api/invoicing/context')]);
+      state.jobs = jobs;
+      state.canDraft = context.canIssue;
+    } catch (error) {
+      host.replaceChildren(notice(error.message, 'danger'));
+      return;
+    }
+    draw();
+  }
+
+  function action(job) {
+    if (job.invoiceId) {
+      const href = `/invoices/${job.invoiceId}`;
+      return h('a', { class: 'fx-btn fx-btn--ghost fx-btn--sm', href, onclick: ui.go }, job.invoiceNumber ?? 'Open draft');
+    }
+    if (job.view !== 'ready' || !state.canDraft) return null;
+    return h('button', {
+      class: 'fx-btn fx-btn--primary fx-btn--sm', type: 'button',
+      onclick: async (event) => {
+        event.stopPropagation();
+        const button = event.currentTarget;
+        button.disabled = true;
+        try {
+          const { invoice } = await flow(`/api/invoicing/jobs/${job.id}/draft`, { method: 'POST', body: '{}' });
+          ui.toast('Draft invoice made.', 'success');
+          ui.go(`/invoices/${invoice.id}`);
+        } catch (error) {
+          const reasons = error.details?.reasons;
+          ui.toast(reasons?.length ? `Not drafted: ${reasons.join('; ')}.` : error.message, 'danger');
+          button.disabled = false;
+          await load();
+        }
+      },
+    }, 'Draft invoice');
+  }
+
+  function card(job) {
+    const stage = STAGE_OF[job.view];
+    const reasons = ['review', 'pending'].includes(stage?.id) ? job.reasons?.join('; ') : '';
+    const why = reasons ? reasons[0].toUpperCase() + reasons.slice(1) + '.' : null;
+    return h('article', { class: `fx-job${stage?.id === 'review' ? ' fx-job--flag' : ''}` },
+      h('div', { class: 'fx-job__top' },
+        h('span', { class: 'fx-strong' }, job.caseRef ?? job.sourceJobRef),
+        h('span', { class: 'fx-job__amount' }, formatCents(job.totalCents))),
+      h('div', { class: 'fx-job__client' }, job.contactName ?? 'No client'),
+      h('div', { class: 'fx-job__meta' },
+        job.practitioner ? h('span', {}, job.practitioner) : null,
+        h('span', {}, `Shipped ${showDate(job.shippedOn)}`)),
+      why ? h('p', { class: 'fx-job__why' }, why) : null,
+      action(job));
+  }
+
+  function board(jobs) {
+    return h('div', { class: 'fx-board' }, STAGES.map((stage) => {
+      const inStage = jobs.filter((job) => stage.views.includes(job.view));
+      const total = inStage.reduce((sum, job) => sum + (job.totalCents ?? 0), 0);
+      return h('section', { class: 'fx-board__col', 'aria-label': stage.label },
+        h('header', { class: 'fx-board__head' },
+          h('span', { class: 'fx-board__dot', 'data-tone': stage.tone }),
+          h('span', { class: 'fx-strong' }, stage.label),
+          h('span', { class: 'fx-board__count' }, String(inStage.length)),
+          h('span', { class: 'fx-board__sum' }, inStage.length ? formatCents(total) : '')),
+        h('div', { class: 'fx-board__cards' }, inStage.length ? inStage.map(card) : h('p', { class: 'fx-board__none' }, 'None')));
+    }));
+  }
+
+  function list(jobs) {
+    if (!jobs.length) return h('div', { class: 'fx-panel' }, h('p', { class: 'fx-empty' }, 'No job matches that search.'));
+    return h('div', { class: 'fx-panel' }, h('table', { class: 'fx-table' },
+      h('thead', {}, h('tr', {},
+        h('th', {}, 'Case'), h('th', {}, 'Client'), h('th', {}, 'Practitioner'), h('th', {}, 'Shipped'),
+        h('th', {}, 'Stage'), h('th', { class: 'fx-num' }, 'Total'), h('th', { class: 'fx-table__actions' }, h('span', { class: 'fx-sr' }, 'Action')))),
+      h('tbody', {}, jobs.map((job) => {
+        const stage = STAGE_OF[job.view];
+        return h('tr', {},
+          h('td', { class: 'fx-strong' }, job.caseRef ?? job.sourceJobRef),
+          h('td', {}, job.contactName ?? '—'),
+          h('td', { class: 'fx-dim' }, job.practitioner ?? '—'),
+          h('td', { class: 'fx-dim' }, showDate(job.shippedOn)),
+          h('td', {}, h('span', { class: 'fx-status', 'data-tone': stage?.tone ?? 'mute', title: job.reasons?.join('; ') ?? '' }, stage?.label ?? job.view)),
+          h('td', { class: 'fx-num fx-strong' }, formatCents(job.totalCents)),
+          h('td', { class: 'fx-table__actions' }, action(job)));
+      }))));
+  }
+
+  await load();
+}

package/server/ui/logos/seazona.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" role="img"><title>Seazona</title><path fill="#F04037" d="M6 3H26L22 13H21L18 24H22L23 23V27L22 29H8L9 25L11 19V13H7L6 9Z"/></svg>

package/server/ui/logos/xero.svg

@@ -0,0 +1 @@
+<svg role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg" fill="#13B5EA"><title>Xero</title><path d="M12 0C5.373 0 0 5.373 0 12s5.373 12 12 12 12-5.373 12-12S18.627 0 12 0zm6.585 14.655c-1.485 0-2.69-1.206-2.69-2.689 0-1.485 1.207-2.691 2.69-2.691 1.485 0 2.69 1.207 2.69 2.691s-1.207 2.689-2.69 2.689zM7.53 14.644c-.099 0-.192-.041-.267-.116l-2.043-2.04-2.052 2.047c-.069.068-.16.108-.258.108-.202 0-.368-.166-.368-.368 0-.099.04-.191.111-.263l2.04-2.05-2.038-2.047c-.075-.069-.113-.162-.113-.261 0-.203.166-.366.368-.366.098 0 .188.037.258.105l2.055 2.048 2.048-2.045c.069-.071.162-.108.26-.108.211 0 .375.165.375.366 0 .098-.029.188-.104.258l-2.056 2.055 2.055 2.051c.068.069.104.16.104.258 0 .202-.165.368-.365.368h-.01zm8.017-4.591c-.796.101-.882.476-.882 1.404v2.787c0 .202-.165.366-.366.366-.203 0-.367-.165-.368-.366v-4.53c0-.204.16-.366.362-.366.166 0 .316.125.346.289.27-.209.6-.317.93-.317h.105c.195 0 .359.165.359.368 0 .201-.164.352-.375.359 0 0-.09 0-.164.008l.053-.002zm-3.091 2.205H8.625c0 .019.003.037.006.057.02.105.045.211.083.31.194.531.765 1.275 1.829 1.29.33-.003.631-.086.9-.229.21-.12.391-.271.525-.428.045-.058.09-.112.12-.168.18-.229.405-.186.54-.083.164.135.18.391.045.57l-.016.016c-.21.27-.435.495-.689.66-.255.164-.525.284-.811.345-.33.09-.645.104-.975.06-1.095-.135-2.01-.93-2.28-2.01-.06-.21-.09-.42-.09-.645 0-.855.421-1.695 1.125-2.205.885-.615 2.085-.66 3-.075.63.405 1.035 1.021 1.185 1.771.075.419-.21.794-.734.81l.068-.046zm6.129-2.223c-1.064 0-1.931.865-1.931 1.931 0 1.064.866 1.931 1.931 1.931s1.931-.867 1.931-1.931c0-1.065-.866-1.933-1.931-1.933v.002zm0 2.595c-.367 0-.666-.297-.666-.666 0-.367.3-.665.666-.665.367 0 .667.299.667.665 0 .369-.3.667-.667.666zm-8.04-2.603c-.91 0-1.672.623-1.886 1.466v.03h3.776c-.203-.855-.973-1.494-1.891-1.494v-.002z"/></svg>

package/server/ui/routes.js

@@ -17,8 +17,10 @@ import { themeStylesheet } from '../theme/themes.js';
 const require = createRequire(import.meta.url);
 const here = dirname(fileURLToPath(import.meta.url));
 const themeDir = join(here, '..', 'theme');
+const logoDir = join(here, 'logos');
+const LOGO_FILES = new Set(['xero.svg', 'seazona.svg']);
 const THEME_FILES = new Set(['themes.js', 'color-contrast.js', 'openclaw-palettes.js', 'font-families.js']);
-const UI_FILES = new Set(['flow.css', 'appearance.js', 'clerk-appearance.js', 'app.js', 'flow-mark.svg']);
+const UI_FILES = new Set(['flow.css', 'appearance.js', 'clerk-appearance.js', 'app.js', 'invoicing.js', 'jobs.js', 'flow-mark.svg']);
 const MAX_AGE = '1h';
 
 // Send one named file from dir. Passing dir as root limits the dotfile check
@@ -44,6 +46,8 @@ export function createUiAssetsRouter({ rateLimitPerMinute = 600 } = {}) {
   };
   router.get('/assets/theme/:file', sendFrom(themeDir, THEME_FILES));
   router.get('/assets/ui/:file', sendFrom(here, UI_FILES));
+  // Each integration's logo, the maker's own mark (Integrations).
+  router.get('/assets/ui/logos/:file', sendFrom(logoDir, LOGO_FILES));
 
   for (const name of FONT_PACKAGES) {
     const dir = dirname(require.resolve(`@fontsource-variable/${name}/LICENSE`));