@arcforgelabs/flow 2026.10.30 → 2026.10.32

package/server/integrations/xero/import.js

@@ -1,14 +1,22 @@
 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';
+import { runWebhookWork, WEBHOOK_REFRESH_MS, webhooksActive } from './webhooks.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). While
+// Xero's webhooks arrive (webhooks.js), it waits WEBHOOK_REFRESH_MS instead.
+// It only reads from Xero.
 
 export const IMPORT_KIND = 'xero.import';
 const IMPORT_KEY = 'history';
@@ -18,6 +26,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 +56,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 +94,109 @@ 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.
+    // While Xero's webhooks arrive, the poll is only the safety net (issue #45).
+    const every = await webhooksActive(db, runtime, ran.job.organisationId, { now: Number(now()) }) ? WEBHOOK_REFRESH_MS : REFRESH_MS;
+    await queueChangesRead(db, ran.job.organisationId, { runAfter: new Date(Number(now()) + every) });
   }
   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();
+  const holds = new Map();
   let timer = null;
   let running = null;
   let stopped = true;
@@ -105,12 +214,15 @@ 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 });
+        await runWebhookWork(db, runtime, { log, holds });
         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 +239,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', '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.
@@ -28,6 +29,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: [
@@ -37,6 +39,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'],
 };
@@ -61,10 +64,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 +90,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 +122,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 +135,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/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

@@ -43,6 +43,20 @@
       "when": 1792406000000,
       "tag": "0005_xero_send_modes",
       "breakpoints": true
+    },
+    {
+      "idx": 6,
+      "version": "7",
+      "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

@@ -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';
 
@@ -181,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`);
@@ -212,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 () => {
@@ -232,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,
@@ -257,12 +266,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 });