@arcforgelabs/flow 2026.10.29 → 2026.10.32-beta.1

package/server/integrations/xero/drafts.js

@@ -1,5 +1,6 @@
 import { createHash } from 'node:crypto';
 import { and, eq, inArray, sql } from 'drizzle-orm';
+import { isCallsStopped } from '../call-guard.js';
 import { getInvoice, listInvoiceVersions } from '../../core/invoices.js';
 import { sendModeFor } from '../../core/invoicing-rules.js';
 import { contacts as flowContacts, invoices as flowInvoices, priceItems } from '../../db/schema.js';
@@ -206,6 +207,38 @@ export async function listPushes(db, organisationId, invoiceId) {
   return rows.map(mapPush);
 }
 
+// What the customer's Xero copy of one Flow invoice version says, from Flow's
+// copy of Xero (no calls): the stored push, and the mirror row when the
+// mirror has it. Before the version is in Xero, only who numbers it and the
+// default due days are known.
+export async function documentFacts(db, runtime, { organisationId, invoiceId, version = null }) {
+  const { settings } = runtime;
+  const facts = { system: 'Xero', sent: false, numberedBy: settings.invoiceNumber, defaultDueDays: settings.defaultDueDays };
+  if (!version) return facts;
+  const { rows: [push] } = await db.execute(sql`select xero_invoice_id, xero_invoice_number, xero_status, request_body
+    from xero_invoice_pushes
+    where organisation_id = ${organisationId} and invoice_id = ${invoiceId} and version = ${version} and xero_invoice_id is not null`);
+  if (!push) return facts;
+  const { rows: [copy] } = await db.execute(sql`select invoice_number, reference, status,
+      to_char(issued_on, 'YYYY-MM-DD') as issued_on, to_char(due_on, 'YYYY-MM-DD') as due_on
+    from xero_invoices where organisation_id = ${organisationId} and xero_invoice_id = ${push.xero_invoice_id}`);
+  let sent = {};
+  try {
+    sent = JSON.parse(push.request_body) ?? {};
+  } catch {
+    // An unreadable body leaves only the mirror and the push's own columns.
+  }
+  return {
+    ...facts,
+    sent: true,
+    number: copy?.invoice_number || push.xero_invoice_number || sent.InvoiceNumber || null,
+    reference: copy?.reference || sent.Reference || null,
+    issueDate: copy?.issued_on || sent.Date || null,
+    dueDate: copy?.due_on || sent.DueDate || null,
+    status: copy?.status || push.xero_status || null,
+  };
+}
+
 async function settle(db, id, fields) {
   const { rows } = await db.execute(sql`update xero_invoice_pushes set
       state = ${fields.state},
@@ -313,7 +346,7 @@ export async function pushDrafts(db, runtime, organisationId, invoiceIds, { push
       try {
         results.push(await pushOne(db, runtime, client, organisationId, invoiceId, { pushedBy, allowExisting: allowed.has(invoiceId) }));
       } catch (error) {
-        if (error.code === 'xero_rate_limited' || error.code === 'xero_reconnect_needed') {
+        if (stopsTheBatch(error)) {
           // Every later invoice would fail the same way: stop and say so.
           results.push(failed(invoiceId, error));
           for (const rest of invoiceIds.slice(invoiceIds.indexOf(invoiceId) + 1)) results.push(failed(rest, error, 'not_tried'));
@@ -392,9 +425,13 @@ async function assertTracking(client, tracking) {
   }
 }
 
-// Xero errors that prove no invoice was made: Xero refused the request.
+// Errors after which every later call would fail the same way: stop the batch.
+const stopsTheBatch = (error) => error.code === 'xero_rate_limited' || error.code === 'xero_reconnect_needed' || isCallsStopped(error);
+
+// Xero errors that prove no invoice was made: Xero refused the request, or
+// the call guard stopped it before it went.
 function provesNothingCreated(error) {
-  return error.code === 'xero_validation_failed' || error.code === 'xero_rate_limited'
+  return isCallsStopped(error) || error.code === 'xero_validation_failed' || error.code === 'xero_rate_limited'
     || error.code === 'xero_unauthorized' || error.code === 'xero_reconnect_needed'
     || (error.code === 'xero_api_error' && error.status >= 400 && error.status < 500);
 }
@@ -509,7 +546,7 @@ async function dispatch(db, client, push, document, { fresh = false } = {}) {
       throw error;
     }
     await settle(db, push.id, { state: 'ambiguous', errorCode: error.code ?? 'xero_uncertain', errorMessage: error.message });
-    if (error.code === 'xero_rate_limited' || error.code === 'xero_reconnect_needed') throw error;
+    if (stopsTheBatch(error)) throw error;
     return {
       invoiceId: push.invoiceId,
       version: push.version,
@@ -555,8 +592,9 @@ async function verify(db, client, push, draft, document, created, outcome) {
 // ---------------------------------------------------------------------------
 // Email
 
-// Xero errors that prove it sent no email: it refused the request.
-const emailRefused = (error) => error.code === 'xero_validation_failed'
+// Xero errors that prove it sent no email: it refused the request, or the
+// call guard stopped it before it went.
+const emailRefused = (error) => isCallsStopped(error) || error.code === 'xero_validation_failed'
   || (error.code === 'xero_api_error' && error.status >= 400 && error.status < 500);
 
 // Asks Xero to email an approved invoice that Flow sent and checked, once.
@@ -576,7 +614,7 @@ async function emailIfDue(db, client, push) {
       ? `Xero did not email the invoice: ${error.message}`
       : 'Flow does not know whether Xero emailed the invoice. Check the invoice in Xero before you send it again.';
     await db.execute(sql`update xero_invoice_pushes set email_state = ${state}, email_error = ${message}, updated_at = now() where id = ${push.id}`);
-    if (error.code === 'xero_rate_limited' || error.code === 'xero_reconnect_needed') throw error;
+    if (stopsTheBatch(error)) throw error;
     return { state, error: message, at: null };
   }
   const { rows: [done] } = await db.execute(sql`update xero_invoice_pushes set email_state = 'sent', email_error = null, emailed_at = now(), updated_at = now()
@@ -613,7 +651,7 @@ async function resume(db, runtime, client, push, document) {
       .filter((inv) => !GONE.has(inv.Status) && !push.preExistingIds.includes(inv.InvoiceID)
         && differences(inv, draft, document).filter((d) => d !== 'date').length === 0);
   } catch (error) {
-    if (error.code === 'xero_rate_limited') throw error;
+    if (error.code === 'xero_rate_limited' || isCallsStopped(error)) throw error;
     return { invoiceId: push.invoiceId, version: push.version, outcome: 'ambiguous', error: { code: 'xero_outcome_unknown', message: 'Flow could not look in Xero to settle an earlier attempt. Send again later.' } };
   }
   if (candidates.length === 1) return verify(db, client, push, draft, document, candidates[0], 'reconciled');

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,11 +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(', ');
-          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}`);
@@ -126,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 });