@arcforgelabs/flow 2026.10.21 → 2026.10.23

package/server/integrations/xero/mirror.js

@@ -0,0 +1,295 @@
+import { createHash } from 'node:crypto';
+import { sql } from 'drizzle-orm';
+import { parseXeroDate } from './catalogue.js';
+import { withXeroLane } from './governor.js';
+
+// Flow's copy of the connected organisation's Xero invoices, credit notes and
+// payments (docs/DATA_SPINE.md, issue 54). Xero owns these records. Flow keeps
+// them so its reports cover the years before it was installed, and so the
+// ledger and the identity map can link them without spending Xero calls.
+//
+// Each resource keeps a cursor. A read asks Xero for the records changed since
+// the cursor, oldest change first, one page at a time, and stores each page in
+// one transaction with the cursor's next position. So a read can stop at any
+// page (the day's call budget, an error, a restart) and the next read goes on
+// from there. The first read has no cursor and copies the whole history; every
+// later read copies only changes.
+//
+// Paging is by time, not by page number: after a full page the cursor moves to
+// the last record's change time (less one second), so a record that changes
+// during a read moves ahead of the cursor and is read again, never skipped.
+// Only when one second holds a whole page does the page number move on.
+
+export const MIRROR_RESOURCES = Object.freeze(['invoices', 'credit_notes', 'payments']);
+
+// A Xero amount (a JSON number with up to 4 decimals) to whole cents, half away
+// from zero, without float drift.
+export function toCents(amount) {
+  if (amount === null || amount === undefined || amount === '') return null;
+  const match = /^(-?)(\d+)(?:\.(\d+))?$/.exec(String(amount).trim());
+  if (!match) return null;
+  const [, sign, whole, fraction = ''] = match;
+  const digits = `${fraction}000`;
+  let cents = Number(whole) * 100 + Number(digits.slice(0, 2));
+  if (Number(digits[2]) >= 5) cents += 1;
+  return sign ? -cents : cents;
+}
+
+// A Xero date to a calendar date (YYYY-MM-DD), as Xero shows it.
+function toDay(value) {
+  const at = parseXeroDate(value);
+  return at ? at.toISOString().slice(0, 10) : null;
+}
+
+const text = (value, keep) => (keep && value ? String(value) : null);
+
+function mapLines(lines, keep) {
+  return (lines ?? []).map((line) => ({
+    lineItemId: line.LineItemID ?? null,
+    itemCode: line.ItemCode || null,
+    description: text(line.Description, keep),
+    quantity: line.Quantity ?? null,
+    unitAmount: line.UnitAmount ?? null,
+    lineAmountCents: toCents(line.LineAmount),
+    taxAmountCents: toCents(line.TaxAmount),
+    discountRate: line.DiscountRate ?? null,
+    accountCode: line.AccountCode || null,
+    taxType: line.TaxType || null,
+  }));
+}
+
+export function mapInvoice(invoice, { keepReference = false } = {}) {
+  return {
+    xeroInvoiceId: invoice.InvoiceID,
+    type: invoice.Type,
+    invoiceNumber: invoice.InvoiceNumber || null,
+    reference: text(invoice.Reference, keepReference),
+    xeroContactId: invoice.Contact?.ContactID ?? null,
+    status: invoice.Status,
+    issuedOn: toDay(invoice.Date ?? invoice.DateString),
+    dueOn: toDay(invoice.DueDate ?? invoice.DueDateString),
+    fullyPaidOn: toDay(invoice.FullyPaidOnDate),
+    currency: invoice.CurrencyCode || null,
+    subtotalCents: toCents(invoice.SubTotal),
+    taxCents: toCents(invoice.TotalTax),
+    totalCents: toCents(invoice.Total),
+    amountDueCents: toCents(invoice.AmountDue),
+    amountPaidCents: toCents(invoice.AmountPaid),
+    amountCreditedCents: toCents(invoice.AmountCredited),
+    lines: mapLines(invoice.LineItems, keepReference),
+    xeroUpdatedAt: parseXeroDate(invoice.UpdatedDateUTC),
+  };
+}
+
+export function mapCreditNote(note, { keepReference = false } = {}) {
+  return {
+    xeroCreditNoteId: note.CreditNoteID,
+    type: note.Type,
+    creditNoteNumber: note.CreditNoteNumber || null,
+    reference: text(note.Reference, keepReference),
+    xeroContactId: note.Contact?.ContactID ?? null,
+    status: note.Status,
+    issuedOn: toDay(note.Date ?? note.DateString),
+    currency: note.CurrencyCode || null,
+    subtotalCents: toCents(note.SubTotal),
+    taxCents: toCents(note.TotalTax),
+    totalCents: toCents(note.Total),
+    remainingCreditCents: toCents(note.RemainingCredit),
+    allocations: (note.Allocations ?? []).map((a) => ({
+      xeroInvoiceId: a.Invoice?.InvoiceID ?? null,
+      amountCents: toCents(a.Amount),
+      allocatedOn: toDay(a.Date),
+    })),
+    lines: mapLines(note.LineItems, keepReference),
+    xeroUpdatedAt: parseXeroDate(note.UpdatedDateUTC),
+  };
+}
+
+export function mapPayment(payment, { keepReference = false } = {}) {
+  return {
+    xeroPaymentId: payment.PaymentID,
+    paymentType: payment.PaymentType || null,
+    status: payment.Status || 'AUTHORISED',
+    xeroInvoiceId: payment.Invoice?.InvoiceID ?? null,
+    xeroCreditNoteId: payment.CreditNote?.CreditNoteID ?? null,
+    paidOn: toDay(payment.Date),
+    amountCents: toCents(payment.Amount),
+    reference: text(payment.Reference, keepReference),
+    isReconciled: payment.IsReconciled ?? null,
+    xeroUpdatedAt: parseXeroDate(payment.UpdatedDateUTC),
+  };
+}
+
+// The hash covers what Flow keeps, so a change Flow does not keep (a field it
+// drops) never counts as a change.
+function hashOf(row) {
+  const { xeroUpdatedAt, ...content } = row;
+  return createHash('sha256').update(JSON.stringify(content)).digest('hex');
+}
+
+const json = (value) => JSON.stringify(value);
+
+// Each upsert writes only when the content changed, and answers whether it did.
+const UPSERT = {
+  invoices: (org, r, hash) => sql`
+    insert into xero_invoices (organisation_id, xero_invoice_id, type, invoice_number, reference, xero_contact_id, status,
+      issued_on, due_on, fully_paid_on, currency, subtotal_cents, tax_cents, total_cents, amount_due_cents,
+      amount_paid_cents, amount_credited_cents, lines, xero_updated_at, record_hash)
+    values (${org}, ${r.xeroInvoiceId}, ${r.type}, ${r.invoiceNumber}, ${r.reference}, ${r.xeroContactId}, ${r.status},
+      ${r.issuedOn}, ${r.dueOn}, ${r.fullyPaidOn}, ${r.currency}, ${r.subtotalCents}, ${r.taxCents}, ${r.totalCents},
+      ${r.amountDueCents}, ${r.amountPaidCents}, ${r.amountCreditedCents}, ${json(r.lines)}::jsonb, ${r.xeroUpdatedAt}, ${hash})
+    on conflict (organisation_id, xero_invoice_id) do update set
+      type = excluded.type, invoice_number = excluded.invoice_number, reference = excluded.reference,
+      xero_contact_id = excluded.xero_contact_id, status = excluded.status, issued_on = excluded.issued_on,
+      due_on = excluded.due_on, fully_paid_on = excluded.fully_paid_on, currency = excluded.currency,
+      subtotal_cents = excluded.subtotal_cents, tax_cents = excluded.tax_cents, total_cents = excluded.total_cents,
+      amount_due_cents = excluded.amount_due_cents, amount_paid_cents = excluded.amount_paid_cents,
+      amount_credited_cents = excluded.amount_credited_cents, lines = excluded.lines,
+      xero_updated_at = excluded.xero_updated_at, record_hash = excluded.record_hash, last_changed_at = now()
+    where xero_invoices.record_hash is distinct from excluded.record_hash
+    returning (xmax = 0) as inserted`,
+  credit_notes: (org, r, hash) => sql`
+    insert into xero_credit_notes (organisation_id, xero_credit_note_id, type, credit_note_number, reference, xero_contact_id,
+      status, issued_on, currency, subtotal_cents, tax_cents, total_cents, remaining_credit_cents, allocations, lines,
+      xero_updated_at, record_hash)
+    values (${org}, ${r.xeroCreditNoteId}, ${r.type}, ${r.creditNoteNumber}, ${r.reference}, ${r.xeroContactId}, ${r.status},
+      ${r.issuedOn}, ${r.currency}, ${r.subtotalCents}, ${r.taxCents}, ${r.totalCents}, ${r.remainingCreditCents},
+      ${json(r.allocations)}::jsonb, ${json(r.lines)}::jsonb, ${r.xeroUpdatedAt}, ${hash})
+    on conflict (organisation_id, xero_credit_note_id) do update set
+      type = excluded.type, credit_note_number = excluded.credit_note_number, reference = excluded.reference,
+      xero_contact_id = excluded.xero_contact_id, status = excluded.status, issued_on = excluded.issued_on,
+      currency = excluded.currency, subtotal_cents = excluded.subtotal_cents, tax_cents = excluded.tax_cents,
+      total_cents = excluded.total_cents, remaining_credit_cents = excluded.remaining_credit_cents,
+      allocations = excluded.allocations, lines = excluded.lines, xero_updated_at = excluded.xero_updated_at,
+      record_hash = excluded.record_hash, last_changed_at = now()
+    where xero_credit_notes.record_hash is distinct from excluded.record_hash
+    returning (xmax = 0) as inserted`,
+  payments: (org, r, hash) => sql`
+    insert into xero_payments (organisation_id, xero_payment_id, payment_type, status, xero_invoice_id, xero_credit_note_id,
+      paid_on, amount_cents, reference, is_reconciled, xero_updated_at, record_hash)
+    values (${org}, ${r.xeroPaymentId}, ${r.paymentType}, ${r.status}, ${r.xeroInvoiceId}, ${r.xeroCreditNoteId},
+      ${r.paidOn}, ${r.amountCents}, ${r.reference}, ${r.isReconciled}, ${r.xeroUpdatedAt}, ${hash})
+    on conflict (organisation_id, xero_payment_id) do update set
+      payment_type = excluded.payment_type, status = excluded.status, xero_invoice_id = excluded.xero_invoice_id,
+      xero_credit_note_id = excluded.xero_credit_note_id, paid_on = excluded.paid_on, amount_cents = excluded.amount_cents,
+      reference = excluded.reference, is_reconciled = excluded.is_reconciled, xero_updated_at = excluded.xero_updated_at,
+      record_hash = excluded.record_hash, last_changed_at = now()
+    where xero_payments.record_hash is distinct from excluded.record_hash
+    returning (xmax = 0) as inserted`,
+};
+
+const MAPPERS = { invoices: mapInvoice, credit_notes: mapCreditNote, payments: mapPayment };
+const ID_OF = { invoices: 'xeroInvoiceId', credit_notes: 'xeroCreditNoteId', payments: 'xeroPaymentId' };
+
+async function readCursor(db, organisationId, resource) {
+  await db.execute(sql`insert into xero_mirror_cursors (organisation_id, resource) values (${organisationId}, ${resource})
+    on conflict do nothing`);
+  const { rows: [row] } = await db.execute(sql`select * from xero_mirror_cursors
+    where organisation_id = ${organisationId} and resource = ${resource}`);
+  return { modifiedSince: row.modified_since ? new Date(row.modified_since) : null, page: row.page };
+}
+
+// Where the next page starts, from the page just read. A full page moves the
+// time cursor to its last change, less one second (Xero compares whole
+// seconds); when that does not move it forward, one second holds more than a
+// page, and the page number moves on instead.
+export function nextPosition({ modifiedSince, page }, rows, pageSize) {
+  const times = rows.map((r) => r.xeroUpdatedAt?.getTime()).filter(Number.isFinite);
+  const latest = times.length ? Math.max(...times) : null;
+  const full = rows.length >= pageSize;
+  if (!full) {
+    const since = latest === null ? modifiedSince : new Date(Math.floor(latest / 1000) * 1000 - 1000);
+    return { modifiedSince: since && modifiedSince && since < modifiedSince ? modifiedSince : since, page: 1, done: true };
+  }
+  const since = latest === null ? null : new Date(Math.floor(latest / 1000) * 1000 - 1000);
+  if (since && (!modifiedSince || since > modifiedSince)) return { modifiedSince: since, page: 1, done: false };
+  return { modifiedSince, page: page + 1, done: false };
+}
+
+// Reads one resource from its cursor until Xero has no more changes, the
+// mirror's share of the day's calls is spent, or `maxPages` pages are read.
+// Answers counts and why it stopped: `done`, `budget` or `max_pages`.
+export async function mirrorResource(db, runtime, organisationId, resource, { maxPages = 50 } = {}) {
+  if (!MIRROR_RESOURCES.includes(resource)) throw new TypeError(`unknown Xero mirror resource: ${resource}`);
+  const { settings } = runtime;
+  const map = MAPPERS[resource];
+  const pageSize = settings.mirrorPageSize;
+  const counts = { pages: 0, read: 0, inserted: 0, changed: 0, unchanged: 0 };
+  return withXeroLane('sync', async () => {
+    const { client } = await runtime.clientFor(db, organisationId);
+    let position = await readCursor(db, organisationId, resource);
+    for (;;) {
+      if (counts.pages >= maxPages) return { resource, ...counts, stopped: 'max_pages' };
+      const budget = runtime.governor.status(client.tenantId);
+      if (budget.dayRemaining <= Math.ceil(budget.dayLimit * settings.mirrorReserveFraction)) {
+        return { resource, ...counts, stopped: 'budget' };
+      }
+      let raw;
+      try {
+        raw = await client.listChangedPage(resource, { page: position.page, pageSize, modifiedSince: position.modifiedSince });
+      } catch (error) {
+        await db.execute(sql`update xero_mirror_cursors set last_error = ${`${error.code ?? 'error'}: ${String(error.message).slice(0, 300)}`}
+          where organisation_id = ${organisationId} and resource = ${resource}`);
+        throw error;
+      }
+      const rows = raw.map((record) => map(record, settings)).filter((r) => r[ID_OF[resource]]);
+      const next = nextPosition(position, rows, pageSize);
+      await db.transaction(async (tx) => {
+        for (const row of rows) {
+          const { rows: written } = await tx.execute(UPSERT[resource](organisationId, row, hashOf(row)));
+          if (!written.length) counts.unchanged += 1;
+          else if (written[0].inserted) counts.inserted += 1;
+          else counts.changed += 1;
+        }
+        await tx.execute(sql`update xero_mirror_cursors set
+          modified_since = ${next.modifiedSince}, page = ${next.page}, rows_read = rows_read + ${raw.length},
+          last_read_at = now(), last_error = null,
+          passes = passes + ${next.done ? 1 : 0},
+          last_pass_finished_at = case when ${next.done} then now() else last_pass_finished_at end
+          where organisation_id = ${organisationId} and resource = ${resource}`);
+      });
+      counts.pages += 1;
+      counts.read += raw.length;
+      position = next;
+      if (next.done) return { resource, ...counts, stopped: 'done' };
+    }
+  });
+}
+
+// Reads each resource in turn, one organisation at a time with any other Xero
+// work for it (runtime.serial).
+export async function mirrorXero(db, runtime, organisationId, { resources = MIRROR_RESOURCES, maxPages } = {}) {
+  return runtime.serial(organisationId, async () => {
+    const results = [];
+    for (const resource of resources) {
+      const result = await mirrorResource(db, runtime, organisationId, resource, { maxPages });
+      results.push(result);
+      if (result.stopped === 'budget') break;
+    }
+    return results;
+  });
+}
+
+// What the copy holds, and where each cursor stands. No Xero calls.
+export async function mirrorStatus(db, organisationId) {
+  const { rows: cursors } = await db.execute(sql`select resource, modified_since, page, passes, rows_read,
+    last_read_at, last_pass_finished_at, last_error from xero_mirror_cursors where organisation_id = ${organisationId}
+    order by resource`);
+  const { rows: [counts] } = await db.execute(sql`select
+    (select count(*)::int from xero_invoices where organisation_id = ${organisationId}) as invoices,
+    (select count(*)::int from xero_credit_notes where organisation_id = ${organisationId}) as credit_notes,
+    (select count(*)::int from xero_payments where organisation_id = ${organisationId}) as payments`);
+  return {
+    counts,
+    cursors: cursors.map((c) => ({
+      resource: c.resource,
+      modifiedSince: c.modified_since,
+      page: c.page,
+      passes: c.passes,
+      rowsRead: Number(c.rows_read),
+      lastReadAt: c.last_read_at,
+      lastPassFinishedAt: c.last_pass_finished_at,
+      lastError: c.last_error,
+    })),
+  };
+}

package/server/integrations/xero/routes.js

@@ -6,6 +6,8 @@ import { lastSync, listContacts, listItems, syncCatalogue } from './catalogue.js
 import { createXeroClient } from './client.js';
 import { describePush, listPushes, MAX_BATCH, previewDrafts, pushDrafts } from './drafts.js';
 import { recordXeroEvidence, recordXeroPayments } from './ledger.js';
+import { queueHistoryImport, resetImport } from './import.js';
+import { MIRROR_RESOURCES, mirrorStatus, mirrorXero } from './mirror.js';
 import { decryptToken, deleteConnection, describeConnection, readConnection, saveConnection } from './connections.js';
 import { authorizeUrl, exchangeCode, fetchConnections, revokeToken, selectConnection } from './oauth.js';
 import { writesAllowed } from './settings.js';
@@ -28,6 +30,9 @@ import { messagePage as themedMessagePage } from '../../ui/page.js';
 //   POST /obligations/:obligationId/check   owner or admin: Xero's invoice for
 //                                  a billable job, recorded on the ledger
 //   POST /payments/sync            owner or admin: Xero payments to the ledger
+//   POST /mirror                   owner or admin: copies Xero invoices, credit
+//                                  notes and payments changed since the last copy
+//   GET  /mirror?organisationId=   any signed-in person: what the copy holds
 //
 // Only an owner, with a verified owner sign-in, can connect or disconnect.
 // The callback carries no Flow session: the one-use state from /connect,
@@ -138,6 +143,7 @@ export function createXeroRouter({ db, personAuth, runtime, log = console, messa
         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,
@@ -149,8 +155,11 @@ export function createXeroRouter({ db, personAuth, runtime, log = console, messa
         key: settings.tokenKey,
       });
       runtime.remember(entry.organisationId, tokens);
+      // 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}`);
-      return res.type('html').send(page('Xero is connected', `Flow is connected to ${connection.tenantName || 'your Xero organisation'} (${settings.mode}). You can close this tab.`, 'success'));
+      return res.type('html').send(page('Xero is connected', `Flow is connected to ${connection.tenantName || 'your Xero organisation'} (${settings.mode}). Flow is now copying its invoice and payment history in the background. You can close this tab.`, 'success'));
     } catch (error) {
       log.error?.(`[xero] connect failed: ${error.code ?? 'error'}: ${error.message}`);
       const message = error instanceof FlowError ? error.message : 'Something went wrong talking to Xero. Try again.';
@@ -227,5 +236,21 @@ export function createXeroRouter({ db, personAuth, runtime, log = console, messa
     res.json({ ok: true, ...result });
   }));
 
+  router.post('/mirror', ...manager, handle(log, async (req, res) => {
+    const organisationId = await requireOrganisation(db, req.body?.organisationId);
+    const resources = req.body?.resources ?? MIRROR_RESOURCES;
+    if (!Array.isArray(resources) || !resources.length || !resources.every((r) => MIRROR_RESOURCES.includes(r))) {
+      throw new FlowError('invalid', `resources must list some of: ${MIRROR_RESOURCES.join(', ')}`);
+    }
+    const results = await mirrorXero(db, runtime, organisationId, { resources: [...new Set(resources)] });
+    log.info?.(`[xero] organisation ${organisationId}: person ${req.person.id} copied Xero records: ${JSON.stringify(results)}`);
+    res.json({ ok: true, results, ...(await mirrorStatus(db, organisationId)) });
+  }));
+
+  router.get('/mirror', ...signedIn, handle(log, async (req, res) => {
+    const organisationId = await requireOrganisation(db, req.query.organisationId);
+    res.json({ ok: true, ...(await mirrorStatus(db, organisationId)) });
+  }));
+
   return router;
 }

package/server/integrations/xero/settings.js

@@ -28,6 +28,8 @@ export const XERO_CALLBACK_PATH = '/api/xero/oauth/callback';
 export const DEFAULT_XERO_SCOPE = 'offline_access accounting.contacts accounting.invoices accounting.settings.read';
 export const DEFAULT_XERO_DAY_LIMIT = 1000;
 export const DEFAULT_DUE_DAYS = 30;
+export const DEFAULT_MIRROR_PAGE_SIZE = 200;
+export const MAX_MIRROR_PAGE_SIZE = 1000;
 
 function readEnv(env, name) {
   const value = env?.[name];
@@ -159,6 +161,12 @@ export function resolveXeroSettings(env = process.env) {
     defaultDueDays: readPositiveInteger(env, 'XERO_DEFAULT_DUE_DAYS', DEFAULT_DUE_DAYS),
     invoiceNumber,
     replayFixtures: readEnv(env, 'XERO_REPLAY_FIXTURES') || null,
+    // Free text on Xero records (references, line descriptions) can name a
+    // patient. Flow keeps it only when the lab turns this on (VISION.md).
+    keepReference: readOnOff(env, 'XERO_KEEP_REFERENCE'),
+    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),
     endpoints: XERO_ENDPOINTS,
   };
 }

package/server/ui/app-page.js

@@ -53,7 +53,7 @@ const BODY = `<div class="fx-app">
   <div id="toasts" class="fx-toasts" aria-live="polite"></div>
 </div>`;
 
-export const APP_PATHS = ['/sign-in', '/people', '/account', '/appearance'];
+export const APP_PATHS = ['/sign-in', '/people', '/integrations', '/account', '/appearance'];
 
 export function appPage({ defaultFamily }) {
   return renderPage({

package/server/ui/app.js

@@ -182,6 +182,7 @@ let me = null;
 
 const VIEWS = {
   people: { label: 'People', ownerOnly: true, render: renderPeople },
+  integrations: { label: 'Integrations', ownerOnly: true, render: renderIntegrations },
   account: { label: 'Account', render: renderAccount },
   appearance: { label: 'Appearance', render: renderAppearance },
 };
@@ -347,6 +348,147 @@ function personRow(person, host) {
     h('td', { class: 'fx-table__actions' }, h('div', { class: 'fx-row fx-row--end' }, actions)));
 }
 
+// Integrations: an owner turns Xero and Seazona on and enters their settings
+// here. Credentials are write-only: the server says whether each is set,
+// never its value (server/integrations/setup.js).
+const STATE_LABEL = { ready: 'On', disabled: 'Off', failed: 'Needs attention', restart_needed: 'Restart needed', not_started: 'Starting' };
+const STATE_TONE = { ready: 'success', disabled: 'info', failed: 'danger', restart_needed: 'warn', not_started: 'info' };
+
+async function renderIntegrations(main) {
+  const host = h('div', { class: 'fx-fields' }, h('div', { class: 'fx-skeleton' }));
+  main.append(
+    pageHeader('Integrations', { subtitle: 'Connect Flow to your accounting and lab systems. Each one uses an app you create in that system.' }),
+    host);
+  let body;
+  try {
+    body = await flow('/api/integrations');
+  } catch (error) {
+    host.replaceChildren(notice(error.message, 'danger'));
+    return;
+  }
+  const canChange = Boolean(me.ownerActions?.allowed);
+  host.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 has no secrets key, so it cannot store a client secret. Ask whoever hosts Flow to set FLOW_SECRETS_KEY (64 hex characters), then restart Flow.', 'warn', 'No secrets key.'),
+    ...body.integrations.map((integration) => integrationCard(integration, { canChange, organisations: body.organisations })),
+  ].filter(Boolean));
+}
+
+function integrationCard(integration, { canChange, organisations }) {
+  const card = h('section', { class: 'fx-panel', 'aria-label': integration.name });
+  const draw = (current) => {
+    const inputs = new Map();
+    const fields = current.fields.map((field) => {
+      const fromHost = field.source === 'host';
+      const disabled = !canChange || fromHost;
+      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 },
+          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)));
+      } else if (field.secret) {
+        input = h('input', { class: 'fx-input', type: 'password', autocomplete: 'off', disabled, placeholder: field.set ? 'Set. Type a new one to replace it.' : 'Paste it here' });
+      } else {
+        input = h('input', { class: 'fx-input', type: field.kind === 'url' ? 'url' : 'text', autocomplete: 'off', disabled, value: field.value ?? '' });
+      }
+      inputs.set(field.name, { field, input });
+      const suggestion = field.suggest === 'callback' ? `${location.origin}/api/${current.id}/oauth/callback` : null;
+      return h('label', { class: 'fx-field' },
+        h('span', { class: 'fx-label' }, field.label),
+        input,
+        fromHost ? h('span', { class: 'fx-dim' }, 'Set by the host. Change it there.') : null,
+        field.unreadable ? h('span', { class: 'fx-dim' }, 'Stored with another key. Enter it again.') : null,
+        field.help ? h('span', { class: 'fx-dim' }, field.help) : null,
+        suggestion && !disabled ? h('div', { class: 'fx-row' },
+          h('code', {}, suggestion),
+          h('button', { class: 'fx-btn fx-btn--ghost fx-btn--sm', type: 'button', onclick: () => { navigator.clipboard?.writeText(suggestion); toast('Copied.', 'success'); } }, 'Copy'),
+          h('button', { class: 'fx-btn fx-btn--ghost fx-btn--sm', type: 'button', onclick: () => { input.value = suggestion; } }, 'Use this')) : null);
+    });
+
+    const values = () => {
+      const out = {};
+      for (const [name, { field, input }] of inputs) {
+        if (field.source === 'host') continue;
+        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;
+      }
+      return out;
+    };
+    const save = async (enabled) => {
+      try {
+        const res = await flow(`/api/integrations/${current.id}`, { method: 'PUT', body: JSON.stringify({ values: values(), ...(enabled === undefined ? {} : { enabled }) }) });
+        const next = res.integration;
+        toast(next.state === 'ready' ? `${next.name} is on.` : next.state === 'disabled' ? `${next.name} settings saved. It is off.` : `${next.name} needs attention.`, next.state === 'failed' ? 'danger' : 'success');
+        draw(next);
+      } catch (error) {
+        toast(error.message, 'danger');
+      }
+    };
+
+    const on = current.enabled;
+    const guide = current.guide;
+    card.replaceChildren(...[
+      h('div', { class: 'fx-row' },
+        h('h2', { class: 'fx-title' }, current.name),
+        h('span', { class: 'fx-tag', 'data-tone': STATE_TONE[current.state] ?? 'info' }, STATE_LABEL[current.state] ?? current.state),
+        current.enabledBy === 'host' ? h('span', { class: 'fx-dim' }, 'Turned on by the host.') : null),
+      current.state === 'failed' && current.error ? notice(current.error, 'danger', 'It could not start.') : null,
+      guide ? h('details', { open: !on },
+        h('summary', {}, guide.title),
+        h('ol', {}, guide.steps.map((step) => h('li', {}, step))),
+        guide.link ? h('p', {}, h('a', { href: guide.link, target: '_blank', rel: 'noopener' }, guide.link)) : null) : null,
+      h('div', { class: 'fx-fields' }, fields),
+      canChange ? h('div', { class: 'fx-row fx-row--end' },
+        h('button', { class: 'fx-btn fx-btn--ghost', type: 'button', onclick: () => save(undefined) }, 'Save'),
+        current.enabledBy === 'host' ? null : on
+          ? h('button', { class: 'fx-btn fx-btn--danger', type: 'button', onclick: () => save(false) }, `Turn ${current.name} off`)
+          : h('button', { class: 'fx-btn fx-btn--primary', type: 'button', onclick: () => save(true) }, `Save and turn ${current.name} on`)) : null,
+      current.id === 'xero' && current.state === 'ready' ? xeroConnection(organisations, canChange) : null,
+    ].filter(Boolean));
+  };
+  draw(integration);
+  return card;
+}
+
+// Once Xero is on: each organisation's connection, the history copy, and
+// Connect, which goes to Xero and comes back.
+function xeroConnection(organisations, canChange) {
+  const host = h('div', { class: 'fx-fields' });
+  for (const organisation of organisations) {
+    const row = h('div', { class: 'fx-row' }, h('span', {}, organisation.name), h('span', { class: 'fx-dim' }, 'Checking…'));
+    host.append(row);
+    (async () => {
+      try {
+        const status = await flow(`/api/xero/status?organisationId=${organisation.id}`);
+        const parts = [h('span', {}, organisation.name)];
+        if (status.connected) {
+          parts.push(h('span', { class: 'fx-tag', 'data-tone': 'success' }, `Connected to ${status.connection?.tenantName ?? 'Xero'}`));
+          const mirror = await flow(`/api/xero/mirror?organisationId=${organisation.id}`).catch(() => null);
+          if (mirror) parts.push(h('span', { class: 'fx-dim' }, `History copied: ${mirror.counts.invoices} invoices, ${mirror.counts.credit_notes} credit notes, ${mirror.counts.payments} payments.`));
+        } else {
+          parts.push(h('span', { class: 'fx-dim' }, 'Not connected.'));
+        }
+        if (canChange) {
+          parts.push(h('button', { class: 'fx-btn fx-btn--primary fx-btn--sm', type: 'button', onclick: async () => {
+            try {
+              const { authorizeUrl } = await flow('/api/xero/connect', { method: 'POST', body: JSON.stringify({ organisationId: organisation.id }) });
+              location.assign(authorizeUrl);
+            } catch (error) {
+              toast(error.message, 'danger');
+            }
+          } }, status.connected ? 'Connect again' : 'Connect to Xero'));
+        }
+        row.replaceChildren(...parts);
+      } catch (error) {
+        row.replaceChildren(h('span', {}, organisation.name), notice(error.message, 'danger'));
+      }
+    })();
+  }
+  return h('div', {}, h('h3', { class: 'fx-label' }, 'Connection'), host);
+}
+
 async function invitePerson() {
   const data = await dialog({
     title: 'Invite someone',

package/server/ui/routes.js

@@ -21,6 +21,13 @@ const THEME_FILES = new Set(['themes.js', 'color-contrast.js', 'openclaw-palette
 const UI_FILES = new Set(['flow.css', 'appearance.js', 'clerk-appearance.js', 'app.js', 'flow-mark.svg']);
 const MAX_AGE = '1h';
 
+// Send one named file from dir. Passing dir as root limits the dotfile check
+// to the file name, so an install under a dot directory (such as
+// .flow-deploy/) still serves its assets. A missing file falls through to the
+// app's own 404.
+const sendNamed = (res, next, dir, file) =>
+  res.sendFile(file, { root: dir, maxAge: MAX_AGE }, (err) => err && !res.headersSent && next());
+
 export function createUiAssetsRouter({ rateLimitPerMinute = 600 } = {}) {
   const router = express.Router();
   const css = themeStylesheet();
@@ -33,14 +40,14 @@ export function createUiAssetsRouter({ rateLimitPerMinute = 600 } = {}) {
 
   const sendFrom = (dir, allowed) => (req, res, next) => {
     if (!allowed.has(req.params.file)) return next();
-    res.sendFile(join(dir, req.params.file), { maxAge: MAX_AGE });
+    sendNamed(res, next, dir, req.params.file);
   };
   router.get('/assets/theme/:file', sendFrom(themeDir, THEME_FILES));
   router.get('/assets/ui/:file', sendFrom(here, UI_FILES));
 
   for (const name of FONT_PACKAGES) {
     const dir = dirname(require.resolve(`@fontsource-variable/${name}/LICENSE`));
-    router.get(`/assets/fonts/${name}/index.css`, (_req, res) => res.sendFile(join(dir, 'index.css'), { maxAge: MAX_AGE }));
+    router.get(`/assets/fonts/${name}/index.css`, (_req, res, next) => sendNamed(res, next, dir, 'index.css'));
     router.use(`/assets/fonts/${name}/files`, express.static(join(dir, 'files'), { maxAge: MAX_AGE, index: false, fallthrough: false }));
   }