@arcforgelabs/flow 2026.10.47 → 2026.10.48-1

package/server/integrations/xero/index.js

@@ -1,6 +1,8 @@
 import { fileURLToPath } from 'node:url';
 import { sql } from 'drizzle-orm';
 import { guardAlerts } from '../call-guard.js';
+import { deleteXeroInvoice } from './delete-invoice.js';
+import { createCustomer } from './create-contact.js';
 import { checkDrafts, documentFacts, pushInvoice, pushInvoices } from './drafts.js';
 import { readConnection } from './connections.js';
 import { createImportWorker } from './import.js';
@@ -41,6 +43,7 @@ export const XERO_SETUP = {
     { name: 'XERO_CLIENT_SECRET', label: 'Client secret', secret: true, help: 'Stored encrypted. Flow never shows it again.' },
     { name: 'XERO_TENANT_NAME', label: 'Xero organisation name', help: 'Live mode connects only the organisation with this exact name.' },
     { name: 'XERO_ALLOW_LIVE_WRITES', label: 'Create draft invoices in live Xero', kind: 'onoff', help: 'Off: Flow only reads from Xero.' },
+    { name: 'XERO_CREATE_CONTACTS', label: 'Create missing clients', kind: 'onoff', default: 'on', help: 'On: a pending invoice whose client is not in Xero offers Create. Off: add the client in Xero, then sync.' },
     { name: 'XERO_WEBHOOK_KEY', label: 'Webhook key', secret: true, help: 'From the Xero app\'s Webhooks page. Empty: Flow reads Xero\'s changes every 15 minutes instead.' },
   ],
   derivedKeys: ['XERO_TOKEN_KEY'],
@@ -115,6 +118,9 @@ export function createXeroAdapter({ runtime: given = null } = {}) {
       // One issued invoice to a Xero draft (drafts.js). The Flow invoice id
       // and version are the idempotency key.
       pushInvoice: ({ organisationId, invoiceId, pushedBy = null }) => pushInvoice(database, current(), { organisationId, invoiceId, pushedBy }),
+      // Read the linked Xero invoice, and delete it only while it is a draft
+      // (delete-invoice.js). The core voids in Flow after deleted or gone.
+      deleteInvoice: ({ organisationId, invoiceId, actor = null }) => deleteXeroInvoice(database, current(), { organisationId, invoiceId, actor }),
       // Several issued invoices, in batches of MAX_BATCH (drafts.js).
       pushInvoices: ({ organisationId, invoiceIds, pushedBy = null }) => pushInvoices(database, current(), { organisationId, invoiceIds, pushedBy }),
       // The Invoices page tab of each issued invoice (reconcile.js), from
@@ -141,6 +147,9 @@ export function createXeroAdapter({ runtime: given = null } = {}) {
       readChanges: ({ organisationId }) => readChangesFirst(database, current(), organisationId),
       // Active Xero contacts, from Flow's copy (lookup.js).
       listCustomers: ({ organisationId }) => listCustomers(database, organisationId),
+      // Create the Xero contact for one Flow contact, when that setting is on
+      // (create-contact.js). The Flow contact id is the idempotency key.
+      createCustomer: ({ organisationId, contactId, actor = null }) => createCustomer(database, current(), { organisationId, contactId, actor }),
       // Sales invoices from the mirror, with the mirror's state (lookup.js).
       findInvoices: ({ organisationId, ...query }) => findInvoices(database, organisationId, query),
       // Xero items, from Flow's copy, for the price list (lookup.js).

package/server/integrations/xero/migrations/0011_xero_invoice_deleted.sql

@@ -0,0 +1,11 @@
+-- Who deleted a Xero draft from Flow, and when. The push keeps Xero's status
+-- (DELETED or VOIDED). A link made on the Import page has no push, so it
+-- keeps the same who and when. The Xero adapter's own table: the core does
+-- not store this.
+ALTER TABLE "xero_invoice_pushes" ADD COLUMN IF NOT EXISTS "deleted_by" text;
+--> statement-breakpoint
+ALTER TABLE "xero_invoice_pushes" ADD COLUMN IF NOT EXISTS "deleted_at" timestamp with time zone;
+--> statement-breakpoint
+ALTER TABLE "xero_invoice_links" ADD COLUMN IF NOT EXISTS "deleted_by" text;
+--> statement-breakpoint
+ALTER TABLE "xero_invoice_links" ADD COLUMN IF NOT EXISTS "deleted_at" timestamp with time zone;

package/server/integrations/xero/migrations/0012_xero_contact_details.sql

@@ -0,0 +1,16 @@
+-- Billing fields on Flow's copy of a Xero contact, so a created client and
+-- a synced client keep the same record (docs/CONTACTS.md). The Xero adapter's
+-- own table: the core does not store this.
+ALTER TABLE "xero_contacts" ADD COLUMN IF NOT EXISTS "first_name" text;
+--> statement-breakpoint
+ALTER TABLE "xero_contacts" ADD COLUMN IF NOT EXISTS "last_name" text;
+--> statement-breakpoint
+ALTER TABLE "xero_contacts" ADD COLUMN IF NOT EXISTS "phone" text;
+--> statement-breakpoint
+ALTER TABLE "xero_contacts" ADD COLUMN IF NOT EXISTS "mobile" text;
+--> statement-breakpoint
+ALTER TABLE "xero_contacts" ADD COLUMN IF NOT EXISTS "account_number" text;
+--> statement-breakpoint
+ALTER TABLE "xero_contacts" ADD COLUMN IF NOT EXISTS "tax_number" text;
+--> statement-breakpoint
+ALTER TABLE "xero_contacts" ADD COLUMN IF NOT EXISTS "address" jsonb;

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

@@ -78,6 +78,20 @@
       "when": 1792530000000,
       "tag": "0010_xero_call_usage",
       "breakpoints": true
+    },
+    {
+      "idx": 11,
+      "version": "7",
+      "when": 1792540000000,
+      "tag": "0011_xero_invoice_deleted",
+      "breakpoints": true
+    },
+    {
+      "idx": 12,
+      "version": "7",
+      "when": 1792550000000,
+      "tag": "0012_xero_contact_details",
+      "breakpoints": true
     }
   ]
 }

package/server/integrations/xero/routes.js

@@ -4,6 +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 { createXeroClient } from './client.js';
 import { describePush, listPushes, MAX_BATCH, previewDrafts, pushDrafts } from './drafts.js';
 import { recordXeroEvidence, recordXeroPayments } from './ledger.js';
@@ -27,6 +28,9 @@ import { messagePage as themedMessagePage } from '../../ui/page.js';
 //   POST /disconnect               owner: revokes and forgets the connection
 //   POST /sync                     owner or admin: copies Xero contacts and items
 //   GET  /contacts?organisationId=&q=   any signed-in person: the copy
+//   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
 //   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)
@@ -59,6 +63,7 @@ export const XERO_ACTIONS = Object.freeze({
   sync: { cooldownMs: 5 * 60_000 },
   recheck: { cooldownMs: 30_000 },
   push: { cooldownMs: 0, budget: false },
+  createContact: { cooldownMs: 30_000 },
   obligationCheck: { cooldownMs: 30_000 },
   paymentsSync: { cooldownMs: 5 * 60_000 },
   mirror: { cooldownMs: 2 * 60_000 },
@@ -272,6 +277,22 @@ export function createXeroRouter({ db, personAuth, runtime, log = console, butto
     res.json({ ok: true, contacts: await listContacts(db, organisationId, { q: typeof req.query.q === 'string' ? req.query.q : '' }) });
   }));
 
+  // Whether this Flow contact is a Xero contact, and whether Create is offered.
+  // No Xero calls: it reads Flow's copy.
+  router.get('/contacts/match', ...signedIn, handle(log, async (req, res) => {
+    const organisationId = await requireOrganisation(db, req.query.organisationId);
+    if (typeof req.query.contactId !== 'string' || !UUID.test(req.query.contactId)) throw new FlowError('invalid', 'contactId must be a Flow contact id');
+    res.json({ ok: true, ...(await matchCustomer(db, runtime, { organisationId, contactId: req.query.contactId })) });
+  }));
+
+  router.post('/contacts', ...manager, act('createContact', (req) => req.body?.contactId), 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');
+    const result = await createCustomer(db, runtime, { organisationId, contactId: req.body.contactId, actor: `person:${req.person.id}` });
+    log.info?.(`[xero] organisation ${organisationId}: person ${req.person.id} ${result.outcome} Xero contact ${result.contact.xeroContactId} for Flow contact ${req.body.contactId}`);
+    res.status(result.outcome === 'created' ? 201 : 200).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/integrations/xero/settings.js

@@ -171,6 +171,9 @@ export function resolveXeroSettings(env = process.env) {
     // Free text on Xero records (references, line descriptions) is the lab's
     // own data, and the Import matches on it. On unless the lab turns it off.
     keepReference: readOnOff(env, 'XERO_KEEP_REFERENCE', true),
+    // On unless the lab turns it off: a pending invoice whose client is not
+    // in Xero offers to create that client (docs/CONTACTS.md).
+    createContacts: readOnOff(env, 'XERO_CREATE_CONTACTS', true),
     mirrorPageSize: Math.min(readPositiveInteger(env, 'XERO_MIRROR_PAGE_SIZE', DEFAULT_MIRROR_PAGE_SIZE), MAX_MIRROR_PAGE_SIZE),
     // The share of the day's calls the mirror leaves for drafts and people.
     mirrorReserveFraction: readFraction(env, 'XERO_MIRROR_RESERVE_FRACTION', 0.3),

package/server/ui/app.js

@@ -10,6 +10,7 @@ import { getAppearance, onAppearanceChange, setAppearance, loadFonts } from '/as
 import { flowClerkAppearance } from '/assets/ui/clerk-appearance.js';
 import { ACCENT_PRESETS, normalizeAccent, THEME_FAMILIES, tokensFor } from '/assets/theme/themes.js';
 import { renderInvoice, renderInvoiceList } from '/assets/ui/invoicing.js';
+import { renderContacts } from '/assets/ui/contacts.js';
 import { automationSection, renderAutomations } from '/assets/ui/automations.js';
 import { renderInvoicingSettings, sendModeSection } from '/assets/ui/invoicing-settings.js';
 import { renderPriceList } from '/assets/ui/price-list.js';
@@ -152,6 +153,7 @@ let me = null;
 const VIEWS = {
   jobs: { label: 'Jobs', icon: 'jobs', render: (main) => renderJobs(main, ui()) },
   invoices: { label: 'Invoices', icon: 'invoices', render: (main, id) => (id ? renderInvoice(main, ui(), id) : renderInvoiceList(main, ui())) },
+  contacts: { label: 'Contacts', icon: 'contacts', render: (main, id) => renderContacts(main, ui(), id) },
   reconcile: { label: 'Reconcile', icon: 'reconcile', render: (main, id) => renderReconcile(main, ui(), id) },
   'price-list': { label: 'Price list', icon: 'tag', render: (main, id) => (id === 'reconcile' ? renderPriceReconcile(main, ui()) : renderPriceList(main, ui())) },
   'invoicing-settings': { label: 'Rules', icon: 'rules', render: (main, id) => renderInvoicingSettings(main, ui(), id) },
@@ -171,6 +173,7 @@ const VIEWS = {
 const ICON_PATHS = {
   jobs: '<rect x="3" y="4" width="5" height="16" rx="1"/><rect x="10" y="4" width="5" height="11" rx="1"/><rect x="17" y="4" width="4" height="14" rx="1"/>',
   invoices: '<path d="M6 3h9l4 4v14H6z"/><path d="M14 3v5h5M9 13h7M9 17h5"/>',
+  contacts: '<rect x="3" y="4" width="18" height="16" rx="2"/><circle cx="9" cy="10" r="2"/><path d="M6 16c.4-1.6 1.5-2.4 3-2.4s2.6.8 3 2.4M14 9h5M14 13h4"/>',
   bolt: '<path d="M13 3L5 13h6l-1 8 8-10h-6z"/>',
   rules: '<path d="M3 6l2 2 4-4M3 16l2 2 4-4M13 6h8M13 12h8M13 18h8"/>',
   reconcile: '<path d="M4 8h13M13 4l4 4-4 4M20 16H7M11 12l-4 4 4 4"/>',
@@ -756,9 +759,10 @@ async function renderIntegration(main, id) {
       let input;
       if (field.kind === 'choice' || field.kind === 'onoff') {
         const choices = field.kind === 'onoff' ? [{ value: 'off', label: 'Off' }, { value: 'on', label: 'On' }] : field.choices;
-        input = h('select', { class: 'fx-select', disabled },
+        const fallback = field.kind === 'onoff' ? (field.default === 'on' || field.default === 'off' ? field.default : 'off') : '';
+        input = h('select', { class: 'fx-select', disabled, 'data-fallback': fallback },
           field.kind === 'choice' ? h('option', { value: '' }, 'Choose…') : null,
-          choices.map((c) => h('option', { value: c.value, selected: (field.value ?? (field.kind === 'onoff' ? 'off' : '')) === c.value }, c.label)));
+          choices.map((c) => h('option', { value: c.value, selected: (field.value ?? fallback) === c.value }, c.label)));
       } else if (field.secret) {
         input = h('input', { class: 'fx-input', type: 'password', autocomplete: 'off', disabled, placeholder: field.set ? 'Saved' : 'Paste it here' });
       } else {
@@ -781,7 +785,8 @@ async function renderIntegration(main, id) {
       for (const [name, { field, input }] of inputs) {
         const value = input.value.trim();
         if (field.secret) { if (value) out[name] = value; continue; }
-        if (value !== (field.value ?? (field.kind === 'onoff' ? 'off' : ''))) out[name] = value || null;
+        const fallback = input.dataset.fallback ?? (field.kind === 'onoff' ? 'off' : '');
+        if (value !== (field.value ?? fallback)) out[name] = value || null;
       }
       return out;
     };

package/server/ui/contacts.js

@@ -0,0 +1,260 @@
+// 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.
+import { initialsOf } from '/assets/ui/person.js';
+
+const DOCS = 'https://github.com/arcforgelabs/flow/blob/main/docs/CONTACTS.md';
+const KINDS = [['customer', 'Customer'], ['supplier', 'Supplier']];
+
+const field = (h, label, control) => h('label', { class: 'fx-field' }, h('span', { class: 'fx-label' }, label), control);
+const input = (h, attrs) => h('input', { class: 'fx-input', autocomplete: 'off', ...attrs });
+
+export async function renderContacts(main, ui, id) {
+  if (id) return renderContact(main, ui, id);
+  return renderContactList(main, ui);
+}
+
+async function renderContactList(main, ui) {
+  const { h, flow, toast, notice, dialog, pageHeader, go, me } = ui;
+  const canEdit = ['owner', 'admin'].includes(me?.person.role);
+  const host = h('div', { class: 'fx-panel' }, h('div', { class: 'fx-skeleton' }));
+  const search = input(h, { type: 'search', 'aria-label': 'Search', placeholder: 'Search', class: 'fx-input fx-contacts__search' });
+  const kind = h('select', { class: 'fx-select', 'aria-label': 'Kind' },
+    h('option', { value: 'all', selected: true }, 'All'),
+    ...KINDS.map(([value, label]) => h('option', { value }, `${label}s`)));
+  const page = h('div', { class: 'fx-contacts' });
+  const add = h('button', { class: 'fx-btn fx-btn--primary', type: 'button', hidden: !canEdit, onclick: () => createContact() }, 'New');
+  page.append(
+    pageHeader('Contacts', { help: { href: DOCS, label: 'How contacts work' }, actions: [add] }),
+    host,
+  );
+  main.append(page);
+
+  let rows = [];
+  const draw = () => {
+    const needle = search.value.trim().toLowerCase();
+    const shown = rows.filter((contact) => {
+      if (kind.value !== 'all' && contact.kind !== kind.value) return false;
+      if (!needle) return true;
+      return [contact.name, contact.email, contact.accountNumber].some((value) => String(value ?? '').toLowerCase().includes(needle));
+    });
+    const body = shown.length
+      ? h('table', { class: 'fx-table fx-people' },
+        h('thead', { class: 'fx-sr' }, h('tr', {}, h('th', {}, 'Name'), h('th', {}, 'Kind'), h('th', {}, 'Account'))),
+        h('tbody', {}, shown.map((contact) => h('tr', {},
+          h('td', {}, h('a', { class: 'fx-person', href: `/contacts/${contact.id}`, onclick: go },
+            h('span', { class: 'fx-avatar', 'aria-hidden': 'true' }, initialsOf(contact.name)),
+            h('span', { class: 'fx-person__text' },
+              h('span', { class: 'fx-person__name' }, contact.name, contact.active ? null : h('span', { class: 'fx-tag' }, 'Inactive')),
+              contact.email ? h('span', { class: 'fx-person__email' }, contact.email) : null))),
+          h('td', {}, KINDS.find(([value]) => value === contact.kind)?.[1] ?? contact.kind),
+          h('td', {}, contact.accountNumber ?? '')))))
+      : h('p', { class: 'fx-empty' }, rows.length ? 'Nothing matches.' : 'No contacts.');
+    host.replaceChildren(
+      h('div', { class: 'fx-contacts__tools' }, search, kind),
+      body,
+    );
+  };
+
+  search.addEventListener('input', draw);
+  kind.addEventListener('change', draw);
+
+  async function createContact() {
+    const name = input(h, { name: 'name', required: true, 'aria-label': 'Name' });
+    const kindInput = h('select', { class: 'fx-select', name: 'kind', 'aria-label': 'Kind' },
+      ...KINDS.map(([value, label]) => h('option', { value, selected: value === 'customer' }, label)));
+    const email = input(h, { name: 'email', type: 'email', 'aria-label': 'Email' });
+    const confirmed = await dialog({
+      title: 'New contact',
+      confirm: 'Create',
+      body: h('div', { class: 'fx-fields' },
+        field(h, 'Name', name),
+        field(h, 'Kind', kindInput),
+        field(h, 'Email', email)),
+    });
+    if (!confirmed) return;
+    try {
+      const body = await flow('/api/invoicing/contacts', {
+        method: 'POST',
+        body: JSON.stringify({
+          name: String(confirmed.get('name') ?? ''),
+          kind: String(confirmed.get('kind') ?? 'customer'),
+          email: String(confirmed.get('email') ?? '').trim() || null,
+        }),
+      });
+      go(`/contacts/${body.contact.id}`);
+    } catch (error) {
+      toast(error.message, 'danger');
+    }
+  }
+
+  try {
+    ({ contacts: rows } = await flow('/api/invoicing/contacts?kind=all&active=all&limit=200'));
+    draw();
+  } catch (error) {
+    host.replaceChildren(notice(error.message, 'danger'));
+  }
+}
+
+async function renderContact(main, ui, id) {
+  const { h, flow, toast, notice, pageHeader, crumbs, me } = ui;
+  const canEdit = ['owner', 'admin'].includes(me?.person.role);
+  const page = h('div', { class: 'fx-contacts' }, h('div', { class: 'fx-skeleton' }));
+  main.append(page);
+  let contact;
+  try {
+    ({ contact } = await flow(`/api/invoicing/contacts/${id}`));
+  } catch (error) {
+    page.replaceChildren(notice(error.message, 'danger'));
+    return;
+  }
+
+  const values = {
+    name: input(h, { value: contact.name ?? '' }),
+    kind: h('select', { class: 'fx-select', 'aria-label': 'Kind' },
+      ...KINDS.map(([value, label]) => h('option', { value, selected: value === contact.kind }, label))),
+    firstName: input(h, { value: contact.firstName ?? '' }),
+    lastName: input(h, { value: contact.lastName ?? '' }),
+    email: input(h, { type: 'email', value: contact.email ?? '' }),
+    phone: input(h, { value: contact.phone ?? '' }),
+    mobile: input(h, { value: contact.mobile ?? '' }),
+    accountNumber: input(h, { value: contact.accountNumber ?? '' }),
+    taxNumber: input(h, { value: contact.taxNumber ?? '' }),
+    taxRate: input(h, { value: contact.taxRate ?? '' }),
+  };
+  const address = contact.address ?? {};
+  const addressInputs = {
+    line1: input(h, { value: address.line1 ?? '', 'aria-label': 'Address line 1' }),
+    line2: input(h, { value: address.line2 ?? '', 'aria-label': 'Address line 2' }),
+    city: input(h, { value: address.city ?? '', 'aria-label': 'City' }),
+    region: input(h, { value: address.region ?? '', 'aria-label': 'Region' }),
+    postalCode: input(h, { value: address.postalCode ?? '', 'aria-label': 'Postal code' }),
+    country: input(h, { value: address.country ?? '', 'aria-label': 'Country' }),
+  };
+  const practitioners = h('textarea', {
+    class: 'fx-input', rows: '4', 'aria-label': 'Practitioners',
+  }, (contact.practitioners ?? []).map((person) => person.name).join('\n'));
+  const active = h('input', { type: 'checkbox', checked: contact.active });
+  for (const control of [...Object.values(values), ...Object.values(addressInputs), practitioners, active]) {
+    if (!canEdit) control.disabled = true;
+  }
+
+  const save = h('button', {
+    class: 'fx-btn fx-btn--primary', type: 'button', hidden: !canEdit,
+    onclick: async () => {
+      const addressBody = Object.fromEntries(Object.entries(addressInputs).map(([key, control]) => [key, control.value.trim()]));
+      const people = practitioners.value.split('\n').map((line) => line.trim()).filter(Boolean).map((name) => ({ name }));
+      save.disabled = true;
+      try {
+        const body = await flow(`/api/invoicing/contacts/${id}`, {
+          method: 'PATCH',
+          body: JSON.stringify({
+            name: values.name.value,
+            kind: values.kind.value,
+            firstName: values.firstName.value,
+            lastName: values.lastName.value,
+            email: values.email.value,
+            phone: values.phone.value,
+            mobile: values.mobile.value,
+            accountNumber: values.accountNumber.value,
+            taxNumber: values.taxNumber.value,
+            taxRate: values.taxRate.value,
+            address: Object.values(addressBody).some(Boolean) ? addressBody : null,
+            practitioners: people,
+            active: active.checked,
+          }),
+        });
+        toast('Saved.', 'success');
+        contact = body.contact;
+      } catch (error) {
+        toast(error.message, 'danger');
+      } finally {
+        save.disabled = false;
+      }
+    },
+  }, 'Save');
+
+  const xero = h('div');
+  page.replaceChildren(
+    crumbs(['/contacts', 'Contacts'], contact.name),
+    pageHeader(contact.name, { actions: [save] }),
+    h('section', { class: 'fx-card' },
+      h('div', { class: 'fx-contacts__grid' },
+        field(h, 'Name', values.name),
+        field(h, 'Kind', values.kind),
+        field(h, 'First name', values.firstName),
+        field(h, 'Last name', values.lastName),
+        field(h, 'Email', values.email),
+        field(h, 'Phone', values.phone),
+        field(h, 'Mobile', values.mobile),
+        field(h, 'Account', values.accountNumber),
+        field(h, 'Tax number', values.taxNumber),
+        field(h, 'Tax rate', values.taxRate),
+        h('div', { class: 'fx-contacts__wide fx-fields' },
+          field(h, 'Address', addressInputs.line1),
+          addressInputs.line2,
+          h('div', { class: 'fx-contacts__grid' },
+            field(h, 'City', addressInputs.city),
+            field(h, 'Region', addressInputs.region),
+            field(h, 'Postal code', addressInputs.postalCode),
+            field(h, 'Country', addressInputs.country))),
+        h('label', { class: 'fx-field fx-contacts__wide' },
+          h('span', { class: 'fx-label' }, 'Practitioners'),
+          practitioners),
+        h('label', { class: 'fx-check' }, active, 'Active'))),
+    xero,
+  );
+  void loadXero(ui, contact, canEdit, xero);
+}
+
+async function loadXero(ui, contact, canEdit, host) {
+  const { h, flow, toast, notice } = ui;
+  let context;
+  try {
+    context = await flow('/api/invoicing/context');
+  } catch {
+    return;
+  }
+  const organisationId = context.organisations?.[0]?.id;
+  if (!organisationId) return;
+  let match;
+  try {
+    match = await flow(`/api/xero/contacts/match?organisationId=${encodeURIComponent(organisationId)}&contactId=${encodeURIComponent(contact.id)}`);
+  } catch {
+    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 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}".`;
+  host.replaceChildren(h('section', { class: 'fx-card fx-offer' },
+    notice(text, match.state === 'matched' ? 'success' : 'danger', match.state === 'matched' ? 'Xero.' : 'Xero.'),
+    create));
+}

package/server/ui/flow.css

@@ -365,6 +365,7 @@ a.fx-link:hover, a.fx-link:focus-visible { border-color: var(--t-strong); }
 .fx-tile .fx-logo--icon { background: var(--fx-hover); color: var(--t-strong); box-shadow: inset 0 0 0 1px var(--fx-line); }
 .fx-tile h3 { overflow: hidden; color: var(--t-strong); font: 600 14.5px/1.35 var(--t-body); text-overflow: ellipsis; white-space: nowrap; }
 .fx-tile__meta { color: var(--t-dim); font-size: 12.5px; white-space: nowrap; }
+.fx-tile__go { display: none; }
 .fx-logo--icon .fx-lucide { width: 22px; height: 22px; }
 .fx-logo img { width: 28px; height: 28px; object-fit: contain; }
 .fx-logo--lg { width: 52px; height: 52px; }
@@ -1398,6 +1399,26 @@ body[data-state="loading"] .fx-loading { display: grid; justify-items: center; }
   [data-phone-layout="two-line"] tr.fx-table__group td { height: 32px; padding: 0; background: none; }
   [data-phone-layout="two-line"] tr.fx-table__group .fx-tick-cell { height: 32px; }
   [data-phone-layout="two-line"] tr.fx-table__group .fx-tick-cell .fx-tick { width: 44px; height: 44px; }
+  /* Tiles: every card is one 56px row, as a list row: the mark, the name,
+     the status and ›. The blurb and the button stay on the page it opens. */
+  .fx-int-grid, .fx-tiles__grid { gap: 8px; }
+  :is(.fx-int-card, .fx-tile)[data-phone-layout="one-line"] {
+    display: flex; align-items: center; gap: 12px; box-sizing: border-box;
+    height: 56px; padding: 0 8px 0 12px;
+  }
+  .fx-int-card[data-phone-layout="one-line"]:is(:hover, :focus-visible) { transform: none; box-shadow: none; }
+  [data-phone-layout="one-line"] .fx-int-card__head { display: contents; }
+  [data-phone-layout="one-line"] :is(.fx-int-card__blurb, .fx-int-card__btn) { display: none; }
+  [data-phone-layout="one-line"] .fx-logo { width: 32px; height: 32px; border-radius: var(--t-radius); }
+  [data-phone-layout="one-line"] .fx-logo img { width: 20px; height: 20px; }
+  [data-phone-layout="one-line"] .fx-logo--icon .fx-lucide { width: 18px; height: 18px; }
+  [data-phone-layout="one-line"] h3 {
+    flex: 1; min-width: 0; overflow: hidden; font: 600 14.5px/1.35 var(--t-body);
+    text-overflow: ellipsis; white-space: nowrap;
+  }
+  [data-phone-layout="one-line"] :is(.fx-status, .fx-tile__meta) { flex: none; }
+  [data-phone-layout="one-line"] .fx-tile__go { display: inline-flex; flex: none; color: var(--t-dim); }
+  [data-phone-layout="one-line"] .fx-tile__go .fx-lucide { width: 18px; height: 18px; }
 }
 
 @keyframes fx-rise { from { opacity: 0; transform: translateY(6px); } to { opacity: 1; transform: none; } }
@@ -1910,3 +1931,22 @@ body[data-state="loading"] .fx-loading { display: grid; justify-items: center; }
   .fx-xu-hour { flex: none; width: 10px; }
   .fx-xu__fold { padding: 12px; }
 }
+
+/* Contacts (server/ui/contacts.js) and the pending-invoice Create offer.
+   Phone targets stay on this page only, so other screenshots stay valid. */
+.fx-offer { display: flex; flex-wrap: wrap; align-items: center; gap: 10px; }
+.fx-offer > .fx-notice { flex: 1 1 220px; }
+.fx-contacts { display: flex; flex-direction: column; gap: 16px; min-width: 0; }
+.fx-contacts__tools { display: flex; flex-wrap: wrap; align-items: center; gap: 8px; padding: 12px 16px; border-bottom: 1px solid var(--fx-line-soft); }
+.fx-contacts__search { flex: 1 1 180px; max-width: 320px; }
+.fx-contacts .fx-card { padding: 16px 20px; }
+.fx-contacts__grid { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 14px; }
+.fx-contacts__wide { grid-column: 1 / -1; }
+.fx-contacts textarea.fx-input { min-height: 96px; padding: 8px 10px; resize: vertical; }
+.fx-contacts .fx-person { color: inherit; text-decoration: none; }
+@media (max-width: 639px) {
+  .fx-contacts__grid { grid-template-columns: minmax(0, 1fr); }
+  .fx-offer .fx-btn,
+  .fx-contacts :is(.fx-btn, .fx-input, .fx-select, .fx-check) { min-height: 44px; }
+  .fx-contacts .fx-help { min-width: 44px; min-height: 44px; }
+}