@arcforgelabs/flow 2026.10.37 → 2026.10.39

package/server/integrations/xero/settings.js

@@ -38,9 +38,10 @@ function readEnv(env, name) {
   return typeof value === 'string' ? value.trim() : '';
 }
 
-function readOnOff(env, name) {
+function readOnOff(env, name, fallback = false) {
   const raw = readEnv(env, name).toLowerCase();
-  if (raw === '' || raw === 'off') return false;
+  if (raw === '') return fallback;
+  if (raw === 'off') return false;
   if (raw === 'on') return true;
   throw new Error(`${name} must be "on", "off" or unset`);
 }
@@ -166,9 +167,9 @@ export function resolveXeroSettings(env = process.env) {
     defaultDueDays: readPositiveInteger(env, 'XERO_DEFAULT_DUE_DAYS', DEFAULT_DUE_DAYS),
     invoiceNumber,
     replayFixtures: readEnv(env, 'XERO_REPLAY_FIXTURES') || null,
-    // Free text on Xero records (references, line descriptions) can name a
-    // patient. Flow keeps it only when the lab turns this on (VISION.md).
-    keepReference: readOnOff(env, 'XERO_KEEP_REFERENCE'),
+    // Free text on Xero records (references, line descriptions) is the lab's
+    // own data, and the Import matches on it. On unless the lab turns it off.
+    keepReference: readOnOff(env, 'XERO_KEEP_REFERENCE', true),
     mirrorPageSize: Math.min(readPositiveInteger(env, 'XERO_MIRROR_PAGE_SIZE', DEFAULT_MIRROR_PAGE_SIZE), MAX_MIRROR_PAGE_SIZE),
     // The share of the day's calls the mirror leaves for drafts and people.
     mirrorReserveFraction: readFraction(env, 'XERO_MIRROR_RESERVE_FRACTION', 0.3),

package/server/ui/app-page.js

@@ -51,7 +51,7 @@ const BODY = `<div class="fx-app">
   <div id="toasts" class="fx-toasts" aria-live="polite"></div>
 </div>`;
 
-export const APP_PATHS = ['/sign-in', '/jobs', '/invoices', '/invoices/:id', '/people', '/integrations', '/integrations/:id', '/account', '/appearance', '/invoicing-settings', '/price-list', '/custom-fields'];
+export const APP_PATHS = ['/sign-in', '/jobs', '/invoices', '/invoices/:id', '/reconcile', '/reconcile/:id', '/xero-import', '/people', '/integrations', '/integrations/:id', '/account', '/appearance', '/invoicing-settings', '/price-list', '/custom-fields'];
 
 export function appPage({ defaultFamily }) {
   return renderPage({

package/server/ui/app.js

@@ -13,8 +13,11 @@ import { renderInvoice, renderInvoiceList } from '/assets/ui/invoicing.js';
 import { automationSection } from '/assets/ui/automations.js';
 import { renderInvoicingSettings, sendModeSection } from '/assets/ui/invoicing-settings.js';
 import { renderPriceList } from '/assets/ui/price-list.js';
+import { renderPriceReconcile } from '/assets/ui/price-reconcile.js';
 import { lucide, renderCustomFields } from '/assets/ui/custom-fields.js';
 import { renderJobs } from '/assets/ui/jobs.js';
+import { renderReconcile } from '/assets/ui/reconcile.js';
+import { renderXeroImport } from '/assets/ui/xero-import.js';
 import { startMonitoring } from '/assets/ui/monitoring.js';
 import { openSearch } from '/assets/ui/search.js';
 import { alertStrip } from '/assets/ui/alerts.js';
@@ -124,10 +127,41 @@ async function flow(path, options = {}) {
     headers: { Authorization: `Bearer ${token}`, ...(options.body ? { 'Content-Type': 'application/json' } : {}) },
   });
   const body = await res.json().catch(() => ({ ok: false, error: `HTTP ${res.status}` }));
-  if (!res.ok) throw Object.assign(new Error(body.error || `HTTP ${res.status}`), { status: res.status, code: body.code, details: body.details });
+  // A button that calls Xero or Seazona waits between presses (the action
+  // guard): a press too soon says how long (retryAfterMs), and a good run
+  // says its own wait (Flow-Cooldown-Ms). holdButton shows the wait.
+  if (!res.ok) throw Object.assign(new Error(body.error || `HTTP ${res.status}`), { status: res.status, code: body.code, details: body.details, retryAfterMs: body.retryAfterMs });
+  const cooldownMs = Number(res.headers.get('Flow-Cooldown-Ms'));
+  if (cooldownMs > 0 && body && typeof body === 'object') body.cooldownMs = cooldownMs;
   return body;
 }
 
+// Keeps a button off for `ms`, with the time left on it, then puts it back.
+function holdButton(button, ms) {
+  if (!button || !(ms > 0)) return;
+  clearInterval(button.fxHold);
+  const label = button.dataset.label ?? button.textContent;
+  button.dataset.label = label;
+  const until = Date.now() + ms;
+  const draw = () => {
+    const left = Math.ceil((until - Date.now()) / 1000);
+    if (left <= 0) {
+      clearInterval(button.fxHold);
+      button.textContent = label;
+      delete button.dataset.label;
+      button.removeAttribute('title');
+      button.disabled = false;
+      return;
+    }
+    const time = left < 60 ? `${left}s` : `${Math.floor(left / 60)}:${String(left % 60).padStart(2, '0')}`;
+    button.disabled = true;
+    button.textContent = `${label} · ${time}`;
+    button.title = `Flow waits before it asks again, to protect the connected system's limits. Ready in ${time}.`;
+  };
+  draw();
+  button.fxHold = setInterval(draw, 1000);
+}
+
 // ── Shared pieces ──────────────────────────────────────────────────────────
 
 function pageHeader(title, { subtitle, actions = [] } = {}) {
@@ -200,13 +234,16 @@ let me = null;
 const VIEWS = {
   jobs: { label: 'Jobs', icon: 'jobs', group: 'Work', render: (main) => renderJobs(main, ui()) },
   invoices: { label: 'Invoices', icon: 'invoices', group: 'Work', render: (main, id) => (id ? renderInvoice(main, ui(), id) : renderInvoiceList(main, ui())) },
+  reconcile: { label: 'Reconcile', icon: 'reconcile', group: 'Work', render: (main, id) => renderReconcile(main, ui(), id) },
   'invoicing-settings': { label: 'Invoice rules', icon: 'invoices', group: 'Settings', render: (main) => renderInvoicingSettings(main, ui()) },
-  'price-list': { label: 'Price list', icon: 'tag', group: 'Settings', render: (main) => renderPriceList(main, ui()) },
+  'price-list': { label: 'Price list', icon: 'tag', group: 'Settings', render: (main, id) => (id === 'reconcile' ? renderPriceReconcile(main, ui()) : renderPriceList(main, ui())) },
   'custom-fields': { label: 'Custom fields', icon: 'fields', group: 'Settings', render: (main) => renderCustomFields(main, ui()) },
   people: { label: 'People', icon: 'people', group: 'Settings', ownerOnly: true, render: renderPeople },
   integrations: { label: 'Integrations', icon: 'plug', group: 'Settings', ownerOnly: true, render: (main, id) => (id ? renderIntegration(main, id) : renderIntegrations(main)) },
   // Not in the sidebar: "Manage account" in the account menu opens the same
   // Clerk profile. The page stays for links and Search.
+  // Opened from the Xero integration page: Xero invoices against Flow's own.
+  'xero-import': { label: 'Xero import', icon: 'plug', group: 'Settings', sidebar: false, render: (main) => renderXeroImport(main, ui()) },
   account: { label: 'Account', icon: 'person', group: 'Settings', sidebar: false, render: renderAccount },
   appearance: { label: 'Appearance', icon: 'palette', group: 'Settings', render: renderAppearance },
 };
@@ -215,6 +252,7 @@ const VIEWS = {
 const ICON_PATHS = {
   jobs: '<rect x="3" y="4" width="5" height="16" rx="1"/><rect x="10" y="4" width="5" height="11" rx="1"/><rect x="17" y="4" width="4" height="14" rx="1"/>',
   invoices: '<path d="M6 3h9l4 4v14H6z"/><path d="M14 3v5h5M9 13h7M9 17h5"/>',
+  reconcile: '<path d="M4 8h13M13 4l4 4-4 4M20 16H7M11 12l-4 4 4 4"/>',
   people: '<circle cx="9" cy="8" r="3"/><path d="M3 20c0-3.5 2.7-6 6-6s6 2.5 6 6"/><path d="M16 5a3 3 0 010 6M21 20c0-3-1.6-5-4-5.7"/>',
   tag: '<path d="M3 12V4h8l10 10-8 8z"/><circle cx="7.5" cy="8.5" r="1.5"/>',
   fields: '<rect x="3" y="4" width="18" height="5" rx="1.5"/><rect x="3" y="13" width="18" height="5" rx="1.5"/><path d="M7 6.5h4M7 15.5h7"/>',
@@ -365,7 +403,7 @@ function navigate(event) {
 // The shared pieces a view module (invoicing.js) builds with. Its `go`
 // takes a path, or a link's click event.
 const ui = () => ({
-  h, flow, toast, notice, pageHeader, dialog, me,
+  h, flow, toast, notice, pageHeader, dialog, me, holdButton,
   go: (target, options) => (typeof target === 'string' ? go(target, options) : navigate(target)),
 });
 
@@ -825,6 +863,7 @@ async function renderIntegration(main, id) {
           current.id === 'xero' && current.state === 'ready' ? h('section', { class: 'fx-int-section' }, xeroConnection(body.organisations, canChange)) : null,
           current.id === 'seazona' ? h('section', { class: 'fx-int-section fx-card', style: { padding: '8px 20px 16px' } }, automationSection(ui(), 'seazona', 'Ready to invoice')) : null,
           on && current.state === 'ready' ? personSettingsSection(current) : null,
+          current.id === 'xero' && current.state === 'ready' ? xeroImportSection(body.organisations) : null,
           current.id === 'xero' ? h('section', { class: 'fx-int-section fx-card', style: { padding: '8px 20px 16px' } }, sendModeSection(ui())) : null,
           guide ? h('section', { class: 'fx-int-section' },
             h('h2', { class: 'fx-int-section__title' }, 'Set up'),
@@ -904,6 +943,53 @@ function connectProgress({ steps, started }) {
       step.label))));
 }
 
+// Xero › Import, in settings rows: how many Xero invoices to check (Review
+// opens them one at a time), the two import settings, and the history. The
+// counts come from Flow's copy of Xero; the pages are server/ui/xero-import.js.
+function xeroImportSection(organisations) {
+  const organisationId = organisations?.[0]?.id;
+  const canAct = ['owner', 'admin'].includes(me?.person?.role);
+  const count = h('span', { class: 'fx-num fx-xi-count' }, '…');
+  const copied = h('span', {}, 'Every Xero invoice Flow copied. Search it with no Xero call.');
+  const switchFor = (name, label) => {
+    const button = h('button', { class: 'fx-switch', type: 'button', role: 'switch', 'aria-label': label, 'aria-checked': 'false', disabled: true });
+    button.addEventListener('click', async () => {
+      const on = button.getAttribute('aria-checked') !== 'true';
+      button.disabled = true;
+      try {
+        const { settings } = await flow('/api/xero/import/settings', { method: 'PUT', body: JSON.stringify({ organisationId, [name]: on }) });
+        button.setAttribute('aria-checked', String(settings[name]));
+        toast('Saved.', 'success');
+      } catch (error) {
+        toast(error.message, 'danger');
+      }
+      button.disabled = !canAct;
+    });
+    return button;
+  };
+  const autoLink = switchFor('autoLink', 'Link sure matches');
+  const makeUnmatched = switchFor('makeUnmatched', 'Make Flow invoices for the rest');
+  const section = h('section', { class: 'fx-set fx-int-section fx-card', style: { padding: '8px 20px 16px' } },
+    h('h2', { class: 'fx-set__title' }, 'Import'),
+    settingRow({ label: 'To check', hint: 'Xero invoices that fit a Flow invoice or a Flow job.',
+      control: h('span', { class: 'fx-row' }, count, h('a', { class: 'fx-btn fx-btn--sm fx-btn--primary', href: '/xero-import', onclick: navigate }, 'Review')) }),
+    settingRow({ label: 'Link sure matches', hint: 'Same client, total and week, and only one fit. Flow links them.', control: autoLink }),
+    settingRow({ label: 'Make Flow invoices for the rest', hint: 'Off: they stay in the Xero history.', control: makeUnmatched }),
+    settingRow({ label: 'Xero history', hint: copied, control: h('a', { class: 'fx-btn fx-btn--sm', href: '/xero-import?show=all', onclick: navigate }, 'Search') }));
+  if (organisationId) {
+    flow(`/api/xero/import?organisationId=${organisationId}&show=check&limit=1`)
+      .then(({ counts: c, settings }) => {
+        count.replaceChildren(String(c.job_fits + c.invoice_fits));
+        copied.replaceChildren(`${Object.values(c).reduce((a, b) => a + b, 0)} Xero invoices copied, ${c.linked} in Flow. Search with no Xero call.`);
+        autoLink.setAttribute('aria-checked', String(settings.autoLink));
+        makeUnmatched.setAttribute('aria-checked', String(settings.makeUnmatched));
+        autoLink.disabled = makeUnmatched.disabled = !canAct;
+      })
+      .catch(() => count.replaceChildren('—'));
+  }
+  return section;
+}
+
 // Once Xero is on: each organisation's connection, the history copy, and
 // Connect, which goes to Xero and comes back.
 function xeroConnection(organisations, canChange) {

package/server/ui/bulk-bar.js

@@ -5,7 +5,8 @@
 // its name on hover and to a screen reader. More opens every action, with a
 // search box, grouped under small heads.
 //
-// bulkBar(ui) answers { element, draw(state) }. state = { count, onClear,
+// bulkBar(ui, { label }) answers { element, draw(state) }. label names the
+// bar for a screen reader ("Ticked invoices", "Ticked jobs"). state = { count, onClear,
 // groups: [[action]], more: [{ head, actions: [action] }] }; an action is
 // { icon, label, title?, run, primary?, iconOnly?, tone? }. title is the
 // long name, for the hover tip and the More menu. A count of 0 hides the
@@ -14,10 +15,10 @@ import { lucide } from '/assets/ui/custom-fields.js';
 
 let barCount = 0;
 
-export function bulkBar(ui) {
+export function bulkBar(ui, { label = 'Ticked invoices' } = {}) {
   const { h } = ui;
   const id = `fx-bulk-more-${++barCount}`;
-  const element = h('div', { class: 'fx-bulk', role: 'toolbar', 'aria-label': 'Ticked invoices', hidden: true });
+  const element = h('div', { class: 'fx-bulk', role: 'toolbar', 'aria-label': label, hidden: true });
   const panel = h('div', { class: 'fx-pop fx-bulk__more', id, popover: 'auto', role: 'menu' });
   let current = null;
   let busy = false;