@arcforgelabs/flow 2026.10.48 → 2026.10.49

package/server/integrations/xero/contact-sync.js

@@ -0,0 +1,289 @@
+import { createHash } from 'node:crypto';
+import { sql } from 'drizzle-orm';
+import { listAutomations } from '../../core/automations.js';
+import { getContact, updateContact } from '../../core/contacts.js';
+import { FlowError } from '../../core/errors.js';
+import { openReview, resolveReviewFor } from '../../core/review.js';
+import { isCallsStopped } from '../call-guard.js';
+import { mapContact, upsertContact } from './catalogue.js';
+import { readConnection } from './connections.js';
+import { withXeroLane } from './governor.js';
+import { writesAllowed } from './settings.js';
+
+// Two-way contact edits (docs/CONTACTS.md), when "Two-way edits"
+// (sync_contact_edits) is on. For each Flow contact linked to a Xero contact,
+// Flow compares three versions of each field: Flow's, Flow's copy of Xero
+// (catalogue.js), and the base, the value both sides last agreed on
+// (xero_contact_sync). The side that changed a field since the base wins:
+//
+//   only Flow changed it   Flow writes it to Xero (read the live contact first)
+//   only Xero changed it   Flow takes it from the copy (no Xero call)
+//   both changed it        a clash: neither side changes. A review item says
+//                          which fields differ, alert only; it closes when a
+//                          person makes the two sides the same.
+//
+// The first time a pair is compared there is no base: a field blank on one
+// side takes the other side's value, and a field set on both sides to
+// different values is a clash. Practitioners, the tax rate and Active stay
+// Flow's own. Writes to Xero follow XERO_ALLOW_LIVE_WRITES; while they are
+// not allowed, a Flow change waits and Xero's changes still come in.
+
+export const CONTACT_FIELDS = Object.freeze(['name', 'firstName', 'lastName', 'email', 'phone', 'mobile', 'accountNumber', 'taxNumber', 'address']);
+export const CONTACT_DIFFERS = 'contact.accounting_differs';
+export const ACTOR = 'system:xero-contacts';
+const AUTOMATION = 'sync_contact_edits';
+const ADDRESS_KEYS = ['line1', 'line2', 'city', 'region', 'postalCode', 'country'];
+// Xero writes in one pass, so a long list of edits spreads over passes.
+const PUSHES_PER_PASS = 20;
+
+// One field's value in the form both sides compare: text trimmed or null, an
+// address with its keys in order or null.
+export function fieldValue(field, value) {
+  if (field === 'address') {
+    if (!value || typeof value !== 'object') return null;
+    const kept = {};
+    for (const key of ADDRESS_KEYS) {
+      const text = String(value[key] ?? '').trim();
+      if (text) kept[key] = text;
+    }
+    return Object.keys(kept).length ? kept : null;
+  }
+  const text = String(value ?? '').trim();
+  return text || null;
+}
+
+export const fieldsOf = (record) => Object.fromEntries(CONTACT_FIELDS.map((field) => [field, fieldValue(field, record?.[field])]));
+const same = (a, b) => JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
+
+// What to change on each side, from the three versions. `base` null is the
+// first compare of a pair.
+export function planContactSync(flow, xero, base) {
+  const toFlow = {};
+  const toXero = {};
+  const clashes = [];
+  const next = {};
+  for (const field of CONTACT_FIELDS) {
+    const mine = flow[field];
+    const theirs = xero[field];
+    if (same(mine, theirs)) {
+      next[field] = mine;
+      continue;
+    }
+    const was = base ? base[field] ?? null : null;
+    const flowChanged = base ? !same(mine, was) : mine !== null;
+    const xeroChanged = base ? !same(theirs, was) : theirs !== null;
+    if (flowChanged && !xeroChanged) {
+      toXero[field] = mine;
+      next[field] = mine;
+    } else if (xeroChanged && !flowChanged) {
+      toFlow[field] = theirs;
+      next[field] = theirs;
+    } else {
+      clashes.push({ field, flow: mine, xero: theirs });
+      next[field] = was;
+    }
+  }
+  return { toFlow, toXero, clashes, base: next };
+}
+
+// The Xero body for the fields Flow changed. A blank clears the field.
+export function xeroContactChanges(changes) {
+  const body = {};
+  const simple = { name: 'Name', firstName: 'FirstName', lastName: 'LastName', email: 'EmailAddress', accountNumber: 'AccountNumber', taxNumber: 'TaxNumber' };
+  for (const [field, key] of Object.entries(simple)) {
+    if (field in changes) body[key] = changes[field] ?? '';
+  }
+  const phones = [];
+  for (const [field, type] of [['phone', 'DEFAULT'], ['mobile', 'MOBILE']]) {
+    if (field in changes) phones.push({ PhoneType: type, PhoneNumber: changes[field] ?? '', PhoneAreaCode: '', PhoneCountryCode: '' });
+  }
+  if (phones.length) body.Phones = phones;
+  if ('address' in changes) {
+    const address = changes.address ?? {};
+    const lines = {
+      AddressLine1: address.line1 || '', AddressLine2: address.line2 || '', City: address.city || '',
+      Region: address.region || '', PostalCode: address.postalCode || '', Country: address.country || '',
+    };
+    body.Addresses = [{ AddressType: 'POBOX', ...lines }, { AddressType: 'STREET', ...lines }];
+  }
+  return body;
+}
+
+function idempotencyKey(organisationId, xeroContactId, body) {
+  const digest = createHash('sha256').update([organisationId, xeroContactId, JSON.stringify(body)].join('\u0000')).digest('hex');
+  return `flow-xero-contact-edit-${digest.slice(0, 40)}`;
+}
+
+// Each Flow contact linked to an active Xero contact in the copy, with the
+// pair's base when there is one.
+async function linkedPairs(db, organisationId) {
+  const { rows } = await db.execute(sql`
+    select l.flow_id, x.*, s.contact_id as base_contact_id, s.base, s.clashes as saved_clashes
+    from external_links l
+    join xero_contacts x on x.organisation_id = l.organisation_id and x.xero_contact_id = l.external_id
+    join contacts c on c.organisation_id = l.organisation_id and c.id = l.flow_id
+    left join xero_contact_sync s on s.organisation_id = l.organisation_id and s.xero_contact_id = l.external_id
+    where l.organisation_id = ${organisationId} and l.system = 'xero' and l.entity = 'contact' and l.state = 'active'
+      and x.status = 'ACTIVE'
+    order by x.name`);
+  return rows;
+}
+
+const copyFields = (row) => fieldsOf({
+  name: row.name, firstName: row.first_name, lastName: row.last_name, email: row.email, phone: row.phone,
+  mobile: row.mobile, accountNumber: row.account_number, taxNumber: row.tax_number, address: row.address,
+});
+
+async function saveBase(db, organisationId, { xeroContactId, contactId, base, clashes, error = null, pushed = false }) {
+  await db.execute(sql`insert into xero_contact_sync (organisation_id, xero_contact_id, contact_id, base, clashes, last_error, checked_at, pushed_at)
+    values (${organisationId}, ${xeroContactId}, ${contactId}, ${JSON.stringify(base)}::jsonb, ${JSON.stringify(clashes)}::jsonb, ${error}, now(),
+      case when ${pushed} then now() else null end)
+    on conflict (organisation_id, xero_contact_id) do update set
+      contact_id = excluded.contact_id, base = excluded.base, clashes = excluded.clashes, last_error = excluded.last_error,
+      checked_at = now(), pushed_at = case when ${pushed} then now() else xero_contact_sync.pushed_at end`);
+}
+
+// Takes Xero's values into the Flow contact. A value Flow cannot keep (too
+// long for the field) stays a clash.
+async function takeFromXero(db, organisationId, contactId, changes) {
+  const taken = {};
+  const refused = [];
+  const attempt = async (patch) => {
+    await updateContact(db, organisationId, contactId, patch);
+    Object.assign(taken, patch);
+  };
+  try {
+    await attempt(changes);
+  } catch (error) {
+    if (!(error instanceof FlowError)) throw error;
+    for (const [field, value] of Object.entries(changes)) {
+      try {
+        await attempt({ [field]: value });
+      } catch (inner) {
+        if (!(inner instanceof FlowError)) throw inner;
+        refused.push(field);
+      }
+    }
+  }
+  return { taken, refused };
+}
+
+// Writes Flow's changed fields to one Xero contact. Reads the live contact
+// first: when Xero changed one of those fields since the copy, the copy takes
+// it and nothing is written; the next pass compares again.
+async function pushToXero(db, runtime, organisationId, xeroContactId, changes, copy) {
+  return runtime.serial(organisationId, () => withXeroLane('writes', async () => {
+    const { client } = await runtime.clientFor(db, organisationId);
+    await runtime.assertEnvironment(client);
+    const live = await client.getContact(xeroContactId);
+    if (!live) return { outcome: 'gone' };
+    const now = fieldsOf(mapContact(live));
+    if (Object.keys(changes).some((field) => !same(now[field], copy[field]))) {
+      await upsertContact(db, organisationId, mapContact(live));
+      return { outcome: 'moved' };
+    }
+    const body = xeroContactChanges(changes);
+    const updated = await client.updateContact(xeroContactId, body, { idempotencyKey: idempotencyKey(organisationId, xeroContactId, body) });
+    await upsertContact(db, organisationId, mapContact(updated));
+    return { outcome: 'written' };
+  }));
+}
+
+async function noteClashes(db, organisationId, contactId, xeroContactId, clashes) {
+  if (clashes.length) {
+    await openReview(db, organisationId, {
+      kind: CONTACT_DIFFERS, entity: 'contact', flowId: contactId, systems: ['flow', 'xero'],
+      evidence: { xeroContactId, fields: clashes },
+    });
+  } else {
+    await resolveReviewFor(db, organisationId, { kind: CONTACT_DIFFERS, entity: 'contact', flowId: contactId, resolution: 'contacts_agree', actor: ACTOR });
+  }
+}
+
+// One pass for one organisation. Answers counts.
+export async function syncContactEdits(db, runtime, organisationId) {
+  const result = { compared: 0, toFlow: 0, toXero: 0, waiting: 0, clashes: 0, errors: 0 };
+  const canWrite = writesAllowed(runtime.settings);
+  let pushes = 0;
+  for (const row of await linkedPairs(db, organisationId)) {
+    result.compared += 1;
+    const contactId = row.flow_id;
+    const xeroContactId = row.xero_contact_id;
+    // A base belongs to one pair: a link to another Flow contact starts again.
+    const base = row.base && row.base_contact_id === contactId ? row.base : null;
+    const copy = copyFields(row);
+    const flow = fieldsOf(await getContact(db, organisationId, contactId));
+    const plan = planContactSync(flow, copy, base);
+    if (Object.keys(plan.toFlow).length) {
+      const { taken, refused } = await takeFromXero(db, organisationId, contactId, plan.toFlow);
+      if (Object.keys(taken).length) result.toFlow += 1;
+      for (const field of refused) {
+        plan.clashes.push({ field, flow: flow[field], xero: copy[field] });
+        plan.base[field] = base?.[field] ?? null;
+      }
+    }
+    let error = null;
+    let pushed = false;
+    if (Object.keys(plan.toXero).length) {
+      if (!canWrite || pushes >= PUSHES_PER_PASS) {
+        // Not written yet: the base keeps the old value, so the change stays Flow's.
+        for (const field of Object.keys(plan.toXero)) plan.base[field] = base?.[field] ?? copy[field];
+        result.waiting += 1;
+      } else {
+        pushes += 1;
+        try {
+          const sent = await pushToXero(db, runtime, organisationId, xeroContactId, plan.toXero, copy);
+          if (sent.outcome === 'written') {
+            pushed = true;
+            result.toXero += 1;
+          } else {
+            for (const field of Object.keys(plan.toXero)) plan.base[field] = base?.[field] ?? copy[field];
+            result.waiting += 1;
+          }
+        } catch (failure) {
+          // A stop (budget, a refused token) ends the pass; it is not this contact's fault.
+          if (isCallsStopped(failure)) throw failure;
+          error = `${failure.code ?? 'error'}: ${String(failure.message).slice(0, 300)}`;
+          for (const field of Object.keys(plan.toXero)) {
+            plan.clashes.push({ field, flow: flow[field], xero: copy[field], error: failure.message });
+            plan.base[field] = base?.[field] ?? copy[field];
+          }
+          result.errors += 1;
+        }
+      }
+    }
+    if (plan.clashes.length) result.clashes += 1;
+    await saveBase(db, organisationId, { xeroContactId, contactId, base: plan.base, clashes: plan.clashes, error, pushed });
+    await noteClashes(db, organisationId, contactId, xeroContactId, plan.clashes);
+  }
+  return result;
+}
+
+// The fields of one Flow contact that differ from Xero and wait for a person
+// (the contact page). No Xero calls.
+export async function contactClashes(db, organisationId, contactId) {
+  const { rows } = await db.execute(sql`select clashes from xero_contact_sync
+    where organisation_id = ${organisationId} and contact_id = ${contactId}`);
+  return rows.flatMap((row) => row.clashes ?? []);
+}
+
+// Every connected organisation whose "Two-way edits" is on. The import worker
+// runs this on its tick. A stop of Xero calls skips that organisation.
+export async function syncContactsForAll(db, runtime, { log = console } = {}) {
+  const { rows } = await db.execute(sql`select organisation_id from xero_connections where mode = ${runtime.settings.mode}`);
+  for (const { organisation_id: organisationId } of rows) {
+    const setting = (await listAutomations(db, organisationId)).find((a) => a.key === AUTOMATION);
+    if (!setting?.enabled) continue;
+    const connection = await readConnection(db, organisationId);
+    if (!connection) continue;
+    try {
+      const result = await syncContactEdits(db, runtime, organisationId);
+      if (result.toFlow || result.toXero || result.errors) {
+        log.info?.(`[xero] contact edits for organisation ${organisationId}: ${result.toFlow} from Xero, ${result.toXero} to Xero, ${result.clashes} differ, ${result.errors} refused`);
+      }
+    } catch (error) {
+      if (isCallsStopped(error)) continue;
+      log.error?.(`[xero] contact edits for organisation ${organisationId} failed: ${error?.code ?? 'error'}: ${error?.message ?? error}`);
+    }
+  }
+}

package/server/integrations/xero/create-contact.js

@@ -1,9 +1,11 @@
 import { createHash } from 'node:crypto';
+import { sql } from 'drizzle-orm';
 import { getContact } from '../../core/contacts.js';
-import { linkRecord } from '../../core/links.js';
+import { flowIdFor, linkRecord, supersedeLink } from '../../core/links.js';
 import { mapContact, matchContactFor, normaliseName, upsertContact } from './catalogue.js';
 import { xeroError } from './client.js';
 import { readConnection } from './connections.js';
+import { contactClashes } from './contact-sync.js';
 import { withXeroLane } from './governor.js';
 import { writesAllowed } from './settings.js';
 
@@ -75,12 +77,15 @@ function activeNamed(contacts, name) {
 export async function matchCustomer(db, runtime, { organisationId, contactId }) {
   const connection = await readConnection(db, organisationId);
   const connected = Boolean(connection && connection.mode === runtime.settings.mode);
-  if (!connected) return { state: 'off', offerCreate: false, xeroContactId: null, name: null };
+  if (!connected) return { state: 'off', offerCreate: false, offerLink: false, xeroContactId: null, name: null, differs: [] };
   const contact = await getContact(db, organisationId, contactId);
   const match = await matchContactFor(db, organisationId, { contactId, name: contact.name });
   return {
+    // Fields both sides changed (Two-way edits, contact-sync.js): alert only.
+    differs: match.state === 'matched' ? (await contactClashes(db, organisationId, contactId)).map(({ field, flow, xero }) => ({ field, flow, xero })) : [],
     state: match.state,
     offerCreate: match.state === 'missing' && runtime.settings.createContacts && writesAllowed(runtime.settings),
+    offerLink: match.state !== 'matched',
     xeroContactId: match.contact?.xeroContactId ?? null,
     name: match.contact?.name ?? null,
   };
@@ -124,3 +129,38 @@ export async function createCustomer(db, runtime, { organisationId, contactId, a
     return { outcome: 'created', ...kept };
   }));
 }
+
+// A person says which Xero contact a Flow contact is, when the names differ
+// or Xero has the name twice. Flow writes only its identity map (`person`);
+// Xero is not called. A link to a Xero contact that is archived or gone from
+// the copy ends first. A Xero contact another Flow contact has is refused.
+export async function linkCustomer(db, runtime, { organisationId, contactId, xeroContactId }) {
+  const connection = await readConnection(db, organisationId);
+  if (!connection || connection.mode !== runtime.settings.mode) {
+    throw xeroError('xero_not_connected', 'Connect Xero first.', { status: 409 });
+  }
+  const flowContact = await getContact(db, organisationId, contactId);
+  const { rows: [row] } = await db.execute(sql`select xero_contact_id, name, status from xero_contacts
+    where organisation_id = ${organisationId} and xero_contact_id = ${xeroContactId}`);
+  if (!row) throw xeroError('xero_contact_unknown', 'Flow has no copy of that Xero contact. Sync, then try again.', { status: 404 });
+  if (row.status !== 'ACTIVE') throw xeroError('xero_contact_archived', `"${row.name}" is archived in Xero. Restore it in Xero, then sync.`, { status: 409 });
+  const owner = await flowIdFor(db, organisationId, { system: 'xero', entity: 'contact', externalId: xeroContactId });
+  if (owner && owner !== contactId) {
+    throw xeroError('xero_contact_linked', `"${row.name}" is already the Xero contact of another Flow contact.`, { status: 409 });
+  }
+  const { rows: [current] } = await db.execute(sql`select l.id, l.external_id, x.status from external_links l
+    left join xero_contacts x on x.organisation_id = l.organisation_id and x.xero_contact_id = l.external_id
+    where l.organisation_id = ${organisationId} and l.system = 'xero' and l.entity = 'contact'
+      and l.flow_id = ${contactId} and l.state = 'active'`);
+  if (current && current.external_id !== xeroContactId) {
+    if (current.status === 'ACTIVE') {
+      throw xeroError('xero_contact_linked', `${flowContact.name} is already linked to a Xero contact.`, { status: 409 });
+    }
+    await supersedeLink(db, organisationId, current.id);
+  }
+  const link = await linkRecord(db, organisationId, {
+    entity: 'contact', flowId: contactId, system: 'xero', externalId: xeroContactId, matchedBy: 'person',
+  });
+  if (link.outcome === 'conflict') throw xeroError('xero_contact_linked', 'One side is already linked. Check the review list.', { status: 409 });
+  return { outcome: link.outcome, xeroContactId, name: row.name };
+}

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) });