@arcforgelabs/flow 2026.11.9 → 2026.11.10

package/server/integrations/xero/reconcile.js

@@ -105,7 +105,7 @@ export async function accountingStatus(db, runtime, organisationId, invoiceIds =
     ) p on true
     left join invoice_versions v on v.invoice_id = i.id and v.version = p.version
     -- A Flow invoice the Import page linked to a Xero invoice (links.js).
-    left join xero_invoice_links l on l.organisation_id = i.organisation_id and l.invoice_id = i.id
+    left join xero_invoice_links l on l.organisation_id = i.organisation_id and l.invoice_id = i.id and l.released_at is null
     left join xero_invoices x on x.organisation_id = i.organisation_id and x.xero_invoice_id = coalesce(p.xero_invoice_id, l.xero_invoice_id)
     where i.organisation_id = ${organisationId} ${only} ${sentOnly}`);
   const web = runtime.settings.endpoints?.web ?? 'https://go.xero.com';

package/server/integrations/xero/routes.js

@@ -8,9 +8,9 @@ import { createCustomer, linkCustomer, matchCustomer } from './create-contact.js
 import { createXeroClient } from './client.js';
 import { describePush, listPushes, MAX_BATCH, previewDrafts, pushDrafts } from './drafts.js';
 import { recordXeroEvidence, recordXeroPayments } from './ledger.js';
-import { IMPORT_STATES, importOverview, linkXeroInvoice, makeFlowInvoice, matchXero, saveImportSettings, useXeroInvoice } from './links.js';
+import { IMPORT_STATES, importOverview, linkXeroInvoice, makeFlowInvoice, matchXero, releaseXeroLink, saveImportSettings, useXeroInvoice } from './links.js';
 import { queueHistoryImport, resetImport } from './import.js';
-import { MIRROR_RESOURCES, mirrorStatus, mirrorXero, readInvoiceFromXero } from './mirror.js';
+import { MIRROR_RESOURCES, mirrorStatus, mirrorXero, readInvoiceFromXero, rereadCopy } from './mirror.js';
 import { accountingStatus, checkSentInvoices } from './reconcile.js';
 import { CUSTOM_CONNECTION, decryptToken, deleteConnection, describeConnection, readConnection, saveConnection } from './connections.js';
 import { authorizeUrl, clientCredentials, exchangeCode, fetchConnections, revokeToken, selectConnection } from './oauth.js';
@@ -415,6 +415,18 @@ export function createXeroRouter({ db, personAuth, runtime, log = console, butto
     res.json({ ok: true, results, ...(await mirrorStatus(db, organisationId)) });
   }));
 
+  // An owner asks for the whole copy to be read again; the next sync reads it.
+  router.post('/mirror/reread', ...owner, handle(log, async (req, res) => {
+    const organisationId = await requireOrganisation(db, req.body?.organisationId);
+    const resources = req.body?.resources ?? MIRROR_RESOURCES;
+    if (!Array.isArray(resources) || !resources.length || !resources.every((r) => MIRROR_RESOURCES.includes(r))) {
+      throw new FlowError('invalid', `resources must list some of: ${MIRROR_RESOURCES.join(', ')}`);
+    }
+    const status = await rereadCopy(db, organisationId, { resources: [...new Set(resources)], actor: `person:${req.person.id}` });
+    log.info?.(`[xero] organisation ${organisationId}: person ${req.person.id} asked for the copy to be read again: ${resources.join(', ')}`);
+    res.json({ ok: true, ...status });
+  }));
+
   router.get('/mirror', ...signedIn, handle(log, async (req, res) => {
     const organisationId = await requireOrganisation(db, req.query.organisationId);
     res.json({ ok: true, ...(await mirrorStatus(db, organisationId)) });
@@ -463,6 +475,14 @@ export function createXeroRouter({ db, personAuth, runtime, log = console, butto
     res.json({ ok: true, source: 'xero', ...found });
   }));
 
+  // A wrong pair: the Xero invoice's Flow invoice is void and the Xero invoice
+  // is another job's bill. Frees the Xero invoice and the jobs that point at it.
+  router.post('/import/:xeroInvoiceId/release', ...manager, handle(log, async (req, res) => {
+    const organisationId = await requireOrganisation(db, req.body?.organisationId);
+    const reason = typeof req.body?.reason === 'string' ? req.body.reason : null;
+    res.json({ ok: true, ...(await releaseXeroLink(db, organisationId, xeroId(req.params.xeroInvoiceId), { actor: `person:${req.person.id}`, reason })) });
+  }));
+
   router.post('/import/:xeroInvoiceId/make', ...manager, handle(log, async (req, res) => {
     const organisationId = await requireOrganisation(db, req.body?.organisationId);
     const jobId = req.body?.jobId == null ? null : requireInvoiceIds([req.body.jobId], 'jobId')[0];

package/server/ui/app.js

@@ -1140,6 +1140,18 @@ function seazonaHistorySection() {
   return section;
 }
 
+// How much of the last 12 months of the copy has a Reference: a low share
+// is a copy that missed it (docs/XERO.md, "Copy version").
+function copyFill(mirror) {
+  // With free text off the copy keeps no Reference: that is the setting.
+  if (mirror.cursors?.find((c) => c.resource === 'invoices')?.keptReference === false) return '';
+  const months = mirror.completeness ?? [];
+  const invoices = months.reduce((sum, m) => sum + m.invoices, 0);
+  if (!invoices) return '';
+  const withReference = months.reduce((sum, m) => sum + m.withReference, 0);
+  return ` Reference on ${withReference} of ${invoices} in the last 12 months.`;
+}
+
 // Once Xero is on: each organisation's connection, the history copy, and
 // Connect, which goes to Xero and comes back.
 function xeroConnection(organisations, canChange) {
@@ -1153,6 +1165,7 @@ function xeroConnection(organisations, canChange) {
       let control = null;
       let stopped = false;
       let refused = false;
+      let mirror = null;
       try {
         const status = await flow(`/api/xero/status?organisationId=${organisation.id}`);
         usage.replaceChildren(xeroUsage(status) ?? '');
@@ -1168,8 +1181,8 @@ function xeroConnection(organisations, canChange) {
           stopped = status.calls.all;
           refused = !status.calls.all;
         } else if (status.connected) {
-          const mirror = await flow(`/api/xero/mirror?organisationId=${organisation.id}`).catch(() => null);
-          hint = `Connected to ${status.connection?.tenantName ?? 'Xero'}.${mirror ? ` ${mirror.counts.invoices} invoices copied.` : ''}`;
+          mirror = await flow(`/api/xero/mirror?organisationId=${organisation.id}`).catch(() => null);
+          hint = `Connected to ${status.connection?.tenantName ?? 'Xero'}.${mirror ? ` ${mirror.counts.invoices} invoices copied.${copyFill(mirror)}` : ''}`;
         } else {
           hint = 'Not connected.';
         }
@@ -1185,6 +1198,22 @@ function xeroConnection(organisations, canChange) {
               toast(error.message, 'danger');
             }
           } }, status.connected ? 'Connect again' : 'Connect to Xero');
+          // The owner can ask for the whole copy to be read again (a copy
+          // that missed a field). The next sync reads it; no call now.
+          if (mirror && me?.person.role === 'owner') {
+            const reread = h('button', { class: 'fx-btn fx-btn--sm', type: 'button', title: 'Read every Xero invoice again on the next sync', onclick: async () => {
+              // One press is enough: each press starts the read again.
+              reread.disabled = true;
+              try {
+                await flow('/api/xero/mirror/reread', { method: 'POST', body: JSON.stringify({ organisationId: organisation.id }) });
+                toast('Flow reads the copy again on the next sync.');
+              } catch (error) {
+                reread.disabled = false;
+                toast(error.message, 'danger');
+              }
+            } }, 'Read again');
+            control = h('div', { class: 'fx-row' }, reread, control);
+          }
         }
       } catch (error) {
         hint = error.message;

package/server/ui/contacts.js

@@ -23,7 +23,9 @@ async function renderContactList(main, ui) {
   const search = input(h, { type: 'search', 'aria-label': 'Search', placeholder: 'Search', class: 'fx-input fx-contacts__search' });
   const kind = h('select', { class: 'fx-select', 'aria-label': 'Kind' },
     h('option', { value: 'all', selected: true }, 'All'),
-    ...KINDS.map(([value, label]) => h('option', { value }, `${label}s`)));
+    ...KINDS.map(([value, label]) => h('option', { value }, `${label}s`)),
+    // Contacts that are not clients (docs/CONTACTS.md, "Hidden contacts").
+    h('option', { value: 'hidden' }, 'Hidden'));
   const page = h('div', { class: 'fx-contacts' });
   const add = h('button', { class: 'fx-btn fx-btn--primary', type: 'button', hidden: !canEdit, onclick: () => createContact() }, 'New');
   page.append(
@@ -36,7 +38,7 @@ async function renderContactList(main, ui) {
   const draw = () => {
     const needle = search.value.trim().toLowerCase();
     const shown = rows.filter((contact) => {
-      if (kind.value !== 'all' && contact.kind !== kind.value) return false;
+      if (!['all', 'hidden'].includes(kind.value) && contact.kind !== kind.value) return false;
       if (!needle) return true;
       return [contact.name, contact.email, contact.accountNumber].some((value) => String(value ?? '').toLowerCase().includes(needle));
     });
@@ -47,7 +49,9 @@ async function renderContactList(main, ui) {
           h('td', {}, h('a', { class: 'fx-person', href: `/contacts/${contact.id}`, onclick: go },
             h('span', { class: 'fx-avatar', 'aria-hidden': 'true' }, initialsOf(contact.name)),
             h('span', { class: 'fx-person__text' },
-              h('span', { class: 'fx-person__name' }, contact.name, contact.active ? null : h('span', { class: 'fx-tag' }, 'Inactive')),
+              h('span', { class: 'fx-person__name' }, contact.name,
+                contact.active ? null : h('span', { class: 'fx-tag' }, 'Inactive'),
+                contact.hidden ? h('span', { class: 'fx-tag' }, 'Hidden') : null),
               contact.email ? h('span', { class: 'fx-person__email' }, contact.email) : null))),
           h('td', {}, KINDS.find(([value]) => value === contact.kind)?.[1] ?? contact.kind),
           h('td', {}, contact.accountNumber ?? '')))))
@@ -58,8 +62,23 @@ async function renderContactList(main, ui) {
     );
   };
 
+  // The hidden contacts are their own list: the server leaves them out of
+  // every other one.
+  let listed = null;
+  async function load() {
+    const hidden = kind.value === 'hidden' ? 'true' : 'false';
+    if (hidden === listed) return draw();
+    try {
+      ({ contacts: rows } = await flow(`/api/invoicing/contacts?kind=all&active=all&hidden=${hidden}&limit=500`));
+      listed = hidden;
+      draw();
+    } catch (error) {
+      host.replaceChildren(notice(error.message, 'danger'));
+    }
+  }
+
   search.addEventListener('input', draw);
-  kind.addEventListener('change', draw);
+  kind.addEventListener('change', load);
 
   async function createContact() {
     const name = input(h, { name: 'name', required: true, 'aria-label': 'Name' });
@@ -90,17 +109,12 @@ async function renderContactList(main, ui) {
     }
   }
 
-  try {
-    ({ contacts: rows } = await flow('/api/invoicing/contacts?kind=all&active=all&limit=200'));
-    draw();
-  } catch (error) {
-    host.replaceChildren(notice(error.message, 'danger'));
-  }
+  await load();
 }
 
 async function renderContact(main, ui, id) {
-  const { h, flow, toast, notice, pageHeader, crumbs, me } = ui;
-  const canEdit = ['owner', 'admin'].includes(me?.person.role);
+  const { h, flow, toast, notice, pageHeader, crumbs, me, go } = ui;
+  let canEdit = ['owner', 'admin'].includes(me?.person.role);
   const page = h('div', { class: 'fx-contacts' }, h('div', { class: 'fx-skeleton' }));
   main.append(page);
   let contact;
@@ -110,6 +124,8 @@ async function renderContact(main, ui, id) {
     page.replaceChildren(notice(error.message, 'danger'));
     return;
   }
+  // A merged contact is read only, and points at the one it moved into.
+  if (contact.mergedIntoId) canEdit = false;
 
   const values = {
     name: input(h, { value: contact.name ?? '' }),
@@ -176,10 +192,67 @@ async function renderContact(main, ui, id) {
     },
   }, 'Save');
 
+  // Merge (docs/CONTACTS.md, "Merge two contacts"): another contact moves
+  // into this one, which keeps its name as an alias.
+  const merge = h('button', {
+    class: 'fx-btn', type: 'button', hidden: !canEdit, title: 'Merge another contact into this one',
+    onclick: async () => {
+      const picked = await ui.pickOne({
+        title: `Merge into ${contact.name}`,
+        intro: `Its jobs, invoices, links and rules move to ${contact.name}. Its name stays as another name of ${contact.name}.`,
+        label: 'Contacts',
+        find: 'Find a contact',
+        remote: true,
+        load: async (q) => (await flow(`/api/invoicing/contacts?${new URLSearchParams({ q, kind: contact.kind, hidden: 'all', active: 'all', limit: '50' })}`)).contacts
+          .filter((row) => row.id !== contact.id),
+        item: (row) => ({ value: row.id, title: row.name, meta: row.email ?? null }),
+        empty: 'No contact has that name.',
+        confirm: 'Merge',
+      });
+      if (!picked) return;
+      merge.disabled = true;
+      try {
+        const { moved } = await flow(`/api/invoicing/contacts/${id}/merge`, { method: 'POST', body: JSON.stringify({ fromId: picked.id }) });
+        toast(`Merged: ${moved.jobs} jobs, ${moved.invoices} invoices.`, 'success');
+        go(`/contacts/${id}`);
+      } catch (error) {
+        toast(error.message, 'danger');
+        merge.disabled = false;
+      }
+    },
+  }, 'Merge');
+  const mergedNote = contact.mergedIntoId ? h('section', { class: 'fx-card fx-offer' },
+    notice('This contact moved into another.', 'info', 'Merged.'),
+    h('a', { class: 'fx-btn', href: `/contacts/${contact.mergedIntoId}`, onclick: go }, 'Open')) : null;
   const xero = h('div');
+  const billTo = h('div');
+  // A contact that is not a client (docs/CONTACTS.md, "Hidden contacts").
+  const hiddenNote = h('div');
+  const drawHidden = () => {
+    if (!contact.hidden) return hiddenNote.replaceChildren();
+    const show = canEdit ? h('button', {
+      class: 'fx-btn', type: 'button', title: 'Show this contact in the lists',
+      onclick: async () => {
+        show.disabled = true;
+        try {
+          ({ contact } = await flow(`/api/invoicing/contacts/${id}`, { method: 'PATCH', body: JSON.stringify({ hidden: false }) }));
+          toast('Shown.', 'success');
+          drawHidden();
+        } catch (error) {
+          toast(error.message, 'danger');
+          show.disabled = false;
+        }
+      },
+    }, 'Show') : null;
+    hiddenNote.replaceChildren(h('section', { class: 'fx-card fx-offer' },
+      notice('Not a client: no job and no invoice.', 'info', 'Hidden.'), show));
+  };
+  drawHidden();
   page.replaceChildren(
     crumbs(['/contacts', 'Contacts'], contact.name),
-    pageHeader(contact.name, { actions: [save] }),
+    pageHeader(contact.name, { actions: [merge, save] }),
+    mergedNote,
+    contact.mergedIntoId ? null : hiddenNote,
     h('section', { class: 'fx-card' },
       h('div', { class: 'fx-contacts__grid' },
         field(h, 'Name', values.name),
@@ -204,9 +277,67 @@ async function renderContact(main, ui, id) {
           h('span', { class: 'fx-label' }, 'Practitioners'),
           practitioners),
         h('label', { class: 'fx-check' }, active, 'Active'))),
+    billTo,
     xero,
   );
-  void loadXero(ui, contact, canEdit, xero);
+  const reloadXero = () => loadXero(ui, contact, canEdit, xero);
+  if (contact.kind === 'customer' && !contact.mergedIntoId) void loadBillTo(ui, contact, canEdit, billTo, reloadXero);
+  void reloadXero();
+}
+
+// Bill to (docs/CONTACTS.md): another customer, the payer, whose accounting
+// contact this client's work is billed to. Many clients may name one payer.
+async function loadBillTo(ui, contact, canEdit, host, changed) {
+  const { h, flow, toast, notice } = ui;
+  let payer = null;
+  const save = async (billToContactId, button) => {
+    if (button) button.disabled = true;
+    try {
+      await flow(`/api/invoicing/contacts/${contact.id}/billing`, { method: 'PUT', body: JSON.stringify({ billToContactId }) });
+      toast(billToContactId ? 'Bill to saved.' : 'Bill to cleared.', 'success');
+      await load();
+      await changed();
+    } catch (error) {
+      toast(error.message, 'danger');
+      if (button) button.disabled = false;
+    }
+  };
+  const pick = async (event) => {
+    const button = event.currentTarget;
+    const picked = await ui.pickOne({
+      title: `Bill ${contact.name} to`,
+      intro: 'Pick the customer that pays for this client. Its Xero contact gets the invoices.',
+      label: 'Customers',
+      find: 'Find a customer',
+      remote: true,
+      load: async (q) => (await flow(`/api/invoicing/contacts?${new URLSearchParams({ q, limit: '50' })}`)).contacts
+        .filter((row) => row.id !== contact.id),
+      item: (row) => ({ value: row.id, title: row.name, meta: row.email ?? null }),
+      empty: 'No customer has that name.',
+      confirm: 'Save',
+    });
+    if (picked) await save(picked.id, button);
+  };
+  const draw = () => {
+    const change = canEdit ? h('button', { class: 'fx-btn', type: 'button', title: 'Pick the customer that pays', onclick: pick }, payer ? 'Change' : 'Set') : null;
+    const clear = canEdit && payer ? h('button', {
+      class: 'fx-btn fx-btn--ghost', type: 'button', title: 'Bill this client itself',
+      onclick: (event) => save(null, event.currentTarget),
+    }, 'Clear') : null;
+    host.replaceChildren(h('section', { class: 'fx-card fx-offer' },
+      notice(payer ? `Billed to ${payer.name}.` : 'Billed to itself.', 'info', 'Bill to.'),
+      change, clear));
+  };
+  async function load() {
+    try {
+      const { billing } = await flow(`/api/invoicing/contacts/${contact.id}/billing`);
+      payer = billing.billToContactId ? (await flow(`/api/invoicing/contacts/${billing.billToContactId}`)).contact : null;
+      draw();
+    } catch (error) {
+      host.replaceChildren(notice(error.message, 'danger'));
+    }
+  }
+  await load();
 }
 
 async function loadXero(ui, contact, canEdit, host) {
@@ -231,7 +362,11 @@ async function loadXero(ui, contact, canEdit, host) {
     done: (outcome) => host.replaceChildren(h('section', { class: 'fx-card' },
       notice(outcome === 'linked' ? `${contact.name} is linked to Xero.` : `${contact.name} is in Xero.`, 'success'))),
   }) : [];
-  const text = match.state === 'matched'
+  const text = match.billTo
+    ? (match.state === 'matched'
+      ? `Billed to ${match.billTo.name}, in Xero as ${match.name}.`
+      : `Billed to ${match.billTo.name}, which is not linked to Xero. Link it on its contact page.`)
+    : match.state === 'matched'
     ? `In Xero${match.name ? ` as ${match.name}` : ''}.`
     : match.state === 'ambiguous'
       ? `More than one Xero contact is named "${contact.name}".`