@arcforgelabs/flow 2026.10.32-beta.1 → 2026.10.33

package/server/integrations/xero/index.js

@@ -9,12 +9,13 @@ import { findInvoices, listCustomers, listPriceItems, mirrorState } from './look
 import { createXeroRouter } from './routes.js';
 import { createXeroRuntime, requireXeroSettings, XERO_CALL_GUARD } from './runtime.js';
 import { writesAllowed } from './settings.js';
+import { readChangesFirst } from './webhooks.js';
 
 // The Xero adapter (docs/XERO.md). FLOW_INTEGRATIONS=xero turns it on and
 // XERO_MODE says which Xero it acts on. Its tables are created only while it
 // is on (docs/INTEGRATIONS.md).
 
-export const XERO_TABLES = Object.freeze(['xero_connections', 'xero_contacts', 'xero_items', 'xero_sync_runs', 'xero_invoice_pushes', 'xero_payment_cursors', 'xero_invoices', 'xero_credit_notes', 'xero_payments', 'xero_mirror_cursors', 'xero_call_guard', 'xero_calls']);
+export const XERO_TABLES = Object.freeze(['xero_connections', 'xero_contacts', 'xero_items', 'xero_sync_runs', 'xero_invoice_pushes', 'xero_payment_cursors', 'xero_invoices', 'xero_credit_notes', 'xero_payments', 'xero_mirror_cursors', 'xero_call_guard', 'xero_calls', 'xero_webhook_events', 'xero_daily_checks']);
 
 // What an owner enters in Settings, Integrations (server/integrations/setup.js).
 // The refresh token's key comes from Flow's secrets key.
@@ -29,6 +30,7 @@ export const XERO_SETUP = {
       'Redirect URI: copy it from below, exactly.',
       'Open the app\'s Configuration. Copy the client id. Generate a secret and copy it: Xero shows it once.',
       'Paste both below, choose the mode, name your Xero organisation, and turn Xero on.',
+      'Optional, for changes in seconds: open the app\'s Webhooks page. Delivery URL: this installation\'s address plus /api/xero/webhooks. Tick Contacts and Invoices, and Credit notes when Xero offers it. Copy the webhook key into "Webhook key" below and save, then press Send "Intent to receive" in Xero.',
     ],
   },
   fields: [
@@ -38,6 +40,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_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'],
 };
@@ -129,6 +132,9 @@ export function createXeroAdapter({ runtime: given = null } = {}) {
       // Xero's invoice for one billable job, looked up live (ledger.js): the
       // `liveCheck` for draftInvoiceForObligation.
       checkInvoice: ({ organisationId, obligation }) => xeroLiveCheck(database, current(), organisationId)(obligation),
+      // Xero's latest changes into the copy just before Flow drafts by rule or
+      // sends (webhooks.js); no call when the copy is current.
+      readChanges: ({ organisationId }) => readChangesFirst(database, current(), organisationId),
       // Active Xero contacts, from Flow's copy (lookup.js).
       listCustomers: ({ organisationId }) => listCustomers(database, organisationId),
       // Sales invoices from the mirror, with the mirror's state (lookup.js).

package/server/integrations/xero/migrations/0007_xero_webhooks.sql

@@ -0,0 +1,30 @@
+-- Xero's webhooks and the daily check (issue #45). Each event Xero pushes, and
+-- each record the daily check finds out of step, waits here until Flow reads
+-- that record by id into its copy. One row per record: a second event for the
+-- same record before it is read only marks it pending again.
+CREATE TABLE IF NOT EXISTS "xero_webhook_events" (
+	"organisation_id" uuid NOT NULL REFERENCES "organisations"("id"),
+	"resource" text NOT NULL,
+	"resource_id" text NOT NULL,
+	"event_type" text,
+	"source" text NOT NULL,
+	"event_at" timestamp with time zone,
+	"received_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"pending" boolean DEFAULT true NOT NULL,
+	"read_at" timestamp with time zone,
+	CONSTRAINT "xero_webhook_events_pk" PRIMARY KEY("organisation_id", "resource", "resource_id")
+);
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "xero_webhook_events_pending" ON "xero_webhook_events" ("organisation_id", "resource") WHERE "pending";
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "xero_webhook_events_received" ON "xero_webhook_events" ("organisation_id", "source", "received_at");
+--> statement-breakpoint
+-- One full summary read of the invoices a day for each organisation.
+CREATE TABLE IF NOT EXISTS "xero_daily_checks" (
+	"organisation_id" uuid PRIMARY KEY NOT NULL REFERENCES "organisations"("id"),
+	"last_started_at" timestamp with time zone,
+	"last_finished_at" timestamp with time zone,
+	"last_read" integer,
+	"last_flagged" integer,
+	"last_error" text
+);

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

@@ -50,6 +50,13 @@
       "when": 1792490000000,
       "tag": "0006_xero_call_guard",
       "breakpoints": true
+    },
+    {
+      "idx": 7,
+      "version": "7",
+      "when": 1792500000000,
+      "tag": "0007_xero_webhooks",
+      "breakpoints": true
     }
   ]
 }

package/server/integrations/xero/mirror.js

@@ -182,6 +182,20 @@ const UPSERT = {
 const MAPPERS = { invoices: mapInvoice, credit_notes: mapCreditNote, payments: mapPayment };
 const ID_OF = { invoices: 'xeroInvoiceId', credit_notes: 'xeroCreditNoteId', payments: 'xeroPaymentId' };
 
+// Xero records as the copy's rows.
+export const mapRecords = (resource, raw, settings) => raw.map((record) => MAPPERS[resource](record, settings)).filter((r) => r[ID_OF[resource]]);
+
+// Writes each mapped row to the copy. `tx` is a transaction or the database.
+// Adds to `counts` (inserted, changed, unchanged).
+export async function storeRows(tx, organisationId, resource, rows, counts) {
+  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;
+  }
+}
+
 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`);
@@ -213,7 +227,6 @@ export function nextPosition({ modifiedSince, page }, rows, pageSize) {
 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 () => {
@@ -233,15 +246,10 @@ export async function mirrorResource(db, runtime, organisationId, resource, { ma
           where organisation_id = ${organisationId} and resource = ${resource}`);
         throw error;
       }
-      const rows = raw.map((record) => map(record, settings)).filter((r) => r[ID_OF[resource]]);
+      const rows = mapRecords(resource, raw, settings);
       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 storeRows(tx, organisationId, resource, rows, counts);
         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,

package/server/integrations/xero/routes.js

@@ -12,6 +12,7 @@ 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 { writesAllowed } from './settings.js';
+import { saveEvents, signatureValid } from './webhooks.js';
 import { DEFAULT_FAMILY } from '../../theme/themes.js';
 import { messagePage as themedMessagePage } from '../../ui/page.js';
 
@@ -38,6 +39,8 @@ import { messagePage as themedMessagePage } from '../../ui/page.js';
 //   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
+//   POST /webhooks                 Xero: change events, signed with the
+//                                  webhook key (XERO_WEBHOOK_KEY); no session
 //
 // 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,
@@ -93,6 +96,23 @@ export function createXeroRouter({ db, personAuth, runtime, log = console, messa
   const page = (title, text, tone) => messagePage({ title, text, tone });
   const { settings } = runtime;
   const router = express.Router();
+
+  // Xero's webhooks (webhooks.js), before the JSON parser: the signature
+  // covers the raw body. Xero wants 200 with no body within 5 seconds, and
+  // 401 for a bad signature (its "intent to receive" test sends both).
+  router.post('/webhooks', express.raw({ type: () => true, limit: '1mb' }), async (req, res) => {
+    if (!settings.webhookKey) return res.status(404).end();
+    const raw = Buffer.isBuffer(req.body) ? req.body : Buffer.alloc(0);
+    if (!signatureValid(settings.webhookKey, raw, req.get('x-xero-signature'))) return res.status(401).end();
+    try {
+      await saveEvents(db, runtime, JSON.parse(raw.toString('utf8') || '{}'));
+    } catch (error) {
+      log.error?.(`[xero] saving webhook events failed: ${error?.code ?? error?.name ?? 'error'}`);
+      return res.status(500).end();
+    }
+    return res.status(200).end();
+  });
+
   router.use(express.json({ limit: '256kb' }));
 
   // Sign-in off: nothing but the callback answers, and it fails for want of

package/server/integrations/xero/settings.js

@@ -167,6 +167,9 @@ export function resolveXeroSettings(env = process.env) {
     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),
+    // The key Xero signs each webhook with (issue #45), from the Xero app's
+    // Webhooks page. Unset, Flow answers no webhook and reads by polling only.
+    webhookKey: readEnv(env, 'XERO_WEBHOOK_KEY') || null,
     endpoints: XERO_ENDPOINTS,
   };
 }

package/server/integrations/xero/webhooks.js

@@ -0,0 +1,346 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { sql } from 'drizzle-orm';
+import { isCallsStopped } from '../call-guard.js';
+import { lastSync, parseXeroDate, syncCatalogue } from './catalogue.js';
+import { withXeroLane } from './governor.js';
+import { mirrorState } from './lookup.js';
+import { mapRecords, mirrorXero, storeRows, toCents } from './mirror.js';
+import { checkSentInvoices } from './reconcile.js';
+
+// Xero's webhooks, and the daily check (issue #45). The poll (import.js) reads
+// Xero's changes every 15 minutes. Webhooks make a change reach Flow in
+// seconds, and the daily check finds what both of them missed.
+//
+//   1. Xero posts an event to /api/xero/webhooks: a record id and what
+//      happened, never the record. Flow checks the signature, saves the id in
+//      the inbox (xero_webhook_events) and answers 200 at once.
+//   2. The worker reads the waiting invoices by id, up to 50 a call, into the
+//      copy (mirror.js), then compares the sent invoices again (reconcile.js).
+//      Credit notes are read as changes since the cursor; contacts refresh the
+//      contacts and items copy.
+//   3. While webhooks arrive, the poll waits an hour instead of 15 minutes. If
+//      they stop, it goes back to 15 minutes by itself.
+//   4. Once a day, one summary read of every invoice (about 1,000 a call)
+//      finds each copy row whose status, amounts or change time differ from
+//      Xero, and each row Xero no longer lists. Those go into the inbox and are
+//      read by id like an event. This catches part payments that do not move
+//      Xero's change time, and a webhook that never came.
+//
+// Every read goes through the call guard and the governor's sync lane, and
+// leaves the mirror's reserve of the day's calls for drafts and people. Flow
+// never writes to Xero here.
+
+export const BY_ID_BATCH = 50;
+// The poll's wait while webhooks arrive, and how recent the last one must be.
+export const WEBHOOK_REFRESH_MS = 60 * 60 * 1000;
+export const WEBHOOK_ACTIVE_MS = 24 * 60 * 60 * 1000;
+export const DAILY_CHECK_EVERY_MS = 24 * 60 * 60 * 1000;
+// A daily check that failed is tried again after this wait.
+const DAILY_CHECK_RETRY_MS = 60 * 60 * 1000;
+const SUMMARY_PAGE = 1000;
+// At most this many records a day go back for a read by id (5 calls), so a
+// check that finds the whole copy different cannot spend the day. The rest
+// wait for the next day's check.
+export const DAILY_FLAG_MAX = 250;
+const MAX_SUMMARY_PAGES = 50;
+// Contacts and items are read again at most this often for contact events.
+const CONTACTS_EVERY_MS = 60 * 60 * 1000;
+
+const CATEGORIES = { INVOICE: 'invoices', CREDITNOTE: 'credit_notes', CREDIT_NOTE: 'credit_notes', CONTACT: 'contacts' };
+
+// Xero signs the raw body with HMAC-SHA256 and the webhook key, in base64
+// (x-xero-signature). Compared in constant time.
+export function signatureValid(key, rawBody, signature) {
+  if (!key || typeof signature !== 'string' || !signature) return false;
+  const expected = createHmac('sha256', key).update(rawBody).digest();
+  let given;
+  try {
+    given = Buffer.from(signature, 'base64');
+  } catch {
+    return false;
+  }
+  return given.length === expected.length && timingSafeEqual(given, expected);
+}
+
+// Saves the events of one verified delivery. An event for an organisation not
+// connected in this mode is dropped. Answers how many were saved.
+export async function saveEvents(db, runtime, payload, { now = new Date() } = {}) {
+  const events = Array.isArray(payload?.events) ? payload.events : [];
+  if (!events.length) return 0;
+  const { rows } = await db.execute(sql`select organisation_id, tenant_id from xero_connections where mode = ${runtime.settings.mode}`);
+  const byTenant = new Map(rows.map((r) => [r.tenant_id, r.organisation_id]));
+  let saved = 0;
+  for (const event of events) {
+    const organisationId = byTenant.get(event?.tenantId);
+    if (!organisationId || typeof event.resourceId !== 'string' || !event.resourceId) continue;
+    const resource = CATEGORIES[String(event.eventCategory ?? '').toUpperCase()] ?? 'other';
+    const at = Date.parse(`${String(event.eventDateUtc ?? '').replace(/Z?$/, 'Z')}`);
+    await flag(db, organisationId, resource, event.resourceId, {
+      source: 'webhook', eventType: event.eventType ?? null, eventAt: Number.isNaN(at) ? null : new Date(at), now,
+    });
+    saved += 1;
+  }
+  return saved;
+}
+
+// Marks one record as waiting to be read by id.
+async function flag(db, organisationId, resource, resourceId, { source, eventType = null, eventAt = null, now = new Date() }) {
+  await db.execute(sql`
+    insert into xero_webhook_events (organisation_id, resource, resource_id, event_type, source, event_at, received_at)
+    values (${organisationId}, ${resource}, ${resourceId}, ${eventType}, ${source}, ${eventAt}, ${now})
+    on conflict (organisation_id, resource, resource_id) do update set
+      event_type = excluded.event_type, source = excluded.source, event_at = excluded.event_at,
+      received_at = excluded.received_at, pending = true`);
+}
+
+async function markRead(db, organisationId, resource, ids = null) {
+  const only = ids ? sql`and resource_id = any(${sql.param(ids)}::text[])` : sql``;
+  await db.execute(sql`update xero_webhook_events set pending = false, read_at = now()
+    where organisation_id = ${organisationId} and resource = ${resource} and pending ${only}`);
+}
+
+// Whether a webhook for this organisation arrived recently: the poll can wait.
+export async function webhooksActive(db, runtime, organisationId, { now = Date.now() } = {}) {
+  if (!runtime.settings.webhookKey) return false;
+  const { rows: [row] } = await db.execute(sql`select max(received_at) as at from xero_webhook_events
+    where organisation_id = ${organisationId} and source = 'webhook'`);
+  return Boolean(row?.at && Number(now) - new Date(row.at).getTime() <= WEBHOOK_ACTIVE_MS);
+}
+
+// Calls left above the reserve the mirror keeps for drafts and people.
+function overReserve(runtime, tenantId) {
+  const budget = runtime.governor.status(tenantId);
+  return budget.dayRemaining > Math.ceil(budget.dayLimit * runtime.settings.mirrorReserveFraction);
+}
+
+async function pendingIds(db, organisationId) {
+  const { rows } = await db.execute(sql`select resource, resource_id from xero_webhook_events
+    where organisation_id = ${organisationId} and pending order by received_at`);
+  const out = new Map();
+  for (const r of rows) out.set(r.resource, [...(out.get(r.resource) ?? []), r.resource_id]);
+  return out;
+}
+
+// Reads every waiting record of one organisation. Answers counts, or a
+// `stopped` reason: 'calls_stopped' (the call guard) or 'budget'.
+export async function readInbox(db, runtime, organisationId, { now = Date.now } = {}) {
+  const waiting = await pendingIds(db, organisationId);
+  const result = { invoices: { read: 0, inserted: 0, changed: 0, unchanged: 0 }, creditNotes: 0, contacts: false, sent: null };
+  if (!waiting.size) return result;
+  const { rows: [connection] } = await db.execute(sql`select tenant_id from xero_connections
+    where organisation_id = ${organisationId} and mode = ${runtime.settings.mode}`);
+  if (!connection) return result;
+  try {
+    await runtime.guardFor(db).check(connection.tenant_id);
+  } catch (error) {
+    if (isCallsStopped(error)) return { ...result, stopped: 'calls_stopped' };
+    throw error;
+  }
+
+  const invoiceIds = waiting.get('invoices') ?? [];
+  if (invoiceIds.length) {
+    const counts = result.invoices;
+    const stopped = await runtime.serial(organisationId, () => withXeroLane('sync', async () => {
+      const { client } = await runtime.clientFor(db, organisationId);
+      for (let i = 0; i < invoiceIds.length; i += BY_ID_BATCH) {
+        if (!overReserve(runtime, client.tenantId)) return 'budget';
+        const batch = invoiceIds.slice(i, i + BY_ID_BATCH);
+        const rows = mapRecords('invoices', await client.listInvoicesByIds(batch), runtime.settings);
+        await db.transaction(async (tx) => {
+          await storeRows(tx, organisationId, 'invoices', rows, counts);
+          // An id Xero did not return is read too: there is nothing more to get.
+          await markRead(tx, organisationId, 'invoices', batch);
+        });
+        counts.read += rows.length;
+      }
+      return null;
+    }));
+    if (stopped) return { ...result, stopped };
+    if (counts.inserted || counts.changed) result.sent = await checkSentInvoices(db, runtime, organisationId);
+  }
+
+  if (waiting.get('credit_notes')?.length) {
+    // Credit notes are few: one read of the changes since the cursor gets them.
+    const [read] = await mirrorXero(db, runtime, organisationId, { resources: ['credit_notes'] });
+    if (read?.stopped === 'budget') return { ...result, stopped: 'budget' };
+    result.creditNotes = read?.read ?? 0;
+    await markRead(db, organisationId, 'credit_notes');
+  }
+
+  if (waiting.get('contacts')?.length) {
+    const last = await lastSync(db, organisationId);
+    const at = last?.finishedAt ?? last?.startedAt;
+    if (!at || Number(now()) - new Date(at).getTime() >= CONTACTS_EVERY_MS) {
+      await syncCatalogue(db, runtime, organisationId);
+      await markRead(db, organisationId, 'contacts');
+      result.contacts = true;
+    }
+  }
+
+  // Events Flow does not copy (other categories) need no read.
+  if (waiting.get('other')?.length) await markRead(db, organisationId, 'other');
+  return result;
+}
+
+// The daily check for one organisation: one summary read of every invoice,
+// compared with the copy. Each row that differs, and each live copy row Xero
+// no longer lists, waits in the inbox to be read by id. Answers counts, or
+// `stopped`.
+export async function dailyCheck(db, runtime, organisationId, { now = () => new Date() } = {}) {
+  await db.execute(sql`insert into xero_daily_checks (organisation_id, last_started_at) values (${organisationId}, ${now()})
+    on conflict (organisation_id) do update set last_started_at = excluded.last_started_at`);
+  try {
+    const seen = [];
+    const stopped = await runtime.serial(organisationId, () => withXeroLane('sync', async () => {
+      const { client } = await runtime.clientFor(db, organisationId);
+      for (let page = 1; page <= MAX_SUMMARY_PAGES; page += 1) {
+        if (!overReserve(runtime, client.tenantId)) return 'budget';
+        const list = await client.listInvoiceSummaries({ page, pageSize: SUMMARY_PAGE });
+        seen.push(...list.filter((i) => i.InvoiceID));
+        if (list.length < SUMMARY_PAGE) return null;
+      }
+      return 'max_pages';
+    }));
+    if (stopped) {
+      await db.execute(sql`update xero_daily_checks set last_error = ${stopped} where organisation_id = ${organisationId}`);
+      return { read: seen.length, flagged: 0, stopped };
+    }
+    const { rows: copy } = await db.execute(sql`select xero_invoice_id, status, total_cents, amount_due_cents,
+      amount_paid_cents, amount_credited_cents, xero_updated_at from xero_invoices where organisation_id = ${organisationId}`);
+    const byId = new Map(copy.map((r) => [r.xero_invoice_id, r]));
+    const flagged = new Set();
+    for (const x of seen) {
+      const row = byId.get(x.InvoiceID);
+      byId.delete(x.InvoiceID);
+      if (!row || summaryDiffers(row, x)) flagged.add(x.InvoiceID);
+    }
+    // A live copy row Xero no longer lists: read it by id to learn its state.
+    for (const row of byId.values()) if (!['DELETED', 'VOIDED'].includes(row.status)) flagged.add(row.xero_invoice_id);
+    const at = now();
+    const list = [...flagged].slice(0, DAILY_FLAG_MAX);
+    for (const id of list) await flag(db, organisationId, 'invoices', id, { source: 'daily_check', now: at });
+    await db.execute(sql`update xero_daily_checks set last_finished_at = ${at}, last_read = ${seen.length},
+      last_flagged = ${flagged.size}, last_error = null where organisation_id = ${organisationId}`);
+    return { read: seen.length, flagged: flagged.size, queued: list.length, stopped: null };
+  } catch (error) {
+    await db.execute(sql`update xero_daily_checks set last_error = ${`${error.code ?? 'error'}: ${String(error.message).slice(0, 300)}`}
+      where organisation_id = ${organisationId}`);
+    throw error;
+  }
+}
+
+const cents = (value) => (value === null || value === undefined ? null : Number(value));
+
+// Whether a summary from Xero differs from the copy row in what the summary
+// carries: status, money, and the change time.
+export function summaryDiffers(row, summary) {
+  if (row.status !== summary.Status) return true;
+  for (const [column, field] of [['total_cents', 'Total'], ['amount_due_cents', 'AmountDue'], ['amount_paid_cents', 'AmountPaid'], ['amount_credited_cents', 'AmountCredited']]) {
+    if (summary[field] !== undefined && cents(row[column]) !== toCents(summary[field])) return true;
+  }
+  // Xero changed it after the copy's version (whole seconds, as Xero compares).
+  const changed = parseXeroDate(summary.UpdatedDateUTC);
+  const copied = row.xero_updated_at ? new Date(row.xero_updated_at) : null;
+  return Boolean(changed && (!copied || Math.floor(changed / 1000) > Math.floor(copied / 1000)));
+}
+
+// The organisations whose daily check is due: a complete copy, and no check
+// finished in the last day (or none tried in the last hour after a failure).
+export async function dueDailyChecks(db, runtime, { now = Date.now() } = {}) {
+  const { rows } = await db.execute(sql`select c.organisation_id, c.tenant_id, d.last_started_at, d.last_finished_at
+    from xero_connections c left join xero_daily_checks d on d.organisation_id = c.organisation_id
+    where c.mode = ${runtime.settings.mode}`);
+  const due = [];
+  for (const r of rows) {
+    const finished = r.last_finished_at ? new Date(r.last_finished_at).getTime() : null;
+    const started = r.last_started_at ? new Date(r.last_started_at).getTime() : null;
+    if (finished && Number(now) - finished < DAILY_CHECK_EVERY_MS) continue;
+    if (started && (!finished || started > finished) && Number(now) - started < DAILY_CHECK_RETRY_MS) continue;
+    if (!(await mirrorState(db, r.organisation_id, { now: new Date(Number(now)) })).complete) continue;
+    due.push({ organisationId: r.organisation_id, tenantId: r.tenant_id });
+  }
+  return due;
+}
+
+// Read before act (issue #45, step 5): just before Flow drafts by rule or
+// sends a batch, Xero's latest changes reach the copy. The copy counts as
+// current when webhooks arrive and none waits, or when it read Xero's changes
+// in the last READ_FIRST_MS. Otherwise this reads the waiting records and the
+// invoice and credit note changes now: about two calls. Answers { state }:
+//   fresh        no call was needed
+//   read         the copy read Xero now; `changed` counts invoices that changed
+//   unavailable  the read could not run (`reason`); act on nothing
+export const READ_FIRST_MS = 10 * 60 * 1000;
+
+export async function readChangesFirst(db, runtime, organisationId, { now = Date.now } = {}) {
+  const { rows: [connection] } = await db.execute(sql`select tenant_id from xero_connections
+    where organisation_id = ${organisationId} and mode = ${runtime.settings.mode}`);
+  if (!connection) return { state: 'unavailable', reason: 'Xero is not connected' };
+  const { rows: [{ waiting }] } = await db.execute(sql`select count(*)::int as waiting from xero_webhook_events
+    where organisation_id = ${organisationId} and pending`);
+  if (!waiting && await webhooksActive(db, runtime, organisationId, { now: Number(now()) })) return { state: 'fresh' };
+  const { rows: [{ oldest }] } = await db.execute(sql`select min(last_read_at) as oldest from xero_mirror_cursors
+    where organisation_id = ${organisationId} and resource in ('invoices', 'credit_notes')`);
+  if (!waiting && oldest && Number(now()) - new Date(oldest).getTime() <= READ_FIRST_MS) return { state: 'fresh' };
+  try {
+    const inbox = await readInbox(db, runtime, organisationId, { now });
+    if (inbox.stopped) return { state: 'unavailable', reason: inbox.stopped === 'budget' ? 'the day\'s Xero calls are kept for people' : 'Xero calls are stopped' };
+    const reads = await mirrorXero(db, runtime, organisationId, { resources: ['invoices', 'credit_notes'], maxPages: 5 });
+    const short = reads.find((r) => !['done', 'refused'].includes(r.stopped));
+    if (short) return { state: 'unavailable', reason: short.stopped === 'budget' ? 'the day\'s Xero calls are kept for people' : 'Xero has more changes than one read takes' };
+    const invoices = reads.find((r) => r.resource === 'invoices');
+    const changed = inbox.invoices.inserted + inbox.invoices.changed + (invoices?.inserted ?? 0) + (invoices?.changed ?? 0);
+    if (changed && !inbox.sent) await checkSentInvoices(db, runtime, organisationId);
+    return { state: 'read', changed };
+  } catch (error) {
+    return { state: 'unavailable', reason: isCallsStopped(error) ? 'Xero calls are stopped' : `reading Xero failed (${error?.code ?? 'error'})` };
+  }
+}
+
+// After a failed read, an organisation waits 1 minute, then 2, 4 and up to an
+// hour, so a failing read is never tried every tick.
+export const RETRY_FIRST_MS = 60 * 1000;
+export const RETRY_MAX_MS = 60 * 60 * 1000;
+
+// One worker step: reads each organisation's inbox, then runs any daily check
+// that is due. A stop by the call guard skips that organisation quietly; the
+// guard has reported it. A failure is logged once as an error; the same
+// failure again is a warning. `holds` keeps each organisation's wait between
+// steps.
+export async function runWebhookWork(db, runtime, { log = console, now = Date.now, holds = new Map() } = {}) {
+  const failed = (organisationId, what, error) => {
+    const held = holds.get(organisationId);
+    const failures = (held?.failures ?? 0) + 1;
+    holds.set(organisationId, { failures, until: Number(now()) + Math.min(RETRY_MAX_MS, RETRY_FIRST_MS * 2 ** (failures - 1)), code: error?.code ?? 'error' });
+    const line = `[xero] ${what} for organisation ${organisationId} failed: ${error?.code ?? 'error'}`;
+    if (held?.code === (error?.code ?? 'error')) log.warn?.(line);
+    else log.error?.(line);
+  };
+  const waiting = (organisationId) => (holds.get(organisationId)?.until ?? 0) > Number(now());
+
+  const { rows } = await db.execute(sql`select distinct e.organisation_id from xero_webhook_events e
+    join xero_connections c on c.organisation_id = e.organisation_id and c.mode = ${runtime.settings.mode}
+    where e.pending`);
+  for (const { organisation_id: organisationId } of rows) {
+    if (waiting(organisationId)) continue;
+    try {
+      const read = await readInbox(db, runtime, organisationId, { now });
+      holds.delete(organisationId);
+      if (read.invoices.read || read.creditNotes || read.contacts) {
+        log.info?.(`[xero] read waiting changes for organisation ${organisationId}: ${read.invoices.read} invoices, ${read.creditNotes} credit notes${read.contacts ? ', contacts' : ''}`);
+      }
+    } catch (error) {
+      if (!isCallsStopped(error)) failed(organisationId, 'reading waiting changes', error);
+    }
+  }
+  for (const { organisationId, tenantId } of await dueDailyChecks(db, runtime, { now: now() })) {
+    try {
+      await runtime.guardFor(db).check(tenantId);
+      const check = await dailyCheck(db, runtime, organisationId, { now: () => new Date(Number(now())) });
+      log.info?.(`[xero] daily check for organisation ${organisationId}: ${check.read} invoices, ${check.flagged} to read again${check.stopped ? `; stopped (${check.stopped})` : ''}`);
+    } catch (error) {
+      // dueDailyChecks waits an hour after a failed check.
+      if (!isCallsStopped(error)) log.error?.(`[xero] daily check for organisation ${organisationId} failed: ${error?.code ?? 'error'}`);
+    }
+  }
+}

package/server/ui/app.js

@@ -216,7 +216,7 @@ const ICON_PATHS = {
   person: '<circle cx="12" cy="8" r="4"/><path d="M4 21c0-4 3.6-7 8-7s8 3 8 7"/>',
   flag: '<path d="M5 21V4M5 4h11l-2 4 2 4H5"/>',
   search: '<circle cx="11" cy="11" r="6.5"/><path d="M16 16l4.5 4.5"/>',
-  menu: '<path d="M4 6h16M4 12h16M4 18h16"/>',
+  sidebar: '<rect x="3" y="4" width="18" height="16" rx="2.5"/><path d="M9.5 4v16"/>',
   palette: '<path d="M12 3a9 9 0 100 18c1.1 0 1.5-.8 1.5-1.6 0-1-.8-1.4-.8-2.4 0-.9.7-1.5 1.6-1.5H17a4 4 0 004-4c0-4.7-4-8.5-9-8.5z"/><circle cx="7.5" cy="11" r="1"/><circle cx="10" cy="7" r="1"/><circle cx="15" cy="7" r="1"/>',
 };
 
@@ -226,10 +226,12 @@ function icon(name) {
   return node;
 }
 
-// The menu button at the top of the sidebar. On a wide screen it folds the
-// sidebar to its icons and back, and the choice stays in this browser. On a
-// narrow screen the sidebar is a bar across the top, and the button opens
-// the menu below it; choosing a page, Escape or a click outside closes it.
+// The sidebar button at the top of the sidebar (a panel icon, not a
+// hamburger; folded or narrow, the logo stands in for it). On a wide screen it folds the sidebar to its icons and back,
+// and the choice stays in this browser. On a narrow screen the sidebar is a
+// bar across the top, and the button slides the menu in from the left as a
+// drawer over a dimmed page; choosing a page, Escape or a click on the page
+// closes it.
 const NARROW = window.matchMedia('(max-width: 820px)');
 const FOLDED_KEY = 'flow_sidebar_folded';
 
@@ -243,7 +245,7 @@ function drawMenu() {
   shell.toggleAttribute('data-folded', folded);
   const open = NARROW.matches ? shell.hasAttribute('data-menu-open') : !folded;
   const toggle = $('menu-toggle');
-  const label = NARROW.matches ? (open ? 'Close the menu' : 'Open the menu') : (folded ? 'Show the menu' : 'Fold the menu');
+  const label = NARROW.matches ? (open ? 'Close the menu' : 'Open the menu') : (folded ? 'Show the sidebar' : 'Hide the sidebar');
   toggle.setAttribute('aria-expanded', String(open));
   toggle.setAttribute('aria-label', label);
   toggle.title = label;
@@ -384,7 +386,13 @@ function renderShell() {
   const report = h('button', { type: 'button', class: 'fx-nav__report', 'data-nav': 'report', 'data-label': 'Report a problem', hidden: true },
     icon('flag'), h('span', { class: 'fx-nav__label' }, 'Report a problem'));
   nav.replaceChildren(...items, report);
-  $('menu-toggle').replaceChildren(icon('menu'));
+  // Folded or narrow, the logo is the sidebar button: it shows the mark and
+  // turns into the sidebar icon under the pointer or keyboard focus.
+  const mark = h('span', { class: 'fx-toggle__mark', 'aria-hidden': 'true' });
+  mark.innerHTML = document.querySelector('.fx-side__head .fx-brand svg')?.outerHTML ?? '';
+  const sidebar = icon('sidebar');
+  sidebar.classList.add('fx-toggle__icon');
+  $('menu-toggle').replaceChildren(mark, sidebar);
   $('menu-toggle').onclick = toggleMenu;
   drawMenu();
   // The sidebar foot shows who is signed in: photo or initial, then the name