@arcforgelabs/flow 2026.10.48 → 2026.10.50

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';
@@ -12,8 +12,8 @@ import { IMPORT_STATES, importOverview, linkXeroInvoice, makeFlowInvoice, matchX
 import { queueHistoryImport, resetImport } from './import.js';
 import { MIRROR_RESOURCES, mirrorStatus, mirrorXero } from './mirror.js';
 import { accountingStatus, checkSentInvoices } from './reconcile.js';
-import { decryptToken, deleteConnection, describeConnection, readConnection, saveConnection } from './connections.js';
-import { authorizeUrl, exchangeCode, fetchConnections, revokeToken, selectConnection } from './oauth.js';
+import { CUSTOM_CONNECTION, decryptToken, deleteConnection, describeConnection, readConnection, saveConnection } from './connections.js';
+import { authorizeUrl, clientCredentials, exchangeCode, fetchConnections, revokeToken, selectConnection } from './oauth.js';
 import { writesAllowed } from './settings.js';
 import { readXeroUsage } from './usage.js';
 import { saveEvents, signatureValid } from './webhooks.js';
@@ -23,7 +23,8 @@ import { messagePage as themedMessagePage } from '../../ui/page.js';
 // The Xero adapter's routes, mounted at /api/xero (server/integrations/port.js).
 //
 //   GET  /status?organisationId=   any signed-in person: mode and connection
-//   POST /connect                  owner: returns Xero's approval address
+//   POST /connect                  owner: returns Xero's approval address, or
+//                                  connects a Custom Connection at once
 //   GET  /oauth/callback           Xero sends the owner back here
 //   POST /disconnect               owner: revokes and forgets the connection
 //   POST /sync                     owner or admin: copies Xero contacts and items
@@ -31,6 +32,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)
@@ -180,8 +183,59 @@ export function createXeroRouter({ db, personAuth, runtime, log = console, butto
     });
   }));
 
+  // Keeps the one Xero organisation these tokens reach, after proving it is
+  // one Flow may use (a Demo Company in sandbox). A refused code-flow grant
+  // is revoked at Xero. Then the history import starts.
+  async function connectWith(tokens, { organisationId, personId }) {
+    const connections = await fetchConnections(settings, runtime.transport, tokens.access_token);
+    let chosen;
+    try {
+      chosen = selectConnection(connections, settings);
+      const probe = createXeroClient({
+        tenantId: chosen.tenantId,
+        accessToken: async () => tokens.access_token,
+        fetch: runtime.transport,
+        governor: runtime.governor,
+        apiBase: settings.endpoints.api,
+        log,
+      });
+      await runtime.assertEnvironment(probe);
+    } catch (error) {
+      // Refused: Xero keeps no grant for an organisation Flow will not use.
+      if (tokens.refresh_token) await revokeToken(settings, runtime.transport, tokens.refresh_token).catch(() => false);
+      throw error;
+    }
+    const previous = await readConnection(db, organisationId);
+    const connection = await saveConnection(db, {
+      organisationId,
+      mode: settings.mode,
+      tenantId: chosen.tenantId,
+      tenantName: chosen.tenantName ?? null,
+      scope: tokens.scope ?? settings.scope,
+      // A Custom Connection has no refresh token; the column holds a sealed
+      // marker that is never read (runtime.js asks Xero again instead).
+      refreshToken: tokens.refresh_token ?? CUSTOM_CONNECTION,
+      connectedBy: personId,
+      key: settings.tokenKey,
+    });
+    runtime.remember(organisationId, tokens);
+    // A new connection is a person acting: calls stopped before resume.
+    await runtime.guardFor(db).resume();
+    // Another Xero organisation starts its history from the beginning.
+    if (previous && previous.tenantId !== connection.tenantId) await resetImport(db, organisationId);
+    await queueHistoryImport(db, organisationId, { reason: 'connected' });
+    log.info?.(`[xero] organisation ${organisationId} connected to Xero tenant ${connection.tenantId} (${settings.mode}, ${settings.connection}) by person ${personId}`);
+    return connection;
+  }
+
+  // A Custom Connection connects here at once; a Xero app answers with the
+  // approval address the browser opens.
   router.post('/connect', ...owner, handle(log, async (req, res) => {
     const organisationId = await requireOrganisation(db, req.body?.organisationId);
+    if (settings.connection === 'custom') {
+      const connection = await connectWith(await clientCredentials(settings, runtime.transport), { organisationId, personId: req.person.id });
+      return res.json({ ok: true, connected: true, connection: describeConnection(connection), mode: settings.mode });
+    }
     if (!settings.redirectUri) {
       throw Object.assign(new FlowError('xero_redirect_uri_missing', 'Set FLOW_PUBLIC_ORIGIN (or XERO_REDIRECT_URI) to this installation\'s address, and register its /api/xero/oauth/callback on the Xero app.'), { status: 503 });
     }
@@ -200,42 +254,7 @@ export function createXeroRouter({ db, personAuth, runtime, log = console, butto
     }
     try {
       const tokens = await exchangeCode(settings, runtime.transport, typeof req.query.code === 'string' ? req.query.code : '');
-      const connections = await fetchConnections(settings, runtime.transport, tokens.access_token);
-      let chosen;
-      try {
-        chosen = selectConnection(connections, settings);
-        const probe = createXeroClient({
-          tenantId: chosen.tenantId,
-          accessToken: async () => tokens.access_token,
-          fetch: runtime.transport,
-          governor: runtime.governor,
-          apiBase: settings.endpoints.api,
-          log,
-        });
-        await runtime.assertEnvironment(probe);
-      } catch (error) {
-        // Refused: Xero keeps no grant for an organisation Flow will not use.
-        await revokeToken(settings, runtime.transport, tokens.refresh_token).catch(() => false);
-        throw error;
-      }
-      const previous = await readConnection(db, entry.organisationId);
-      const connection = await saveConnection(db, {
-        organisationId: entry.organisationId,
-        mode: settings.mode,
-        tenantId: chosen.tenantId,
-        tenantName: chosen.tenantName ?? null,
-        scope: tokens.scope ?? settings.scope,
-        refreshToken: tokens.refresh_token,
-        connectedBy: entry.personId,
-        key: settings.tokenKey,
-      });
-      runtime.remember(entry.organisationId, tokens);
-      // A new connection is a person acting: calls stopped before resume.
-      await runtime.guardFor(db).resume();
-      // Another Xero organisation starts its history from the beginning.
-      if (previous && previous.tenantId !== connection.tenantId) await resetImport(db, entry.organisationId);
-      await queueHistoryImport(db, entry.organisationId, { reason: 'connected' });
-      log.info?.(`[xero] organisation ${entry.organisationId} connected to Xero tenant ${connection.tenantId} (${settings.mode}) by person ${entry.personId}`);
+      const connection = await connectWith(tokens, entry);
       const organisation = connection.tenantName || 'your Xero organisation';
       return res.type('html').send(page(
         'Xero is connected',
@@ -255,7 +274,8 @@ export function createXeroRouter({ db, personAuth, runtime, log = console, butto
     const connection = await readConnection(db, organisationId);
     if (!connection) return res.json({ ok: true, disconnected: false });
     let revoked = false;
-    try {
+    // A Custom Connection has no token to revoke: it ends in Xero's My Apps.
+    if (settings.connection !== 'custom') try {
       revoked = await revokeToken(settings, runtime.transport, decryptToken(connection.refreshTokenEnc, settings.tokenKey, organisationId));
     } catch (error) {
       log.warn?.(`[xero] could not revoke the Xero token for organisation ${organisationId}: ${error.code ?? 'error'}`);
@@ -274,7 +294,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 +314,17 @@ export function createXeroRouter({ db, personAuth, runtime, log = console, butto
     res.status(result.outcome === 'created' ? 201 : 200).json({ ok: true, ...result });
   }));
 
+  // A person links a Flow contact to a Xero contact of another name. Flow's
+  // identity map only: no Xero call.
+  router.post('/contacts/link', ...manager, handle(log, async (req, res) => {
+    const organisationId = await requireOrganisation(db, req.body?.organisationId);
+    if (typeof req.body?.contactId !== 'string' || !UUID.test(req.body.contactId)) throw new FlowError('invalid', 'contactId must be a Flow contact id');
+    if (typeof req.body?.xeroContactId !== 'string' || !req.body.xeroContactId.trim()) throw new FlowError('invalid', 'xeroContactId must be a Xero contact id');
+    const result = await linkCustomer(db, runtime, { organisationId, contactId: req.body.contactId, xeroContactId: req.body.xeroContactId.trim() });
+    log.info?.(`[xero] organisation ${organisationId}: person ${req.person.id} linked Xero contact ${result.xeroContactId} to Flow contact ${req.body.contactId}`);
+    res.json({ ok: true, ...result });
+  }));
+
   router.get('/items', ...signedIn, handle(log, async (req, res) => {
     const organisationId = await requireOrganisation(db, req.query.organisationId);
     res.json({ ok: true, items: await listItems(db, organisationId) });

package/server/integrations/xero/runtime.js

@@ -2,7 +2,7 @@ import { createCallGuard } from '../call-guard.js';
 import { createXeroClient, xeroError } from './client.js';
 import { decryptToken, readConnection, storeRotatedToken } from './connections.js';
 import { createGovernor } from './governor.js';
-import { createStateStore, refreshTokens } from './oauth.js';
+import { clientCredentials, createStateStore, refreshTokens } from './oauth.js';
 import { createReplayFetch, DEFAULT_REPLAY_FIXTURES, loadReplayFixtures } from './replay.js';
 import { resolveXeroSettings, writesAllowed } from './settings.js';
 
@@ -101,10 +101,13 @@ export function createXeroRuntime({ settings, fetch, now = Date.now, log = conso
     return db.transaction(async (tx) => {
       const connection = usable(await readConnection(tx, organisationId, { lock: true }));
       await guard.check(connection.tenantId, { resource: 'token' });
-      const refreshToken = decryptToken(connection.refreshTokenEnc, settings.tokenKey, organisationId);
+      // A Custom Connection has no refresh token: Flow asks with the client
+      // id and secret again, and nothing rotates.
+      const custom = settings.connection === 'custom';
+      const refreshToken = custom ? null : decryptToken(connection.refreshTokenEnc, settings.tokenKey, organisationId);
       let tokens;
       try {
-        tokens = await refreshTokens(settings, transport, refreshToken);
+        tokens = custom ? await clientCredentials(settings, transport) : await refreshTokens(settings, transport, refreshToken);
       } catch (error) {
         // invalid_grant: the connection is gone. invalid_client: the app's
         // client id or secret is wrong. Neither clears without a person.
@@ -116,7 +119,7 @@ export function createXeroRuntime({ settings, fetch, now = Date.now, log = conso
         throw error;
       }
       await guard.record(connection.tenantId, { resource: 'token', statusCode: 200 });
-      await storeRotatedToken(tx, organisationId, { refreshToken: tokens.refresh_token, scope: tokens.scope, key: settings.tokenKey });
+      if (!custom) await storeRotatedToken(tx, organisationId, { refreshToken: tokens.refresh_token, scope: tokens.scope, key: settings.tokenKey });
       remember(organisationId, tokens);
       return tokens.access_token;
     });

package/server/integrations/xero/settings.js

@@ -10,6 +10,14 @@
 //            is not DEMO, so a sandbox can never write to a real ledger.
 //   replay   no network: recorded, synthetic Xero responses
 //            (server/integrations/xero/fixtures). Development and CI.
+//
+// XERO_CONNECTION says how Flow gets its Xero access tokens.
+//   app      (default) a Xero web app: an owner approves in the browser, and
+//            Flow keeps the rotating refresh token.
+//   custom   a Xero Custom Connection (client credentials): no browser step
+//            and no refresh token. Sandbox only: Xero makes Custom
+//            Connections free on the Demo Company, so a demo or a test
+//            session connects with the client id and secret alone.
 
 import { backgroundJobsOn } from '../../core/host.js';
 
@@ -29,6 +37,8 @@ export const XERO_ENDPOINTS = Object.freeze({
 export const XERO_CALLBACK_PATH = '/api/xero/oauth/callback';
 // accounting.payments.read: Flow reads payments back (ledger.js, mirror.js).
 export const DEFAULT_XERO_SCOPE = 'offline_access accounting.contacts accounting.invoices accounting.payments.read accounting.settings.read';
+// A Custom Connection has no refresh token, so it asks for no offline_access.
+export const DEFAULT_CUSTOM_SCOPE = DEFAULT_XERO_SCOPE.replace('offline_access ', '');
 export const DEFAULT_XERO_DAY_LIMIT = 1000;
 export const DEFAULT_DUE_DAYS = 30;
 export const DEFAULT_MIRROR_PAGE_SIZE = 200;
@@ -121,6 +131,12 @@ export function resolveXeroSettings(env = process.env) {
   if (!mode) return null;
   if (!XERO_MODES.includes(mode)) throw new Error('XERO_MODE must be "live", "sandbox", "replay" or unset');
 
+  const connection = (readEnv(env, 'XERO_CONNECTION') || 'app').toLowerCase();
+  if (!['app', 'custom'].includes(connection)) throw new Error('XERO_CONNECTION must be "app", "custom" or unset');
+  if (connection === 'custom' && mode !== 'sandbox') {
+    throw new Error('XERO_CONNECTION=custom works only with XERO_MODE=sandbox (a Xero Demo Company)');
+  }
+
   const clientId = readEnv(env, 'XERO_CLIENT_ID');
   const clientSecret = readEnv(env, 'XERO_CLIENT_SECRET');
   const tokenKey = decodeTokenKey(readEnv(env, 'XERO_TOKEN_KEY'));
@@ -150,11 +166,12 @@ export function resolveXeroSettings(env = process.env) {
 
   return {
     mode,
+    connection,
     clientId: clientId || (mode === 'replay' ? 'replay-client-id' : ''),
     clientSecret: clientSecret || (mode === 'replay' ? 'replay-client-secret' : ''),
     tokenKey,
     redirectUri: resolveRedirectUri(env),
-    scope: readEnv(env, 'XERO_SCOPE') || DEFAULT_XERO_SCOPE,
+    scope: readEnv(env, 'XERO_SCOPE') || (connection === 'custom' ? DEFAULT_CUSTOM_SCOPE : DEFAULT_XERO_SCOPE),
     tenantId,
     tenantName,
     liveWrites: readOnOff(env, 'XERO_ALLOW_LIVE_WRITES'),

package/server/ui/app-page.js

@@ -51,7 +51,7 @@ const BODY = `<div class="fx-app">
   <div id="toasts" class="fx-toasts" aria-live="polite"></div>
 </div>`;
 
-export const APP_PATHS = ['/sign-in', '/jobs', '/invoices', '/invoices/:id', '/reconcile', '/reconcile/:id', '/xero-import', '/people', '/integrations', '/integrations/:id', '/account', '/appearance', '/invoicing-settings', '/invoicing-settings/:id', '/automations', '/price-list', '/custom-fields'];
+export const APP_PATHS = ['/sign-in', '/jobs', '/invoices', '/invoices/:id', '/contacts', '/contacts/:id', '/reconcile', '/reconcile/:id', '/xero-import', '/people', '/integrations', '/integrations/:id', '/account', '/appearance', '/invoicing-settings', '/invoicing-settings/:id', '/automations', '/price-list', '/price-list/:id', '/custom-fields'];
 
 export function appPage({ defaultFamily }) {
   return renderPage({

package/server/ui/app.js

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

package/server/ui/automations.js

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

package/server/ui/contacts.js

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