@arcforgelabs/flow 2026.10.48-1 → 2026.10.49

package/server/integrations/xero/drafts.js

@@ -68,13 +68,19 @@ function xeroDate(value) {
 
 const problem = (code, message, extra = {}) => ({ code, message, ...extra });
 
+// A person can always link the Flow contact to a Xero contact of another
+// name (create-contact.js, linkCustomer): no Xero call.
 function missingContact(name, { offerCreate }) {
   const message = offerCreate
-    ? `No Xero contact is named "${name}". Create the client in Xero from this contact.`
-    : `No Xero contact is named "${name}". Add it in Xero, then sync.`;
-  return problem('xero_contact_missing', message, { short: 'Client not in Xero', ...(offerCreate ? { offerCreate: true } : {}) });
+    ? `No Xero contact is named "${name}". Link the Xero client, or create it from this contact.`
+    : `No Xero contact is named "${name}". Link the Xero client, or add it in Xero, then sync.`;
+  return problem('xero_contact_missing', message, { short: 'Client not in Xero', offerLink: true, ...(offerCreate ? { offerCreate: true } : {}) });
 }
 
+const twiceContact = (name) => problem('xero_contact_ambiguous',
+  `More than one Xero contact is named "${name}". Link the right one, or merge or rename them in Xero, then sync.`,
+  { short: 'Client twice in Xero', offerLink: true });
+
 // ---------------------------------------------------------------------------
 // The document to send
 
@@ -300,7 +306,7 @@ async function previewOne(db, runtime, organisationId, invoiceId) {
   const match = await matchContactFor(db, organisationId, { contactId: invoice.contactId, name: document.contact.name });
   const offerCreate = match.state === 'missing' && runtime.settings.createContacts && writesAllowed(runtime.settings);
   if (match.state === 'missing') problems.push(missingContact(document.contact.name, { offerCreate }));
-  if (match.state === 'ambiguous') problems.push(problem('xero_contact_ambiguous', `More than one Xero contact is named "${document.contact.name}". Merge or rename them in Xero, then sync.`, { short: 'Client twice in Xero' }));
+  if (match.state === 'ambiguous') problems.push(twiceContact(document.contact.name));
   const items = await itemsByCode(db, organisationId, document.lines.map((l) => l.itemCode));
   const sendMode = await sendModeFor(db, organisationId, invoice.contactId);
   const { draft, problems: lineProblems } = buildDraft(document, { settings: runtime.settings, contact: match.contact, items, sendMode });
@@ -399,7 +405,9 @@ export async function checkDrafts(db, runtime, { organisationId, invoiceIds }) {
     for (const preview of invoices) {
       found.set(preview.invoiceId, preview.problems
         .filter((p) => p.blocking !== false && p.code !== 'invoice_not_issued')
-        .map(({ code, message, short, offerCreate }) => ({ code, message, ...(short ? { short } : {}), ...(offerCreate ? { offerCreate: true } : {}) })));
+        .map(({ code, message, short, offerCreate, offerLink }) => ({
+          code, message, ...(short ? { short } : {}), ...(offerCreate ? { offerCreate: true } : {}), ...(offerLink ? { offerLink: true } : {}),
+        })));
     }
   }
   return found;
@@ -484,7 +492,7 @@ async function pushOne(db, runtime, client, organisationId, invoiceId, { pushedB
     throw xeroError(match.state === 'missing' ? 'xero_contact_missing' : 'xero_contact_ambiguous',
       match.state === 'missing'
         ? missingContact(document.contact.name, { offerCreate }).message
-        : `More than one Xero contact is named "${document.contact.name}". Merge or rename them in Xero, then sync.`,
+        : twiceContact(document.contact.name).message,
       { status: 409 });
   }
   const items = await itemsByCode(db, organisationId, document.lines.map((l) => l.itemCode));

package/server/integrations/xero/import.js

@@ -3,6 +3,7 @@ import { sql } from 'drizzle-orm';
 import { deadHoldSince, deadSince, enqueueJob, runNextJob } from '../../core/queue.js';
 import { isCallsStopped } from '../call-guard.js';
 import { lastSync, syncCatalogue } from './catalogue.js';
+import { syncContactsForAll } from './contact-sync.js';
 import { mirrorState } from './lookup.js';
 import { MIRROR_RESOURCES, mirrorXero } from './mirror.js';
 import { matchXero } from './links.js';
@@ -17,7 +18,8 @@ import { runWebhookWork, WEBHOOK_REFRESH_MS, webhooksActive } from './webhooks.j
 // same job is queued again for REFRESH_MS later and reads only what changed
 // since its cursor (issue #131), so the copy stays fresh (lookup.js). While
 // Xero's webhooks arrive (webhooks.js), it waits WEBHOOK_REFRESH_MS instead.
-// It only reads from Xero.
+// It only reads from Xero; the one write on its tick is a contact edit, with
+// "Two-way edits" on (contact-sync.js).
 
 export const IMPORT_KIND = 'xero.import';
 const IMPORT_KEY = 'history';
@@ -219,6 +221,8 @@ export function createImportWorker({ db, runtime, log = console, timers = { setT
     running = (async () => {
       try {
         await refreshStaleCatalogues(db, runtime, { log });
+        // Two-way contact edits, when that setting is on (contact-sync.js).
+        await syncContactsForAll(db, runtime, { log });
         await keepReadsQueued(db, runtime, { startedAtMs });
         await reportStaleCopies(db, runtime, { stale, log });
         await runWebhookWork(db, runtime, { log, holds });

package/server/integrations/xero/index.js

@@ -1,6 +1,8 @@
 import { fileURLToPath } from 'node:url';
 import { sql } from 'drizzle-orm';
+import { listReview } from '../../core/review.js';
 import { guardAlerts } from '../call-guard.js';
+import { CONTACT_DIFFERS } from './contact-sync.js';
 import { deleteXeroInvoice } from './delete-invoice.js';
 import { createCustomer } from './create-contact.js';
 import { checkDrafts, documentFacts, pushInvoice, pushInvoices } from './drafts.js';
@@ -18,7 +20,7 @@ import { readChangesFirst } from './webhooks.js';
 // XERO_MODE says which Xero it acts on. Its tables are created only while it
 // is on (docs/INTEGRATIONS.md).
 
-export const XERO_TABLES = Object.freeze(['xero_connections', 'xero_contacts', 'xero_items', 'xero_sync_runs', 'xero_invoice_pushes', 'xero_payment_cursors', 'xero_invoices', 'xero_credit_notes', 'xero_payments', 'xero_mirror_cursors', 'xero_call_guard', 'xero_calls', 'xero_webhook_events', 'xero_daily_checks', 'xero_invoice_links', 'xero_import_settings']);
+export const XERO_TABLES = Object.freeze(['xero_connections', 'xero_contacts', 'xero_items', 'xero_sync_runs', 'xero_invoice_pushes', 'xero_payment_cursors', 'xero_invoices', 'xero_credit_notes', 'xero_payments', 'xero_mirror_cursors', 'xero_call_guard', 'xero_calls', 'xero_webhook_events', 'xero_daily_checks', 'xero_invoice_links', 'xero_import_settings', 'xero_contact_sync']);
 
 // What an owner enters in Settings, Integrations (server/integrations/setup.js).
 // The refresh token's key comes from Flow's secrets key.
@@ -113,7 +115,18 @@ export function createXeroAdapter({ runtime: given = null } = {}) {
       async alerts({ organisationId }) {
         const connection = await readConnection(database, organisationId);
         if (!connection || connection.mode !== current().settings.mode) return [];
-        return guardAlerts('Xero', await current().guardFor(database).status(connection.tenantId));
+        const alerts = guardAlerts('Xero', await current().guardFor(database).status(connection.tenantId));
+        // Contacts both sides changed (Two-way edits, contact-sync.js).
+        const differ = await listReview(database, organisationId, { kind: CONTACT_DIFFERS, limit: 500 });
+        if (differ.length) {
+          alerts.push({
+            id: 'contacts-differ',
+            tone: 'warn',
+            title: `${differ.length === 1 ? '1 contact differs' : `${differ.length} contacts differ`} in Flow and Xero. Open the contact, then make both sides the same.`,
+            members: differ.map((item) => `${item.flowId}:${JSON.stringify(item.evidence?.fields?.map((f) => f.field) ?? [])}`),
+          });
+        }
+        return alerts;
       },
       // One issued invoice to a Xero draft (drafts.js). The Flow invoice id
       // and version are the idempotency key.

package/server/integrations/xero/lookup.js

@@ -14,12 +14,25 @@ export const MIRROR_FRESH_MS = 24 * 60 * 60 * 1000;
 // and must still match jobs.
 export const PROOF_RESOURCES = Object.freeze(['invoices', 'credit_notes']);
 
+// `contact` is the Flow contact a new client becomes (docs/CONTACTS.md,
+// "Add Xero clients"). A contact Xero marks a supplier only still links by
+// name, but never becomes a Flow customer (`adoptable` false).
 export async function listCustomers(db, organisationId) {
   const { rows } = await db.execute(sql`
-    select xero_contact_id, name, status from xero_contacts
+    select xero_contact_id, name, first_name, last_name, email, phone, mobile, account_number, tax_number, address,
+      is_customer, is_supplier
+    from xero_contacts
     where organisation_id = ${organisationId} and status = 'ACTIVE'
     order by name`);
-  return rows.map((r) => ({ id: r.xero_contact_id, name: r.name }));
+  return rows.map((r) => ({
+    id: r.xero_contact_id,
+    name: r.name,
+    adoptable: Boolean(r.is_customer || !r.is_supplier),
+    contact: {
+      kind: 'customer', name: r.name, firstName: r.first_name, lastName: r.last_name, email: r.email, phone: r.phone,
+      mobile: r.mobile, accountNumber: r.account_number, taxNumber: r.tax_number, address: r.address,
+    },
+  }));
 }
 
 // Xero's items, from Flow's copy (catalogue.js, read on each sync), for the

package/server/integrations/xero/migrations/0013_xero_contact_sync.sql

@@ -0,0 +1,15 @@
+-- Two-way contact edits (docs/CONTACTS.md, xero/contact-sync.js). One row for
+-- each linked pair: the fields both sides last agreed on (the merge base), so
+-- Flow can tell which side changed a field. `clashes` lists the fields both
+-- sides changed; they wait for a person. The Xero adapter's own table.
+CREATE TABLE IF NOT EXISTS "xero_contact_sync" (
+	"organisation_id" uuid NOT NULL REFERENCES "organisations"("id"),
+	"xero_contact_id" text NOT NULL,
+	"contact_id" uuid NOT NULL,
+	"base" jsonb NOT NULL,
+	"clashes" jsonb DEFAULT '[]'::jsonb NOT NULL,
+	"last_error" text,
+	"checked_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"pushed_at" timestamp with time zone,
+	CONSTRAINT "xero_contact_sync_pk" PRIMARY KEY("organisation_id", "xero_contact_id")
+);

package/server/integrations/xero/migrations/meta/_journal.json

@@ -92,6 +92,13 @@
       "when": 1792550000000,
       "tag": "0012_xero_contact_details",
       "breakpoints": true
+    },
+    {
+      "idx": 13,
+      "version": "7",
+      "when": 1792560000000,
+      "tag": "0013_xero_contact_sync",
+      "breakpoints": true
     }
   ]
 }

package/server/integrations/xero/routes.js

@@ -4,7 +4,7 @@ import { FlowError } from '../../core/errors.js';
 import { createActionGuard } from '../call-guard.js';
 import { billingObligations, organisations } from '../../db/schema.js';
 import { lastSync, listContacts, listItems, syncCatalogue } from './catalogue.js';
-import { createCustomer, matchCustomer } from './create-contact.js';
+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';
@@ -31,6 +31,8 @@ import { messagePage as themedMessagePage } from '../../ui/page.js';
 //   GET  /contacts/match?organisationId=&contactId=   any signed-in person:
 //                                  whether this Flow contact is in the copy
 //   POST /contacts                 owner or admin: create the Xero contact
+//   POST /contacts/link            owner or admin: link a Flow contact to a
+//                                  Xero contact of another name (no Xero call)
 //   GET  /items?organisationId=    any signed-in person: the copy
 //   POST /invoices/preview         any signed-in person: the Xero drafts Flow
 //                                  would make, and what stops them (no Xero calls)
@@ -274,7 +276,8 @@ export function createXeroRouter({ db, personAuth, runtime, log = console, butto
 
   router.get('/contacts', ...signedIn, handle(log, async (req, res) => {
     const organisationId = await requireOrganisation(db, req.query.organisationId);
-    res.json({ ok: true, contacts: await listContacts(db, organisationId, { q: typeof req.query.q === 'string' ? req.query.q : '' }) });
+    const limit = Number(req.query.limit) || undefined;
+    res.json({ ok: true, contacts: await listContacts(db, organisationId, { q: typeof req.query.q === 'string' ? req.query.q : '', limit }) });
   }));
 
   // Whether this Flow contact is a Xero contact, and whether Create is offered.
@@ -293,6 +296,17 @@ export function createXeroRouter({ db, personAuth, runtime, log = console, butto
     res.status(result.outcome === 'created' ? 201 : 200).json({ ok: true, ...result });
   }));
 
+  // A person links a Flow contact to a Xero contact of another name. Flow's
+  // identity map only: no Xero call.
+  router.post('/contacts/link', ...manager, handle(log, async (req, res) => {
+    const organisationId = await requireOrganisation(db, req.body?.organisationId);
+    if (typeof req.body?.contactId !== 'string' || !UUID.test(req.body.contactId)) throw new FlowError('invalid', 'contactId must be a Flow contact id');
+    if (typeof req.body?.xeroContactId !== 'string' || !req.body.xeroContactId.trim()) throw new FlowError('invalid', 'xeroContactId must be a Xero contact id');
+    const result = await linkCustomer(db, runtime, { organisationId, contactId: req.body.contactId, xeroContactId: req.body.xeroContactId.trim() });
+    log.info?.(`[xero] organisation ${organisationId}: person ${req.person.id} linked Xero contact ${result.xeroContactId} to Flow contact ${req.body.contactId}`);
+    res.json({ ok: true, ...result });
+  }));
+
   router.get('/items', ...signedIn, handle(log, async (req, res) => {
     const organisationId = await requireOrganisation(db, req.query.organisationId);
     res.json({ ok: true, items: await listItems(db, organisationId) });

package/server/ui/app.js

@@ -25,7 +25,7 @@ import { isSearchKey, openSearch } from '/assets/ui/search.js';
 import { alertStrip } from '/assets/ui/alerts.js';
 import { initialsOf, personLabel } from '/assets/ui/person.js';
 import { startTips } from '/assets/ui/tip.js';
-import { crumbs, dialog, edgeFade, fieldError, h, holdButton, linksOpenWith, listFrame, listHead, notice, pageHeader, rowMenu, sectionTitle, settingRow, tileCard, tileSection, toast } from '/assets/ui/kit.js';
+import { crumbs, dialog, edgeFade, fieldError, h, holdButton, linksOpenWith, listFrame, listHead, notice, pageHeader, pickOne, rowMenu, sectionTitle, settingRow, tileCard, tileSection, toast } from '/assets/ui/kit.js';
 import { NAV_DEFAULT, NAV_LOCKED } from '/assets/ui/nav-pins.js';
 
 const $ = (id) => document.getElementById(id);
@@ -332,7 +332,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, fieldError, pageHeader, listHead, listFrame, edgeFade, sectionTitle, dialog, me, holdButton, tileCard, tileSection, crumbs,
+  h, flow, toast, notice, fieldError, pageHeader, listHead, listFrame, edgeFade, sectionTitle, settingRow, dialog, pickOne, me, holdButton, tileCard, tileSection, crumbs,
   go: (target, options) => (typeof target === 'string' ? go(target, options) : navigate(target)),
 });
 
@@ -622,6 +622,11 @@ const CATALOGUE = {
 const CATEGORIES = [['all', 'All'], ['accounting', 'Accounting'], ['lab', 'Lab software'], ['monitoring', 'Monitoring']];
 const CATEGORY_LABEL = Object.fromEntries(CATEGORIES);
 
+// The two notices every integration page can show, each one short line. The
+// detail is on the ? (docs/INTEGRATIONS.md has the rest).
+const readOnlyNotice = () => notice('Verified owner sign-in needed.', 'warn', 'Read only.');
+const secretsKeyNotice = () => notice('Set FLOW_SECRETS_KEY, then restart Flow.', 'warn', 'No secrets key.');
+
 function integrationLogo(integration, size = '') {
   const file = CATALOGUE[integration.id]?.logo;
   return h('span', { class: `fx-logo${size ? ` fx-logo--${size}` : ''}`, 'aria-hidden': 'true' },
@@ -631,7 +636,7 @@ function integrationLogo(integration, size = '') {
 async function renderIntegrations(main) {
   const state = { tab: 'all', category: 'all', q: '' };
   const tabs = h('div', { class: 'fx-seg', role: 'tablist' });
-  const search = h('input', { class: 'fx-input fx-search', type: 'search', placeholder: 'Search integrations', 'aria-label': 'Search integrations' });
+  const search = h('input', { class: 'fx-input fx-search', type: 'search', placeholder: 'Search', 'aria-label': 'Search integrations' });
   const category = h('select', { class: 'fx-select', 'aria-label': 'Category' },
     CATEGORIES.map(([id, label]) => h('option', { value: id }, id === 'all' ? 'All categories' : label)));
   const notices = h('div', { class: 'fx-fields' });
@@ -650,8 +655,8 @@ async function renderIntegrations(main) {
   }
   const canChange = Boolean(me.ownerActions?.allowed);
   notices.replaceChildren(...[
-    canChange ? null : notice('Changing integrations needs a verified owner sign-in: Google Workspace on the owner domain with no password, or a second factor.', 'warn', 'Read only.'),
-    body.secretsKey ? null : notice('Flow cannot store a client secret. Set FLOW_SECRETS_KEY (64 hex characters), then restart Flow.', 'warn', 'No secrets key.'),
+    canChange ? null : readOnlyNotice(),
+    body.secretsKey ? null : secretsKeyNotice(),
   ].filter(Boolean));
   const list = [...body.integrations].sort((a, b) => a.name.localeCompare(b.name));
   const connected = (i) => i.enabled;
@@ -706,8 +711,8 @@ function integrationTile(integration) {
 }
 
 
-// One integration's page (/integrations/<id>): its logo and maker, Connect
-// with each step shown as it happens, the setup steps, its settings, and the
+// One integration's page (/integrations/<id>): its logo, name and Connect
+// (each step shown as it runs), the setup steps (closed), its settings, and the
 // facts beside them.
 async function renderIntegration(main, id) {
   const host = h('div', { class: 'fx-int-page' }, h('div', { class: 'fx-skeleton' }));
@@ -733,6 +738,9 @@ async function renderIntegration(main, id) {
     ? h('span', { class: 'fx-status', 'data-tone': 'danger', 'data-int-status': '' }, 'Calls stopped')
     : h('span', { class: 'fx-status', 'data-tone': STATE_TONE[current.state] ?? 'mute', 'data-int-status': '' }, STATE_LABEL[current.state] ?? current.state));
   let shown = found;
+  // Settings: closed on a phone, open on a wider screen, then as the person
+  // leaves it while the page redraws (Connect).
+  let settingsOpen = !window.matchMedia?.('(max-width: 639px)').matches;
   const alerts = alertStrip(ui(), 'integrations', {
     scope: id,
     onLoad: ({ danger }) => {
@@ -750,7 +758,7 @@ async function renderIntegration(main, id) {
         // The host sets it: a value to read, not a box to type in.
         rows.push(settingRow({
           label: field.label,
-          hint: 'Set by whoever hosts Flow.',
+          help: 'Set by whoever hosts Flow.',
           control: field.secret ? h('span', { class: 'fx-dim' }, 'Set') : h('code', { class: 'fx-setting__value' }, field.value),
         }));
         continue;
@@ -772,10 +780,11 @@ async function renderIntegration(main, id) {
       const suggestion = field.suggest === 'callback' ? `${location.origin}/api/${current.id}/oauth/callback` : null;
       rows.push(settingRow({
         label: field.label,
-        hint: field.unreadable ? 'Stored with another key. Enter it again.' : field.help,
+        hint: field.unreadable ? 'Stored with another key. Enter it again.' : null,
+        help: field.help,
         control: suggestion && !disabled
           ? h('div', { class: 'fx-setting__stack' }, input,
-            h('button', { class: 'fx-btn fx-btn--ghost fx-btn--sm', type: 'button', title: suggestion, onclick: () => { input.value = suggestion; navigator.clipboard?.writeText(suggestion); toast('Address filled in and copied.', 'success'); } }, 'Use this installation\'s address'))
+            h('button', { class: 'fx-btn fx-btn--ghost fx-btn--sm', type: 'button', title: suggestion, onclick: () => { input.value = suggestion; navigator.clipboard?.writeText(suggestion); toast('Address filled in and copied.', 'success'); } }, 'Use this address'))
           : input,
       }));
     }
@@ -831,7 +840,6 @@ async function renderIntegration(main, id) {
     const on = current.enabled;
     const guide = current.guide;
     const hostOwned = current.enabledBy === 'host';
-    const entry = CATALOGUE[current.id];
     const mode = current.fields.find((f) => /_MODE$/.test(f.name));
     const modeLabel = mode?.choices?.find((c) => c.value === mode.value)?.label ?? mode?.value;
     const busy = progress && progress.steps.some((step) => step.state === 'running');
@@ -843,44 +851,41 @@ async function renderIntegration(main, id) {
 
     host.replaceChildren(
       crumbs(['/integrations', 'Integrations'], current.name),
-      h('header', { class: 'fx-int-hero' },
-        integrationLogo(current, 'xl'),
-        h('div', { class: 'fx-int-hero__text' },
-          h('h1', { class: 'fx-title' }, current.name),
-          h('p', { class: 'fx-int-hero__maker' }, entry?.maker ?? current.name, h('span', { class: 'fx-dim' }, CATEGORY_LABEL[entry?.category] ?? 'Integration')),
-          h('p', { class: 'fx-int-hero__blurb' }, entry?.blurb ?? ''),
-          h('div', { class: 'fx-int-hero__actions' },
-            primary,
-            on ? statusPill(current) : null,
-            progress ? connectProgress(progress) : null))),
       h('div', { class: 'fx-int-page__grid' },
         h('div', { class: 'fx-int-page__main' }, ...[
+          h('header', { class: 'fx-int-hero' },
+            integrationLogo(current, 'lg'),
+            h('h1', { class: 'fx-title' }, current.name),
+            h('div', { class: 'fx-int-hero__actions' },
+              on ? statusPill(current) : null,
+              primary,
+              progress ? connectProgress(progress) : null)),
           alerts.element,
-          !canChange ? notice('Changing integrations needs a verified owner sign-in: Google Workspace on the owner domain with no password, or a second factor.', 'warn', 'Read only.') : null,
-          !body.secretsKey ? notice('Flow cannot store a client secret. Set FLOW_SECRETS_KEY (64 hex characters), then restart Flow.', 'warn', 'No secrets key.') : null,
+          !canChange ? readOnlyNotice() : null,
+          !body.secretsKey ? secretsKeyNotice() : null,
           current.state === 'failed' && current.error ? notice(current.error, 'danger', 'It could not start.') : null,
           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' } }, automationSection(ui(), 'xero', 'Contacts')) : 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'),
+          guide ? h('details', { class: 'fx-int-section fx-int-fold' },
+            h('summary', { class: 'fx-int-section__title' }, 'Set up'),
             h('ol', { class: 'fx-steps' }, guide.steps.map((step) => h('li', {}, step))),
-            guide.link ? h('a', { class: 'fx-btn fx-btn--sm', href: guide.link, target: '_blank', rel: 'noopener' }, `Open ${current.name} developer site ↗`) : null) : null,
-          rows.length ? h('section', { class: 'fx-int-section' },
-            h('h2', { class: 'fx-int-section__title' }, 'Settings'),
+            guide.link ? h('a', { class: 'fx-btn fx-btn--sm', href: guide.link, target: '_blank', rel: 'noopener' }, `${current.name} site ↗`) : null) : null,
+          rows.length ? h('details', { class: 'fx-int-section fx-int-fold', open: settingsOpen, ontoggle: (event) => { settingsOpen = event.currentTarget.open; } },
+            h('summary', { class: 'fx-int-section__title' }, 'Settings'),
             h('div', { class: 'fx-settings' }, rows),
             canChange && on && inputs.size ? h('div', { class: 'fx-row fx-row--end' }, h('button', { class: 'fx-btn', type: 'button', onclick: () => save(undefined) }, 'Save changes')) : null) : null,
         ].filter(Boolean)),
         h('aside', { class: 'fx-int-page__meta' },
           h('dl', { class: 'fx-meta' }, ...[
             ['Status', statusPill(current)],
-            ['Category', h('span', { class: 'fx-chip fx-chip--static' }, CATEGORY_LABEL[entry?.category] ?? 'Integration')],
             modeLabel ? ['Mode', modeLabel] : null,
-            ['Turned on by', current.enabledBy === 'host' ? 'The host' : current.enabledBy === 'flow' ? 'An owner, here' : '—'],
-            current.updatedAt ? ['Last changed', new Date(current.updatedAt).toLocaleString('en-AU', { dateStyle: 'medium', timeStyle: 'short' })] : null,
-            guide?.link ? ['Documentation', h('a', { href: guide.link, target: '_blank', rel: 'noopener' }, 'Developer site ↗')] : null,
+            current.enabledBy === 'host' ? ['On by', 'Host'] : current.enabledBy === 'flow' ? ['On by', 'Owner'] : null,
+            current.updatedAt ? ['Changed', new Date(current.updatedAt).toLocaleString('en-AU', { dateStyle: 'medium', timeStyle: 'short' })] : null,
+            guide?.link ? ['Docs', h('a', { href: guide.link, target: '_blank', rel: 'noopener' }, `${current.name} ↗`)] : null,
           ].filter(Boolean).map(([label, value]) => h('div', {}, h('dt', {}, label), h('dd', {}, value)))))));
   };
   document.title = `${found.name} · Flow`;
@@ -910,7 +915,7 @@ function personSettingsSection(integration) {
         }
         input.disabled = false;
       });
-      return settingRow({ label: setting.label, hint: setting.hint, control: input });
+      return settingRow({ label: setting.label, help: setting.hint, control: input });
     });
     section.replaceChildren(section.firstChild, h('div', { class: 'fx-settings' }, rows));
   }).catch(() => section.remove());
@@ -933,7 +938,7 @@ 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 copied = h('span', {}, '');
   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 () => {
@@ -954,16 +959,16 @@ function xeroImportSection(organisations) {
   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.',
+    settingRow({ label: 'To check', help: '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') }));
+    settingRow({ label: 'Link sure matches', help: 'Same client, total and week, and only one fit. Flow links them.', control: autoLink }),
+    settingRow({ label: 'Make Flow invoices for the rest', help: 'Off: they stay in the Xero history.', control: makeUnmatched }),
+    settingRow({ label: 'Xero history', hint: copied, help: 'Every Xero invoice Flow copied. A search makes no Xero call.', 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.`);
+        copied.replaceChildren(`${Object.values(c).reduce((a, b) => a + b, 0)} copied, ${c.linked} in Flow`);
         autoLink.setAttribute('aria-checked', String(settings.autoLink));
         makeUnmatched.setAttribute('aria-checked', String(settings.makeUnmatched));
         autoLink.disabled = makeUnmatched.disabled = !canAct;

package/server/ui/automations.js

@@ -9,7 +9,7 @@ const DOCS = 'https://github.com/arcforgelabs/flow/blob/main/docs/AUTOMATIONS.md
 
 // A section of the automations kept at `place`, filled when they load.
 export function automationSection(ui, place, title) {
-  const { h, flow, toast, notice, me } = ui;
+  const { h, flow, toast, notice, me, settingRow } = ui;
   const section = h('section', { class: 'fx-set' }, h('h2', { class: 'fx-set__title' }, title), h('div', { class: 'fx-skeleton' }));
   const disabled = !['owner', 'admin'].includes(me?.person.role);
 
@@ -27,9 +27,7 @@ export function automationSection(ui, place, title) {
     }
   }
 
-  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));
+  const row = (label, help, control) => settingRow({ label, help, control });
 
   // A menu of the statuses the work system reported, each with its job count.
   // A status saved earlier stays in the menu even when no job has it now.

package/server/ui/contacts.js

@@ -1,8 +1,9 @@
 // Contacts (/contacts, /contacts/<id>). Flow's own customers and suppliers
 // (server/core/contacts.js, docs/CONTACTS.md). The list and the record work
 // with no integration on. When Xero is connected, the record says whether
-// that contact is in Xero and, for an owner or admin, offers Create.
+// that contact is in Xero and, for an owner or admin, offers Link and Create.
 import { initialsOf } from '/assets/ui/person.js';
+import { xeroContactActions } from '/assets/ui/xero-contact.js';
 
 const DOCS = 'https://github.com/arcforgelabs/flow/blob/main/docs/CONTACTS.md';
 const KINDS = [['customer', 'Customer'], ['supplier', 'Supplier']];
@@ -225,36 +226,28 @@ async function loadXero(ui, contact, canEdit, host) {
     return;
   }
   if (match.state === 'off') return;
-  const create = match.offerCreate && canEdit
-    ? h('button', {
-      class: 'fx-btn fx-btn--primary', type: 'button', title: 'Create this client in Xero',
-      onclick: async (event) => {
-        const button = event.currentTarget;
-        const confirmed = await ui.dialog({
-          title: `Create ${contact.name} in Xero?`,
-          body: h('p', {}, 'Flow adds this client to Xero from the contact.'),
-          confirm: 'Create',
-        });
-        if (!confirmed) return;
-        button.disabled = true;
-        try {
-          await flow('/api/xero/contacts', { method: 'POST', body: JSON.stringify({ organisationId, contactId: contact.id }) });
-          toast(`${contact.name} is in Xero.`, 'success');
-          host.replaceChildren(h('section', { class: 'fx-card' }, notice(`${contact.name} is in Xero.`, 'success')));
-        } catch (error) {
-          toast(error.message, error.status === 429 ? 'info' : 'danger');
-          if (error.retryAfterMs) ui.holdButton(button, error.retryAfterMs);
-          else button.disabled = false;
-        }
-      },
-    }, 'Create')
-    : null;
+  const actions = canEdit ? xeroContactActions(ui, {
+    organisationId, contact, offerLink: match.offerLink, offerCreate: match.offerCreate,
+    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'
     ? `In Xero${match.name ? ` as ${match.name}` : ''}.`
     : match.state === 'ambiguous'
       ? `More than one Xero contact is named "${contact.name}".`
       : `No Xero contact is named "${contact.name}".`;
+  // Fields both sides changed (Two-way edits): alert only. A person makes the
+  // two the same, here or in Xero, and the next check clears it.
+  const differs = match.differs ?? [];
+  const clash = differs.length
+    ? notice(`Changed in both: ${differs.map((d) => FIELD_LABELS[d.field] ?? d.field).join(', ')}. Make Flow and Xero the same.`, 'warn', 'Xero differs.')
+    : null;
   host.replaceChildren(h('section', { class: 'fx-card fx-offer' },
-    notice(text, match.state === 'matched' ? 'success' : 'danger', match.state === 'matched' ? 'Xero.' : 'Xero.'),
-    create));
+    clash ?? notice(text, match.state === 'matched' ? 'success' : 'danger', match.state === 'matched' ? 'Xero.' : 'Xero.'),
+    ...actions));
 }
+
+const FIELD_LABELS = {
+  name: 'Name', firstName: 'First name', lastName: 'Last name', email: 'Email', phone: 'Phone',
+  mobile: 'Mobile', accountNumber: 'Account', taxNumber: 'Tax number', address: 'Address',
+};