@arcforgelabs/flow 2026.10.48-1 → 2026.10.49

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@arcforgelabs/flow",
-  "version": "2026.10.48-1",
+  "version": "2026.10.49",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@arcforgelabs/flow",
-      "version": "2026.10.48-1",
+      "version": "2026.10.49",
       "license": "MIT",
       "dependencies": {
         "@clerk/backend": "3.25.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcforgelabs/flow",
-  "version": "2026.10.48-1",
+  "version": "2026.10.49",
   "description": "Invoicing, bill entry and a financial dashboard for labs, with Seazona and Xero integrations.",
   "license": "MIT",
   "repository": {

package/server/core/automations.js

@@ -22,6 +22,10 @@ import { refreshReferences } from './references.js';
 //     on the Invoices page, until a person changes it or moves it back.
 //   reference_from_rule: a draft made from a job keeps the Reference the
 //     lab's Reference rule gives (references.js), as the job's fields arrive.
+//   add_contacts, add_xero_contacts: a customer of the work system, or of the
+//     accounting system, that no Flow contact is named like becomes one.
+//   sync_contact_edits: contact edits on either side of the Xero link reach
+//     the other (server/integrations/xero/contact-sync.js).
 
 const BATCH = 500;
 
@@ -71,6 +75,36 @@ export const AUTOMATIONS = Object.freeze([
     readConfig: (config) => readMappingConfig(config),
     remap: true,
   },
+  {
+    // Runs inside the pipeline's read of the work system's customers
+    // (pipeline.js, linkCustomers), before its jobs are read.
+    key: 'add_contacts',
+    place: 'seazona',
+    name: 'Add new clients',
+    hint: 'A new Seazona client becomes a contact.',
+    defaults: { enabled: true, config: {} },
+    readConfig: () => ({}),
+  },
+  {
+    // Runs inside the pipeline's read of the accounting system's customers
+    // (pipeline.js, linkCustomers). Off until a person turns it on.
+    key: 'add_xero_contacts',
+    place: 'xero',
+    name: 'Add Xero clients',
+    hint: 'Each Xero client becomes a contact.',
+    defaults: { enabled: false, config: {} },
+    readConfig: () => ({}),
+  },
+  {
+    // Runs on the Xero adapter's own worker (xero/contact-sync.js), which
+    // writes to Xero only while writes are allowed. Off until a person turns it on.
+    key: 'sync_contact_edits',
+    place: 'xero',
+    name: 'Two-way edits',
+    hint: 'A contact edit in Flow or Xero reaches the other. A clash waits for you.',
+    defaults: { enabled: false, config: {} },
+    readConfig: () => ({}),
+  },
   {
     key: 'mark_ready_from_work_status',
     place: 'seazona',

package/server/core/pipeline.js

@@ -10,6 +10,7 @@ import { observeJob, observeWithdrawn, recordAccountingEvidence, setHold } from
 import { loadMappingContext, mapLines } from './line-mapping.js';
 import { checkPrices, readCatalogues } from './price-list.js';
 import { linkRecord, priorLinkFor } from './links.js';
+import { createContact, readContact } from './contacts.js';
 import { HISTORY_ACTOR, HISTORY_HOLD_REASON, isHistoryHeld } from './history.js';
 import { deadHoldSince, deadSince, enqueueJob, runNextJob } from './queue.js';
 
@@ -88,20 +89,29 @@ function byName(records) {
 }
 
 // Links each customer of one system to the Flow customer with the same name,
-// when one record on each side has it and neither side is linked yet.
-export async function linkCustomers(db, organisationId, { system, customers }) {
+// when one record on each side has it and neither side is linked yet. With
+// `adopt`, a customer no Flow contact is named like becomes a new Flow
+// contact, linked to it (`imported`), so its jobs find their customer
+// (docs/CONTACTS.md). Two customers of one name stay for a person.
+export async function linkCustomers(db, organisationId, { system, customers, adopt = false }) {
   const flow = await db.select({ id: contacts.id, name: contacts.name }).from(contacts)
     .where(and(eq(contacts.organisationId, organisationId), eq(contacts.kind, 'customer')));
   const links = await activeLinks(db, organisationId, { system, entity: 'contact' });
   const linkedFlow = new Set(links.map((l) => l.flowId));
   const linkedExternal = new Set(links.map((l) => l.externalId));
   const flowByName = byName(flow);
-  const result = { linked: 0, alreadyLinked: 0, unmatched: 0, sameName: 0 };
+  const result = { linked: 0, alreadyLinked: 0, unmatched: 0, sameName: 0, added: 0 };
   for (const [key, external] of byName(customers)) {
     const own = flowByName.get(key) ?? [];
     for (const customer of external) {
       if (linkedExternal.has(String(customer.id))) result.alreadyLinked += 1;
     }
+    if (adopt && own.length === 0 && external.length === 1 && external[0].adoptable !== false && !linkedExternal.has(String(external[0].id))) {
+      if (await adoptCustomer(db, organisationId, { system, customer: external[0] })) {
+        result.added += 1;
+        continue;
+      }
+    }
     if (external.length !== 1 || own.length !== 1) {
       const waiting = external.filter((c) => !linkedExternal.has(String(c.id))).length;
       if (own.length === 0) result.unmatched += waiting;
@@ -119,6 +129,32 @@ export async function linkCustomers(db, organisationId, { system, customers }) {
   return result;
 }
 
+// The customer's own fields when Flow can keep them all, else its name only.
+async function adoptCustomer(db, organisationId, { system, customer }) {
+  const name = String(customer.name ?? '').trim();
+  const offered = { ...(customer.contact ?? {}), kind: 'customer', name };
+  let values;
+  try {
+    values = readContact(offered);
+  } catch (error) {
+    if (!(error instanceof FlowError)) throw error;
+    values = readContact({ kind: 'customer', name });
+  }
+  return db.transaction(async (tx) => {
+    let row;
+    try {
+      row = await createContact(tx, organisationId, values);
+    } catch (error) {
+      if (error instanceof FlowError && error.code === 'conflict') return false;
+      throw error;
+    }
+    const { outcome } = await linkRecord(tx, organisationId, {
+      entity: 'contact', flowId: row.id, system, externalId: String(customer.id), matchedBy: 'imported',
+    });
+    return outcome === 'linked' || outcome === 'existing';
+  });
+}
+
 async function readCursor(db, organisationId, name) {
   const [row] = await db.select().from(pipelineCursors)
     .where(and(eq(pipelineCursors.organisationId, organisationId), eq(pipelineCursors.name, name)));
@@ -500,9 +536,12 @@ export async function runPipelineOnce(db, integrations, { now = new Date() } = {
   if (work) {
     let restart = (summary.prices?.linked ?? 0) > 0;
     if (typeof work.capabilities.listCustomers === 'function') {
-      summary.workCustomers = await linkCustomers(db, organisationId, { system: work.id, customers: await work.capabilities.listCustomers({ organisationId }) });
+      const adding = (await listAutomations(db, organisationId)).find((a) => a.key === 'add_contacts');
+      summary.workCustomers = await linkCustomers(db, organisationId, {
+        system: work.id, customers: await work.capabilities.listCustomers({ organisationId }), adopt: Boolean(adding?.enabled),
+      });
       // New customer links reach jobs read before them.
-      restart ||= summary.workCustomers.linked > 0;
+      restart ||= summary.workCustomers.linked + summary.workCustomers.added > 0;
     }
     summary.work = await ingestWork(db, organisationId, { adapter: work, restart });
     // After the live feed, so a job both report is the live one.
@@ -512,8 +551,9 @@ export async function runPipelineOnce(db, integrations, { now = new Date() } = {
   }
   if (accounting) {
     if (typeof accounting.capabilities.listCustomers === 'function') {
+      const adding = (await listAutomations(db, organisationId)).find((a) => a.key === 'add_xero_contacts');
       summary.accountingCustomers = await linkCustomers(db, organisationId, {
-        system: accounting.id, customers: await accounting.capabilities.listCustomers({ organisationId }),
+        system: accounting.id, customers: await accounting.capabilities.listCustomers({ organisationId }), adopt: Boolean(adding?.enabled),
       });
     }
     const settings = await readInvoicingSettings(db, organisationId);

package/server/integrations/port.js

@@ -32,7 +32,7 @@ export const CAPABILITIES = Object.freeze([
   'personSettings', // { personId }: each person's own choices in this integration, as [{ key, label, hint, kind, value }]
   'setPersonSetting', // { personId, key, value }: change one, answers the new list
   'jobIssues', // open issues the integration holds for jobs, by job ref: a short phrase and the page where a person fixes it
-  'listCustomers', // the system's customers, by id and name, for the identity map (Seazona: clients; Xero: contacts)
+  'listCustomers', // the system's customers, by id and name, for the identity map (Seazona: clients; Xero: contacts). An optional `contact` is the Flow contact a new customer becomes; `adoptable` false keeps one from becoming a contact (docs/CONTACTS.md)
   'createCustomer', // { organisationId, contactId, actor }: create the system's customer from the Flow contact. Answers { outcome, contact }. Xero, when Create missing clients is on.
   'findInvoices', // sales invoices in the accounting system's copy, for the matcher; never a live call
   'readChanges', // { state: fresh | read | unavailable }: the accounting system's latest changes into its copy now, just before Flow drafts or sends (read before act)

package/server/integrations/seazona/feed.js

@@ -134,12 +134,19 @@ export async function readBillableOrder(db, orderId) {
 // with no company name is listed by its full name. A client the client list
 // never gave (the list can be closed to an API client) is listed by the
 // company name its orders carry, so its jobs still find their customer.
+// `contact` is the Flow contact a new client becomes (docs/CONTACTS.md).
 export async function listClients(db) {
-  const rows = await db.select({ id: seazonaClients.id, company: seazonaClients.company, fullName: seazonaClients.fullName, active: seazonaClients.active })
-    .from(seazonaClients);
+  const rows = await db.select({
+    id: seazonaClients.id, company: seazonaClients.company, fullName: seazonaClients.fullName, active: seazonaClients.active,
+    accountNumber: seazonaClients.accountNumber, email: seazonaClients.email, phone: seazonaClients.phone,
+    address: seazonaClients.address, taxRate: seazonaClients.taxRate, doctors: seazonaClients.doctors,
+  }).from(seazonaClients);
   const listed = rows
     .filter((r) => r.active !== false)
-    .map((r) => ({ id: r.id, name: (r.company || r.fullName || '').trim() }))
+    .map((r) => {
+      const name = (r.company || r.fullName || '').trim();
+      return { id: r.id, name, contact: clientContact(r, name) };
+    })
     .filter((r) => r.name);
   const known = new Set(rows.map((r) => r.id));
   const fromOrders = await db.selectDistinctOn([seazonaOrders.clientId], { id: seazonaOrders.clientId, company: seazonaOrders.company })
@@ -148,10 +155,40 @@ export async function listClients(db) {
     .orderBy(seazonaOrders.clientId, sql`${seazonaOrders.lastChangedAt} desc`);
   return [
     ...listed,
-    ...fromOrders.filter((r) => !known.has(r.id)).map((r) => ({ id: r.id, name: r.company.trim() })),
+    ...fromOrders.filter((r) => !known.has(r.id)).map((r) => {
+      const name = r.company.trim();
+      return { id: r.id, name, contact: { kind: 'customer', name } };
+    }),
   ];
 }
 
+// A Seazona client as a Flow contact: the billing fields and the doctors as
+// practitioners. A field Flow cannot keep is left out.
+const cut = (value, max) => {
+  const text = String(value ?? '').trim();
+  return text && text.length <= max ? text : null;
+};
+export function clientContact(row, name) {
+  const address = row.address ?? {};
+  const kept = {
+    line1: cut(address.address1, 255), line2: cut(address.address2, 255), city: cut(address.city, 255),
+    region: cut(address.region, 255), postalCode: cut(address.postalCode, 255), country: cut(address.countryCode, 255),
+  };
+  const practitioners = (Array.isArray(row.doctors) ? row.doctors : [])
+    .map((doctor) => cut(doctor?.fullName, 255)).filter(Boolean).slice(0, 30).map((person) => ({ name: person }));
+  const contact = { kind: 'customer', name, practitioners };
+  const email = cut(row.email, 255);
+  if (email) contact.email = email;
+  const phone = cut(row.phone, 50);
+  if (phone) contact.phone = phone;
+  const account = cut(row.accountNumber, 50);
+  if (account) contact.accountNumber = account;
+  const taxRate = cut(row.taxRate, 50);
+  if (taxRate) contact.taxRate = taxRate;
+  if (Object.values(kept).some(Boolean)) contact.address = Object.fromEntries(Object.entries(kept).filter(([, v]) => v));
+  return contact;
+}
+
 // Seazona's products, from Flow's copy (the products lane reads them daily),
 // for the price list's links and price check (server/core/price-list.js).
 // Seazona says only whether a product is taxable: taxable reads as GST.

package/server/integrations/sentry/index.js

@@ -47,8 +47,8 @@ export const SENTRY_SETUP = {
     { name: 'SENTRY_DSN', label: 'DSN', kind: 'url', help: 'From the Sentry project\'s Client Keys. Browsers see it, so it is not a secret.' },
     { name: 'SENTRY_ENVIRONMENT', label: 'Environment', help: 'How Sentry labels this installation, for example production. Empty: production, or workspace in a Replit workspace.' },
     { name: 'SENTRY_CLIENT', label: 'Client', help: 'The name your support desk files this installation\'s reports under. Sent as the client tag. Empty: no client tag.' },
-    { name: 'SENTRY_FEEDBACK', label: 'Report a problem button', kind: 'onoff', help: 'On: everyone signed in can send a report, with a screenshot, to this Sentry project.' },
-    { name: 'SENTRY_REPLAY', label: 'Replay with reports', kind: 'onoff', help: 'On: each report and each browser error keeps up to the last minute of the page, as a replay with every word hidden.' },
+    { name: 'SENTRY_FEEDBACK', label: 'Report button', kind: 'onoff', help: 'On: everyone signed in can send a report, with a screenshot, to this Sentry project.' },
+    { name: 'SENTRY_REPLAY', label: 'Replay', kind: 'onoff', help: 'On: each report and each browser error keeps up to the last minute of the page, as a replay with every word hidden.' },
     { name: 'SENTRY_TRACES_SAMPLE_RATE', label: 'Traces', help: 'The share of clicks, page loads and requests timed, from 0 (off) to 1 (all). Empty: 0.2.' },
   ],
 };

package/server/integrations/xero/client.js

@@ -233,6 +233,9 @@ export function createXeroClient({
     async listContacts({ maxPages } = {}) {
       return collectPages(async (page) => (await request('GET', 'Contacts', { query: { page } })).Contacts, { maxPages });
     },
+    async getContact(contactId) {
+      return first((await request('GET', `Contacts/${encodeURIComponent(contactId)}`)).Contacts);
+    },
     async findContactsByName(name) {
       return (await request('GET', 'Contacts', { query: { where: `Name==${quote(name)}` } })).Contacts ?? [];
     },
@@ -329,6 +332,26 @@ export function createXeroClient({
       }
       return created;
     },
+    // Changes the fields in `changes` on one contact (contact-sync.js). The
+    // body holds only those fields and the id; Xero keeps every other field.
+    async updateContact(contactId, changes, { idempotencyKey }) {
+      if (!contactId) throw new TypeError('updateContact: contactId is required');
+      if (!idempotencyKey) throw new TypeError('updateContact: idempotencyKey is required');
+      const payload = await request('POST', `Contacts/${encodeURIComponent(contactId)}`, {
+        query: { summarizeErrors: 'false' },
+        body: { Contacts: [{ ...changes, ContactID: contactId }] },
+        headers: { 'Idempotency-Key': idempotencyKey },
+      });
+      const updated = first(payload.Contacts);
+      const messages = validationMessages(updated);
+      if (!updated?.ContactID || updated.HasErrors || updated.StatusAttributeString === 'ERROR' || messages.length) {
+        throw xeroError('xero_validation_failed', messages.join(' ') || 'Xero refused the contact change.', {
+          status: 422,
+          details: messages.length ? { validationErrors: messages } : undefined,
+        });
+      }
+      return updated;
+    },
     async createInvoice(invoice, { idempotencyKey }) {
       if (!idempotencyKey) throw new TypeError('createInvoice: idempotencyKey is required');
       const payload = await request('POST', 'Invoices', {

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