@arcforgelabs/flow 2026.10.30 → 2026.10.32-beta.1

package/server/integrations/xero/import.js

@@ -1,14 +1,20 @@
 import { randomUUID } from 'node:crypto';
 import { sql } from 'drizzle-orm';
-import { enqueueJob, runNextJob } from '../../core/queue.js';
+import { deadHoldSince, deadSince, enqueueJob, runNextJob } from '../../core/queue.js';
+import { isCallsStopped } from '../call-guard.js';
 import { lastSync, syncCatalogue } from './catalogue.js';
+import { mirrorState } from './lookup.js';
 import { MIRROR_RESOURCES, mirrorXero } from './mirror.js';
+import { checkSentInvoices } from './reconcile.js';
 
-// The history import. When an owner connects Xero, Flow copies the
-// organisation's invoices, credit notes and payments into the mirror
-// (mirror.js) as a background job, so nobody runs a script by hand. The job
-// reads in slices; a slice that stops at the day's budget or its page limit
-// queues the next slice. It only reads from Xero.
+// The history import, then the reads of changes. When an owner connects Xero,
+// Flow copies the organisation's invoices, credit notes and payments into the
+// mirror (mirror.js) as a background job, so nobody runs a script by hand. The
+// job reads in slices; a slice that stops at the day's budget or its page
+// limit queues the next slice. When every resource is read to its end, the
+// same job is queued again for REFRESH_MS later and reads only what changed
+// since its cursor (issue #131), so the copy stays fresh (lookup.js). It only
+// reads from Xero.
 
 export const IMPORT_KIND = 'xero.import';
 const IMPORT_KEY = 'history';
@@ -18,6 +24,10 @@ const LEASE_MS = 30 * 60 * 1000;
 // Xero's day limit resets on a rolling day; an hour is a cheap re-check.
 const BUDGET_WAIT_MS = 60 * 60 * 1000;
 const IDLE_MS = 30 * 1000;
+// How often a finished copy reads Xero's changes again. Each read costs about
+// one call per resource when little changed: 96 a day for each of invoices and
+// credit notes, inside the reserve the mirror leaves (XERO_MIRROR_RESERVE_FRACTION).
+export const REFRESH_MS = 15 * 60 * 1000;
 // Contacts and items are read again once a day, so the matcher can link each
 // customer (server/core/pipeline.js) without a person pressing Sync.
 const CATALOGUE_EVERY_MS = 24 * 60 * 60 * 1000;
@@ -44,12 +54,33 @@ export async function organisationsToImport(db, mode) {
   return rows.map((r) => r.organisation_id);
 }
 
+// The next read for one organisation: queued now unless one is open already.
+export async function queueChangesRead(db, organisationId, { runAfter = null } = {}) {
+  return queueHistoryImport(db, organisationId, { reason: 'changes', runAfter });
+}
+
 // One slice of the import for one job. Answers what it read and whether more
 // remains (`more`: 'budget' or 'max_pages').
+// While the call guard stops Xero calls the slice does not fail, so it does
+// not spend the job's attempts: it answers `more: 'stopped'` with the wait,
+// or no wait for a stop only a person clears (connecting queues the import).
 export async function runImportSlice(db, runtime, job, { maxPages = SLICE_PAGES } = {}) {
-  const results = await mirrorXero(db, runtime, job.organisationId, { maxPages });
-  const stopped = results.find((r) => r.stopped !== 'done')?.stopped ?? null;
-  return { results, more: stopped };
+  let results;
+  try {
+    results = await mirrorXero(db, runtime, job.organisationId, { maxPages });
+  } catch (error) {
+    if (!isCallsStopped(error)) throw error;
+    return { results: [], more: error.retryAfterMs === null ? null : 'stopped', retryAfterMs: error.retryAfterMs, stoppedBy: error.code };
+  }
+  // A refused resource waits for a person; it never queues another slice.
+  const stopped = results.find((r) => !['done', 'refused'].includes(r.stopped))?.stopped ?? null;
+  // Each invoice Flow sent, against what the copy now holds (issue #132):
+  // an edit, void or delete in Xero opens a review item. No Xero calls.
+  const invoices = results.find((r) => r.resource === 'invoices');
+  const sent = invoices && (invoices.inserted || invoices.changed || job.payload?.reason !== 'changes')
+    ? await checkSentInvoices(db, runtime, job.organisationId)
+    : null;
+  return { results, more: stopped, ...(sent ? { sent } : {}) };
 }
 
 // Claims and runs one due import job, then queues the next slice when one is
@@ -61,33 +92,106 @@ export async function runImportOnce(db, runtime, { workerId = `xero-import-${ran
     handlers: { [IMPORT_KIND]: (job) => runImportSlice(db, runtime, job, { maxPages }) },
   });
   if (ran?.outcome === 'succeeded' && ran.job.result?.more) {
-    const wait = ran.job.result.more === 'budget' ? BUDGET_WAIT_MS : 0;
+    const { more, retryAfterMs } = ran.job.result;
+    const wait = more === 'budget' ? BUDGET_WAIT_MS : more === 'stopped' ? Math.max(IDLE_MS, Number(retryAfterMs) || BUDGET_WAIT_MS) : 0;
     await queueHistoryImport(db, ran.job.organisationId, { reason: ran.job.result.more, runAfter: new Date(Number(now()) + wait) });
+  } else if (ran?.outcome === 'succeeded' && !ran.job.result?.stoppedBy) {
+    // Read to the end: read the changes again later. A stop only a person
+    // clears queues nothing; connecting or saving the settings queues it.
+    await queueChangesRead(db, ran.job.organisationId, { runAfter: new Date(Number(now()) + REFRESH_MS) });
   }
   return ran;
 }
 
+// Failed catalogue reads in a row since the last good one, and the newest
+// failure's code.
+async function failuresInARow(db, organisationId) {
+  const { rows } = await db.execute(sql`
+    select count(*)::int as failures,
+      (array_agg(error_code order by started_at desc))[1] as last_code
+    from xero_sync_runs
+    where organisation_id = ${organisationId} and status = 'failed'
+      and started_at > coalesce((select max(started_at) from xero_sync_runs
+        where organisation_id = ${organisationId} and status = 'succeeded'), 'epoch')`);
+  return { failures: rows[0]?.failures ?? 0, lastCode: rows[0]?.last_code ?? null };
+}
+
+// The wait after `failures` failed reads in a row: an hour, doubling, at most
+// a day (issue #111: never every hour for ever).
+export function catalogueRetryMs(failures) {
+  return Math.min(CATALOGUE_EVERY_MS, BUDGET_WAIT_MS * 2 ** Math.max(0, failures - 1));
+}
+
 // Reads the contacts and items of each connected organisation whose last good
-// read is older than a day. A failure is logged and tried again next hour.
+// read is older than a day. A failed read waits longer each time (above). A
+// failure is reported once with log.error; the same failure again is a
+// warning. While the call guard stops Xero calls, no read is tried.
 export async function refreshStaleCatalogues(db, runtime, { now = Date.now, log = console } = {}) {
-  const { rows } = await db.execute(sql`select organisation_id from xero_connections where mode = ${runtime.settings.mode}`);
-  for (const { organisation_id: organisationId } of rows) {
+  const { rows } = await db.execute(sql`select organisation_id, tenant_id from xero_connections where mode = ${runtime.settings.mode}`);
+  for (const { organisation_id: organisationId, tenant_id: tenantId } of rows) {
     const last = await lastSync(db, organisationId);
     const at = last?.finishedAt ?? last?.startedAt;
-    if (last && at && Number(now()) - new Date(at) < (last.status === 'succeeded' ? CATALOGUE_EVERY_MS : BUDGET_WAIT_MS)) continue;
+    const { failures, lastCode } = last?.status === 'failed' ? await failuresInARow(db, organisationId) : { failures: 0, lastCode: null };
+    if (last && at && Number(now()) - new Date(at) < (last.status === 'succeeded' ? CATALOGUE_EVERY_MS : catalogueRetryMs(failures))) continue;
+    try {
+      await runtime.guardFor(db).check(tenantId);
+    } catch (error) {
+      if (isCallsStopped(error)) continue;
+      throw error;
+    }
     try {
       const run = await syncCatalogue(db, runtime, organisationId);
       log.info?.(`[xero] contacts and items read for organisation ${organisationId}: ${run.contactCount} contacts, ${run.itemCount} items`);
     } catch (error) {
-      log.error?.(`[xero] reading contacts and items for organisation ${organisationId} failed: ${error?.code ?? 'error'}`);
+      const code = error?.code ?? 'error';
+      const line = `[xero] reading contacts and items for organisation ${organisationId} failed: ${code}; next try in ${Math.round(catalogueRetryMs(failures + 1) / 60_000)} minutes`;
+      // The guard reported a stop already; a repeat of the same failure is a warning.
+      if (isCallsStopped(error) || (failures > 0 && code === lastCode)) log.warn?.(line);
+      else log.error?.(line);
+    }
+  }
+}
+
+// Keeps a read queued for each connected organisation. A read that gave up
+// (dead) waits for a person, a restart or the next day (issue #101), and
+// while the call guard stops Xero calls no read is queued.
+export async function keepReadsQueued(db, runtime, { startedAtMs = Date.now(), now = Date.now } = {}) {
+  const { rows } = await db.execute(sql`select organisation_id, tenant_id from xero_connections where mode = ${runtime.settings.mode}`);
+  for (const { organisation_id: organisationId, tenant_id: tenantId } of rows) {
+    if (await deadSince(db, organisationId, { kind: IMPORT_KIND, dedupeKey: IMPORT_KEY, since: deadHoldSince(startedAtMs, Number(now())) })) continue;
+    try {
+      await runtime.guardFor(db).check(tenantId);
+    } catch (error) {
+      if (isCallsStopped(error)) continue;
+      throw error;
+    }
+    await queueChangesRead(db, organisationId);
+  }
+}
+
+// Reports a copy that went stale once with log.error, and its recovery with
+// log.info. `stale` is the set of organisations already reported.
+export async function reportStaleCopies(db, runtime, { stale = new Set(), now = Date.now, log = console } = {}) {
+  const { rows } = await db.execute(sql`select organisation_id from xero_connections where mode = ${runtime.settings.mode}`);
+  for (const { organisation_id: organisationId } of rows) {
+    const state = await mirrorState(db, organisationId, { now: new Date(Number(now())) });
+    if (!state.complete) continue;
+    if (!state.fresh && !stale.has(organisationId)) {
+      stale.add(organisationId);
+      log.error?.(`[xero] the copy of Xero for organisation ${organisationId} is out of date (last full read ${state.lastPassAt?.toISOString() ?? 'never'}); drafts by rule wait until it is read again`);
+    } else if (state.fresh && stale.delete(organisationId)) {
+      log.info?.(`[xero] the copy of Xero for organisation ${organisationId} is up to date again`);
     }
   }
+  return stale;
 }
 
 // The background worker: runs due slices one at a time, then waits. Started
 // by the adapter outside replay mode; stop() waits for a slice in flight.
 export function createImportWorker({ db, runtime, log = console, timers = { setTimeout, clearTimeout }, firstDelayMs = 10_000 }) {
   const workerId = `xero-import-${randomUUID()}`;
+  const startedAtMs = Date.now();
+  const stale = new Set();
   let timer = null;
   let running = null;
   let stopped = true;
@@ -105,12 +209,14 @@ export function createImportWorker({ db, runtime, log = console, timers = { setT
     running = (async () => {
       try {
         await refreshStaleCatalogues(db, runtime, { log });
+        await keepReadsQueued(db, runtime, { startedAtMs });
+        await reportStaleCopies(db, runtime, { stale, log });
         const ran = await runImportOnce(db, runtime, { workerId });
         if (ran) {
           busy = true;
           const read = (ran.job.result?.results ?? []).map((r) => `${r.resource} ${r.read}`).join(', ');
-          if (ran.outcome === 'dead') log.error?.('[xero] the history import gave up after its last attempt');
-          log.info?.(`[xero] import ${ran.outcome} for organisation ${ran.job.organisationId}${read ? `: ${read}` : ''}${ran.job.result?.more ? `; more (${ran.job.result.more})` : ''}`);
+          if (ran.outcome === 'dead') log.error?.('[xero] reading Xero gave up after its last attempt');
+          log.info?.(`[xero] read ${ran.outcome} for organisation ${ran.job.organisationId}${read ? `: ${read}` : ''}${ran.job.result?.more ? `; more (${ran.job.result.more})` : ''}`);
         }
       } catch (error) {
         log.error?.(`[xero] import worker: ${error?.code ?? 'error'}: ${error?.message ?? error}`);
@@ -127,6 +233,8 @@ export function createImportWorker({ db, runtime, log = console, timers = { setT
       for (const organisationId of await organisationsToImport(db, runtime.settings.mode)) {
         await queueHistoryImport(db, organisationId, { reason: 'start' });
       }
+      // A finished copy reads its changes again from the first tick on
+      // (keepReadsQueued), so an upgrade or a restart needs no step.
       schedule(firstDelayMs);
     },
     async stop() {

package/server/integrations/xero/index.js

@@ -1,19 +1,20 @@
 import { fileURLToPath } from 'node:url';
 import { sql } from 'drizzle-orm';
-import { checkDrafts, pushInvoice, pushInvoices } from './drafts.js';
+import { guardAlerts } from '../call-guard.js';
+import { checkDrafts, documentFacts, pushInvoice, pushInvoices } from './drafts.js';
 import { readConnection } from './connections.js';
 import { createImportWorker } from './import.js';
 import { readPayments, xeroLiveCheck } from './ledger.js';
-import { findInvoices, listCustomers } from './lookup.js';
+import { findInvoices, listCustomers, listPriceItems, mirrorState } from './lookup.js';
 import { createXeroRouter } from './routes.js';
-import { createXeroRuntime, requireXeroSettings } from './runtime.js';
+import { createXeroRuntime, requireXeroSettings, XERO_CALL_GUARD } from './runtime.js';
 import { writesAllowed } from './settings.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']);
+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']);
 
 // What an owner enters in Settings, Integrations (server/integrations/setup.js).
 // The refresh token's key comes from Flow's secrets key.
@@ -61,10 +62,16 @@ export function createXeroAdapter({ runtime: given = null } = {}) {
       tables: [...XERO_TABLES],
     },
     setup: XERO_SETUP,
-    async start({ db, log, env }) {
+    // Every Xero call goes through this call guard (docs/INTEGRATIONS.md,
+    // "Outbound calls").
+    callGuard: XERO_CALL_GUARD,
+    // `reconfigured` is true when a person saved the settings or turned Xero
+    // on: that clears a halt, stopped resources and an open circuit.
+    async start({ db, log, env, reconfigured = false }) {
       database = db;
       if (!given) runtime = createXeroRuntime({ settings: requireXeroSettings(env ?? process.env) });
       const { settings } = current();
+      if (reconfigured) await current().guardFor(db).resume();
       log.info?.(`[xero] mode ${settings.mode}; writes ${writesAllowed(settings) ? 'on' : 'off (XERO_ALLOW_LIVE_WRITES)'}; redirect URI ${settings.redirectUri ?? 'not set (FLOW_PUBLIC_ORIGIN)'}`);
       // The history import (import.js) runs in the background outside replay
       // mode. Replay tests run its slices directly.
@@ -81,8 +88,25 @@ export function createXeroAdapter({ runtime: given = null } = {}) {
     capabilities: {
       async health() {
         const { settings } = current();
-        const { rows } = await database.execute(sql`select count(*)::int as connected from xero_connections where mode = ${settings.mode}`);
-        return { ok: true, mode: settings.mode, writesAllowed: writesAllowed(settings), connected: rows[0].connected };
+        const { rows } = await database.execute(sql`select organisation_id, tenant_id from xero_connections where mode = ${settings.mode}`);
+        const guard = current().guardFor(database);
+        const calls = await Promise.all(rows.map(async (r) => ({ tenantId: r.tenant_id, ...await guard.status(r.tenant_id) })));
+        const stopped = calls.some((c) => c.circuit !== 'closed' || c.stoppedResources.length || c.failedToday >= c.dailyFailureBudget);
+        // How fresh each copy of Xero is (lookup.js): a complete copy that is
+        // not fresh stops drafts by rule (issue #131).
+        const copies = await Promise.all(rows.map(async (r) => {
+          const { complete, fresh, lastPassAt } = await mirrorState(database, r.organisation_id);
+          return { tenantId: r.tenant_id, complete, fresh, lastPassAt };
+        }));
+        const stale = copies.some((c) => c.complete && !c.fresh);
+        return { ok: !stopped && !stale, mode: settings.mode, writesAllowed: writesAllowed(settings), connected: rows.length, calls, copies };
+      },
+      // What only a person can clear, for the Integrations page
+      // (server/core/alerts.js): a refused connection stops calls.
+      async alerts({ organisationId }) {
+        const connection = await readConnection(database, organisationId);
+        if (!connection || connection.mode !== current().settings.mode) return [];
+        return guardAlerts('Xero', await current().guardFor(database).status(connection.tenantId));
       },
       // One issued invoice to a Xero draft (drafts.js). The Flow invoice id
       // and version are the idempotency key.
@@ -96,6 +120,9 @@ export function createXeroAdapter({ runtime: given = null } = {}) {
         const connection = await readConnection(database, organisationId);
         return { connected: Boolean(connection && connection.mode === settings.mode), writesAllowed: writesAllowed(settings) };
       },
+      // What the customer's Xero copy of a Flow invoice version says, from
+      // Flow's copy of Xero (drafts.js; no calls). The invoice PDF uses it.
+      documentFacts: ({ organisationId, invoiceId, version = null }) => documentFacts(database, current(), { organisationId, invoiceId, version }),
       // Sales invoice payments changed since `since` (ledger.js). The answer's
       // cursor is the next `since`.
       pullPayments: ({ organisationId, since }) => readPayments(database, current(), organisationId, { since: new Date(since) }),
@@ -106,6 +133,8 @@ export function createXeroAdapter({ runtime: given = null } = {}) {
       listCustomers: ({ organisationId }) => listCustomers(database, organisationId),
       // Sales invoices from the mirror, with the mirror's state (lookup.js).
       findInvoices: ({ organisationId, ...query }) => findInvoices(database, organisationId, query),
+      // Xero items, from Flow's copy, for the price list (lookup.js).
+      listPriceItems: ({ organisationId }) => listPriceItems(database, organisationId, { taxTypes: current().settings.taxTypes }),
     },
     routes: ({ db, personAuth, log, messagePage }) => createXeroRouter({ db, personAuth, runtime: current(), log, messagePage }),
   };

package/server/integrations/xero/lookup.js

@@ -22,6 +22,32 @@ export async function listCustomers(db, organisationId) {
   return rows.map((r) => ({ id: r.xero_contact_id, name: r.name }));
 }
 
+// Xero's items, from Flow's copy (catalogue.js, read on each sync), for the
+// price list's links and price check (server/core/price-list.js). A tax type
+// that charges GST reads as GST; any other set type reads as GST free.
+const GST_TAX_TYPES = new Set(['OUTPUT', 'OUTPUT2']);
+export async function listPriceItems(db, organisationId, { taxTypes = {} } = {}) {
+  const { rows } = await db.execute(sql`
+    select xero_item_id, code, name, description, is_sold, sales_unit_amount_cents, sales_tax_type, synced_at
+    from xero_items where organisation_id = ${organisationId} order by code`);
+  const taxOf = (type) => {
+    if (!type) return null;
+    return type === taxTypes.GST || GST_TAX_TYPES.has(type) ? 'GST' : 'GST_FREE';
+  };
+  return {
+    kind: 'accounting',
+    syncedAt: rows.reduce((at, r) => (!at || r.synced_at > at ? r.synced_at : at), null),
+    items: rows.map((r) => ({
+      id: r.xero_item_id,
+      code: r.code,
+      name: r.name || r.description || r.code,
+      unitAmountCents: r.sales_unit_amount_cents,
+      taxCode: taxOf(r.sales_tax_type),
+      sold: r.is_sold,
+    })),
+  };
+}
+
 // Whether the mirror holds the whole history and was read lately. Until then a
 // search that finds nothing proves nothing.
 export async function mirrorState(db, organisationId, { now = new Date() } = {}) {

package/server/integrations/xero/migrations/0006_xero_call_guard.sql

@@ -0,0 +1,26 @@
+-- The call guard's state and telemetry (server/integrations/call-guard.js,
+-- issue 111): one row per Xero organisation (tenant) with the circuit, a halt
+-- and the resources Xero refused, and one row per call sent. A call row keeps
+-- the resource and path, never the host, the query, a token or a response.
+CREATE TABLE IF NOT EXISTS "xero_call_guard" (
+	"key" text PRIMARY KEY NOT NULL,
+	"circuit_open_until" timestamp with time zone DEFAULT 'epoch' NOT NULL,
+	"circuit_opens" integer DEFAULT 0 NOT NULL,
+	"halted_reason" text,
+	"halted_at" timestamp with time zone,
+	"stopped_resources" jsonb DEFAULT '{}'::jsonb NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE IF NOT EXISTS "xero_calls" (
+	"id" bigserial PRIMARY KEY NOT NULL,
+	"key" text NOT NULL,
+	"at" timestamp with time zone NOT NULL,
+	"resource" text,
+	"request_path" text,
+	"status_code" integer,
+	"failure_kind" text,
+	"duration_ms" integer
+);
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "xero_calls_window" ON "xero_calls" USING btree ("key","at");

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

@@ -43,6 +43,13 @@
       "when": 1792406000000,
       "tag": "0005_xero_send_modes",
       "breakpoints": true
+    },
+    {
+      "idx": 6,
+      "version": "7",
+      "when": 1792490000000,
+      "tag": "0006_xero_call_guard",
+      "breakpoints": true
     }
   ]
 }

package/server/integrations/xero/mirror.js

@@ -1,5 +1,6 @@
 import { createHash } from 'node:crypto';
 import { sql } from 'drizzle-orm';
+import { isCallsStopped } from '../call-guard.js';
 import { parseXeroDate } from './catalogue.js';
 import { withXeroLane } from './governor.js';
 
@@ -257,12 +258,20 @@ export async function mirrorResource(db, runtime, organisationId, resource, { ma
 }
 
 // Reads each resource in turn, one organisation at a time with any other Xero
-// work for it (runtime.serial).
+// work for it (runtime.serial). A resource Xero refused (the call guard
+// stopped it: the connection lacks its scope) is skipped as `refused`, so
+// the others still read.
 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 });
+      let result;
+      try {
+        result = await mirrorResource(db, runtime, organisationId, resource, { maxPages });
+      } catch (error) {
+        if (!isCallsStopped(error) || error.reason !== 'resource_stopped') throw error;
+        result = { resource, pages: 0, read: 0, inserted: 0, changed: 0, unchanged: 0, stopped: 'refused' };
+      }
       results.push(result);
       if (result.stopped === 'budget') break;
     }

package/server/integrations/xero/oauth.js

@@ -53,7 +53,10 @@ async function tokenRequest(settings, fetchImpl, form, what) {
     if (body?.error === 'invalid_grant') {
       throw xeroError('xero_reconnect_needed', 'Xero no longer accepts this connection. An owner must connect Xero again.', { status: 409 });
     }
-    throw xeroError('xero_token_failed', `Xero refused ${what} (${response.status}${body?.error ? `, ${body.error}` : ''}).`, { status: 502 });
+    throw xeroError('xero_token_failed', `Xero refused ${what} (${response.status}${body?.error ? `, ${body.error}` : ''}).`, {
+      status: 502,
+      oauthError: typeof body?.error === 'string' ? body.error.slice(0, 40) : null,
+    });
   }
   if (!body?.access_token || !body?.refresh_token) {
     throw xeroError('xero_token_failed', `Xero's answer to ${what} had no tokens.`, { status: 502 });

package/server/integrations/xero/reconcile.js

@@ -0,0 +1,173 @@
+import { sql } from 'drizzle-orm';
+import { openReview, resolveReviewFor } from '../../core/review.js';
+
+// Each invoice Flow sent, against Flow's copy of Xero (issue #132). People
+// change invoices in both places after Flow sends them: a Xero draft is edited
+// before approval, an invoice is voided in Xero, or voided in Flow. The issued
+// version Flow sent is the merge base: the document both sides agreed on.
+// This module compares the Xero copy with it and with the Flow invoice now.
+// It never calls Xero and never writes to Xero or to the Flow invoice: a
+// difference opens one review item (alert only), and a person fixes it where
+// they choose. The item closes when a later check finds no difference.
+
+export const OUT_OF_SYNC = 'invoice.accounting_differs';
+export const ACTOR = 'system:xero-reconcile';
+
+// Xero's status in the words the Flow screens show.
+const LABELS = {
+  not_sent: 'Not in Xero',
+  sending: 'Sending to Xero',
+  not_copied: 'Sent, not read back yet',
+  draft: 'Draft in Xero',
+  approved: 'Approved in Xero',
+  part_paid: 'Part paid in Xero',
+  paid: 'Paid in Xero',
+  voided: 'Voided in Xero',
+  deleted: 'Deleted in Xero',
+};
+
+const GONE = new Set(['VOIDED', 'DELETED']);
+
+function xeroState(row) {
+  switch (row.status) {
+    case 'DRAFT':
+    case 'SUBMITTED':
+      return 'draft';
+    case 'AUTHORISED':
+      return Number(row.amount_paid_cents ?? 0) > 0 ? 'part_paid' : 'approved';
+    case 'PAID':
+      return 'paid';
+    case 'VOIDED':
+      return 'voided';
+    case 'DELETED':
+      return 'deleted';
+    default:
+      return 'draft';
+  }
+}
+
+const num = (value) => (value === null || value === undefined ? null : Number(value));
+const day = (value) => (value instanceof Date ? value.toISOString().slice(0, 10) : value ? String(value).slice(0, 10) : null);
+const codes = (lines) => [...(lines ?? []).map((l) => l.itemCode ?? '')].sort().join(',');
+
+// What differs between the Xero copy and the version Flow sent. Free text
+// (reference, descriptions) is not compared: the copy keeps it only when the
+// lab turns that on (XERO_KEEP_REFERENCE).
+export function sentDifferences(sent, document, copy) {
+  const found = [];
+  const add = (field, flow, xero) => found.push({ field, flow, xero });
+  if (sent?.Contact?.ContactID && copy.xero_contact_id !== sent.Contact.ContactID) add('contact', sent.Contact.ContactID, copy.xero_contact_id);
+  if (num(copy.subtotal_cents) !== document.subtotalCents) add('subtotal', document.subtotalCents, num(copy.subtotal_cents));
+  if (num(copy.tax_cents) !== document.taxCents) add('tax', document.taxCents, num(copy.tax_cents));
+  if (num(copy.total_cents) !== document.totalCents) add('total', document.totalCents, num(copy.total_cents));
+  const lines = copy.lines ?? [];
+  if (lines.length !== document.lines.length) add('line count', document.lines.length, lines.length);
+  else if (codes(lines) !== codes(document.lines)) add('items', codes(document.lines), codes(lines));
+  if (sent?.Date && day(copy.issued_on) !== sent.Date) add('date', sent.Date, day(copy.issued_on));
+  return found;
+}
+
+// The finding for one invoice, or null when Flow and Xero agree.
+//   differs         Xero's copy no longer matches the version Flow sent
+//   voided_in_xero  Xero voided or deleted it; the Flow invoice is still issued
+//   voided_in_flow  Flow voided it; Xero's invoice is still live
+function findingFor(status) {
+  if (!status.xero) return null;
+  const live = !GONE.has(status.xero.status);
+  if (status.flowStatus === 'void' && live) return 'voided_in_flow';
+  if (status.flowStatus === 'issued' && status.current && !live) return 'voided_in_xero';
+  if (live && status.differences.length) return 'differs';
+  return null;
+}
+
+const MESSAGES = {
+  differs: 'Xero no longer matches the invoice Flow sent.',
+  voided_in_xero: 'Xero voided or deleted this invoice. It is still issued in Flow.',
+  voided_in_flow: 'This invoice is void in Flow. Xero still holds it as a live invoice.',
+};
+
+// Each invoice's Xero status, from Flow's copy (no Xero calls). Answers a map
+// from Flow invoice id to { state, label, xero, differences, finding, message }.
+export async function accountingStatus(db, runtime, organisationId, invoiceIds = null) {
+  const only = invoiceIds ? sql`and i.id = any(${sql.param([...new Set(invoiceIds.map(String))])}::uuid[])` : sql``;
+  // Without ids: only invoices Flow sent, for the check after each read.
+  const sentOnly = invoiceIds ? sql`` : sql`and p.id is not null`;
+  const { rows } = await db.execute(sql`
+    select i.id, i.status, i.issued_version, i.total_cents,
+      p.version as sent_version, p.state as push_state, p.request_body, p.xero_invoice_id, p.xero_invoice_number,
+      v.document,
+      x.status as x_status, x.invoice_number as x_number, x.xero_contact_id, x.subtotal_cents, x.tax_cents,
+      x.total_cents as x_total_cents, x.amount_paid_cents, x.amount_due_cents, x.lines, x.issued_on
+    from invoices i
+    left join lateral (
+      select * from xero_invoice_pushes
+      where organisation_id = i.organisation_id and invoice_id = i.id
+      order by version desc limit 1
+    ) p on true
+    left join invoice_versions v on v.invoice_id = i.id and v.version = p.version
+    left join xero_invoices x on x.organisation_id = i.organisation_id and x.xero_invoice_id = p.xero_invoice_id
+    where i.organisation_id = ${organisationId} ${only} ${sentOnly}`);
+  const web = runtime.settings.endpoints?.web ?? 'https://go.xero.com';
+  const out = new Map();
+  for (const r of rows) {
+    let state;
+    if (!r.push_state) state = 'not_sent';
+    else if (['dispatching', 'ambiguous'].includes(r.push_state)) state = 'sending';
+    else if (!r.x_status) state = 'not_copied';
+    else state = xeroState({ status: r.x_status, amount_paid_cents: r.amount_paid_cents });
+    let sent = null;
+    try {
+      sent = r.request_body ? JSON.parse(r.request_body) : null;
+    } catch {
+      sent = null;
+    }
+    const xero = r.x_status ? {
+      invoiceId: r.xero_invoice_id,
+      number: r.x_number ?? r.xero_invoice_number ?? null,
+      status: r.x_status,
+      totalCents: num(r.x_total_cents),
+      amountDueCents: num(r.amount_due_cents),
+      url: `${web}/AccountsReceivable/View.aspx?InvoiceID=${encodeURIComponent(r.xero_invoice_id)}`,
+    } : null;
+    const status = {
+      invoiceId: r.id,
+      flowStatus: r.status,
+      sentVersion: r.sent_version ?? null,
+      current: r.sent_version !== null && r.sent_version === r.issued_version,
+      state,
+      label: LABELS[state],
+      xero,
+      differences: xero && r.document && !GONE.has(r.x_status) ? sentDifferences(sent, r.document, { ...r, total_cents: r.x_total_cents }) : [],
+      flowTotalCents: num(r.total_cents),
+    };
+    status.finding = findingFor(status);
+    status.message = status.finding ? MESSAGES[status.finding] : null;
+    out.set(r.id, status);
+  }
+  return out;
+}
+
+// Opens or refreshes one review item for each finding, and closes the item of
+// an invoice whose finding went away. Answers counts.
+export async function checkSentInvoices(db, runtime, organisationId, { invoiceIds = null } = {}) {
+  const statuses = await accountingStatus(db, runtime, organisationId, invoiceIds);
+  const result = { checked: 0, open: 0, closed: 0 };
+  for (const status of statuses.values()) {
+    if (status.state === 'not_sent') continue;
+    result.checked += 1;
+    if (status.finding) {
+      await openReview(db, organisationId, {
+        kind: OUT_OF_SYNC,
+        entity: 'invoice',
+        flowId: status.invoiceId,
+        systems: ['flow', 'xero'],
+        evidence: { finding: status.finding, message: status.message, flowStatus: status.flowStatus, sentVersion: status.sentVersion, xero: status.xero, differences: status.differences },
+        moneyAtRiskCents: Math.abs(status.xero?.totalCents ?? status.flowTotalCents ?? 0),
+      });
+      result.open += 1;
+    } else if (await resolveReviewFor(db, organisationId, { kind: OUT_OF_SYNC, entity: 'invoice', flowId: status.invoiceId, resolution: 'no_difference', actor: ACTOR })) {
+      result.closed += 1;
+    }
+  }
+  return result;
+}