@arcforgelabs/flow 2026.10.30 → 2026.10.32

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;
+}

package/server/integrations/xero/routes.js

@@ -8,9 +8,11 @@ import { describePush, listPushes, MAX_BATCH, previewDrafts, pushDrafts } from '
 import { recordXeroEvidence, recordXeroPayments } from './ledger.js';
 import { queueHistoryImport, resetImport } from './import.js';
 import { MIRROR_RESOURCES, mirrorStatus, mirrorXero } from './mirror.js';
+import { accountingStatus, checkSentInvoices } from './reconcile.js';
 import { decryptToken, deleteConnection, describeConnection, readConnection, saveConnection } from './connections.js';
 import { authorizeUrl, exchangeCode, fetchConnections, revokeToken, selectConnection } from './oauth.js';
 import { writesAllowed } from './settings.js';
+import { saveEvents, signatureValid } from './webhooks.js';
 import { DEFAULT_FAMILY } from '../../theme/themes.js';
 import { messagePage as themedMessagePage } from '../../ui/page.js';
 
@@ -27,12 +29,18 @@ import { messagePage as themedMessagePage } from '../../ui/page.js';
 //                                  would make, and what stops them (no Xero calls)
 //   POST /invoices/push            owner or admin: issued invoices to Xero drafts
 //   GET  /invoices/:invoiceId/pushes?organisationId=   any signed-in person
+//   POST /invoices/status          any signed-in person: each invoice's Xero
+//                                  status and any difference, from the copy
+//   POST /invoices/:invoiceId/recheck   owner or admin: reads Xero's changes,
+//                                  then checks that one invoice again (Mark resolved)
 //   POST /obligations/:obligationId/check   owner or admin: Xero's invoice for
 //                                  a billable job, recorded on the ledger
 //   POST /payments/sync            owner or admin: Xero payments to the ledger
 //   POST /mirror                   owner or admin: copies Xero invoices, credit
 //                                  notes and payments changed since the last copy
 //   GET  /mirror?organisationId=   any signed-in person: what the copy holds
+//   POST /webhooks                 Xero: change events, signed with the
+//                                  webhook key (XERO_WEBHOOK_KEY); no session
 //
 // Only an owner, with a verified owner sign-in, can connect or disconnect.
 // The callback carries no Flow session: the one-use state from /connect,
@@ -76,10 +84,35 @@ export const handle = (log, fn) => async (req, res) => {
 
 // `messagePage` draws the callback's answer in the installation's design
 // system (server/ui/page.js); the server's app passes it.
+// What the Xero page says about calls for one connection: stopped until a
+// person connects again (a refused connection or resource), and since when.
+export function callsState(status) {
+  const resources = status.stoppedResources.map((r) => r.resource);
+  const since = status.haltedAt ?? status.stoppedResources.map((r) => r.at).filter(Boolean).sort()[0] ?? null;
+  return { stopped: Boolean(status.haltedReason) || resources.length > 0, all: Boolean(status.haltedReason), resources, since };
+}
+
 export function createXeroRouter({ db, personAuth, runtime, log = console, messagePage = (options) => themedMessagePage({ ...options, defaultFamily: DEFAULT_FAMILY }) }) {
   const page = (title, text, tone) => messagePage({ title, text, tone });
   const { settings } = runtime;
   const router = express.Router();
+
+  // Xero's webhooks (webhooks.js), before the JSON parser: the signature
+  // covers the raw body. Xero wants 200 with no body within 5 seconds, and
+  // 401 for a bad signature (its "intent to receive" test sends both).
+  router.post('/webhooks', express.raw({ type: () => true, limit: '1mb' }), async (req, res) => {
+    if (!settings.webhookKey) return res.status(404).end();
+    const raw = Buffer.isBuffer(req.body) ? req.body : Buffer.alloc(0);
+    if (!signatureValid(settings.webhookKey, raw, req.get('x-xero-signature'))) return res.status(401).end();
+    try {
+      await saveEvents(db, runtime, JSON.parse(raw.toString('utf8') || '{}'));
+    } catch (error) {
+      log.error?.(`[xero] saving webhook events failed: ${error?.code ?? error?.name ?? 'error'}`);
+      return res.status(500).end();
+    }
+    return res.status(200).end();
+  });
+
   router.use(express.json({ limit: '256kb' }));
 
   // Sign-in off: nothing but the callback answers, and it fails for want of
@@ -101,6 +134,7 @@ export function createXeroRouter({ db, personAuth, runtime, log = console, messa
       connected: Boolean(connection && connection.mode === settings.mode),
       connection: describeConnection(connection),
       rateLimit: connection ? runtime.governor.status(connection.tenantId) : null,
+      calls: connection ? callsState(await runtime.guardFor(db).status(connection.tenantId)) : null,
       lastSync: await lastSync(db, organisationId),
     });
   }));
@@ -155,6 +189,8 @@ export function createXeroRouter({ db, personAuth, runtime, log = console, messa
         key: settings.tokenKey,
       });
       runtime.remember(entry.organisationId, tokens);
+      // A new connection is a person acting: calls stopped before resume.
+      await runtime.guardFor(db).resume();
       // Another Xero organisation starts its history from the beginning.
       if (previous && previous.tenantId !== connection.tenantId) await resetImport(db, entry.organisationId);
       await queueHistoryImport(db, entry.organisationId, { reason: 'connected' });
@@ -205,6 +241,25 @@ export function createXeroRouter({ db, personAuth, runtime, log = console, messa
     res.json({ ok: true, mode: settings.mode, writesAllowed: writesAllowed(settings), ...preview });
   }));
 
+  // Xero's status of each invoice, from Flow's copy: no Xero calls.
+  router.post('/invoices/status', ...signedIn, handle(log, async (req, res) => {
+    const organisationId = await requireOrganisation(db, req.body?.organisationId);
+    const statuses = await accountingStatus(db, runtime, organisationId, requireInvoiceIds(req.body?.invoiceIds));
+    res.json({ ok: true, invoices: [...statuses.values()] });
+  }));
+
+  // Mark resolved: read Xero's changes (a few calls, through the call guard),
+  // then check this one invoice again. The item closes only when the
+  // difference is gone; otherwise it stays open with the new evidence.
+  router.post('/invoices/:invoiceId/recheck', ...manager, handle(log, async (req, res) => {
+    const organisationId = await requireOrganisation(db, req.body?.organisationId);
+    const [invoiceId] = requireInvoiceIds([req.params.invoiceId], 'invoiceId');
+    await mirrorXero(db, runtime, organisationId, { resources: ['invoices'] });
+    const result = await checkSentInvoices(db, runtime, organisationId, { invoiceIds: [invoiceId] });
+    const status = (await accountingStatus(db, runtime, organisationId, [invoiceId])).get(invoiceId) ?? null;
+    res.json({ ok: true, resolved: !status?.finding, closed: result.closed, status });
+  }));
+
   router.post('/invoices/push', ...manager, handle(log, async (req, res) => {
     const organisationId = await requireOrganisation(db, req.body?.organisationId);
     const invoiceIds = requireInvoiceIds(req.body?.invoiceIds);

package/server/integrations/xero/runtime.js

@@ -1,3 +1,4 @@
+import { createCallGuard } from '../call-guard.js';
 import { createXeroClient, xeroError } from './client.js';
 import { decryptToken, readConnection, storeRotatedToken } from './connections.js';
 import { createGovernor } from './governor.js';
@@ -6,9 +7,21 @@ import { createReplayFetch, DEFAULT_REPLAY_FIXTURES, loadReplayFixtures } from '
 import { resolveXeroSettings, writesAllowed } from './settings.js';
 
 // The Xero adapter's state for one Flow process: settings, the rate-limit
-// governor, the transport (real fetch, or replay), OAuth states, and the
-// access tokens in memory. Access tokens live 30 minutes and are never
-// stored; the refresh token is stored sealed (connections.js).
+// governor, the call guard (its state is in PostgreSQL), the transport (real
+// fetch, or replay), OAuth states, and the access tokens in memory. Access
+// tokens live 30 minutes and are never stored; the refresh token is stored
+// sealed (connections.js).
+
+// The call guard's tables and policy (../call-guard.js, docs/XERO.md). A 401
+// or 403 that a fresh token does not clear stops only the resource it came
+// from: a connection can lack one scope (payments) and still serve the rest.
+// A refused token refresh halts every call.
+export const XERO_CALL_GUARD = Object.freeze({
+  integration: 'xero',
+  name: 'Xero',
+  tables: Object.freeze({ state: 'xero_call_guard', calls: 'xero_calls' }),
+  policy: Object.freeze({ authStops: 'resource' }),
+});
 
 export function requireXeroSettings(env = process.env) {
   const settings = resolveXeroSettings(env);
@@ -31,6 +44,14 @@ export function createXeroRuntime({ settings, fetch, now = Date.now, log = conso
   const accessTokens = new Map(); // organisation id -> { token, expiresAt }
   const refreshing = new Map(); // organisation id -> promise
   const queues = new Map(); // organisation id -> tail of its work queue
+  const guards = new WeakMap(); // database handle -> call guard
+
+  // The call guard for one database. Keyed by the Xero tenant id: Xero's
+  // limits are per organisation.
+  function guardFor(db) {
+    if (!guards.has(db)) guards.set(db, createCallGuard({ db, ...XERO_CALL_GUARD, now, log }));
+    return guards.get(db);
+  }
 
   // Runs heavy Xero work for one organisation one at a time, in order: a
   // sync and a batch of drafts draw on the same call budget, and running them
@@ -67,11 +88,29 @@ export function createXeroRuntime({ settings, fetch, now = Date.now, log = conso
 
   // Refresh under a row lock, and store the rotated refresh token in the same
   // transaction, so two refreshes never race and the newest token is kept.
+  // A refresh Xero refuses for good halts every call until an owner connects
+  // again or saves the settings; another failed refresh counts as a failed
+  // call.
   async function refresh(db, organisationId) {
+    const guard = guardFor(db);
     return db.transaction(async (tx) => {
       const connection = usable(await readConnection(tx, organisationId, { lock: true }));
+      await guard.check(connection.tenantId, { resource: 'token' });
       const refreshToken = decryptToken(connection.refreshTokenEnc, settings.tokenKey, organisationId);
-      const tokens = await refreshTokens(settings, transport, refreshToken);
+      let tokens;
+      try {
+        tokens = await refreshTokens(settings, transport, refreshToken);
+      } catch (error) {
+        // invalid_grant: the connection is gone. invalid_client: the app's
+        // client id or secret is wrong. Neither clears without a person.
+        if (error?.code === 'xero_reconnect_needed' || ['invalid_client', 'unauthorized_client'].includes(error?.oauthError)) {
+          await guard.halt(connection.tenantId, 'auth', { detail: `Xero refused the token refresh${error.oauthError ? ` (${error.oauthError})` : ''}` });
+        } else if (error?.code !== 'xero_replay_no_match') {
+          await guard.record(connection.tenantId, { resource: 'token', failureKind: error?.code === 'xero_unreachable' ? 'network' : 'token_refresh' });
+        }
+        throw error;
+      }
+      await guard.record(connection.tenantId, { resource: 'token', statusCode: 200 });
       await storeRotatedToken(tx, organisationId, { refreshToken: tokens.refresh_token, scope: tokens.scope, key: settings.tokenKey });
       remember(organisationId, tokens);
       return tokens.access_token;
@@ -96,6 +135,7 @@ export function createXeroRuntime({ settings, fetch, now = Date.now, log = conso
       invalidateAccessToken: () => accessTokens.delete(organisationId),
       fetch: transport,
       governor,
+      guard: guardFor(db),
       apiBase: settings.endpoints.api,
       log,
     });
@@ -122,6 +162,7 @@ export function createXeroRuntime({ settings, fetch, now = Date.now, log = conso
     settings,
     transport,
     governor,
+    guardFor,
     states,
     remember,
     forget: (organisationId) => accessTokens.delete(organisationId),

package/server/integrations/xero/settings.js

@@ -167,6 +167,9 @@ export function resolveXeroSettings(env = process.env) {
     mirrorPageSize: Math.min(readPositiveInteger(env, 'XERO_MIRROR_PAGE_SIZE', DEFAULT_MIRROR_PAGE_SIZE), MAX_MIRROR_PAGE_SIZE),
     // The share of the day's calls the mirror leaves for drafts and people.
     mirrorReserveFraction: readFraction(env, 'XERO_MIRROR_RESERVE_FRACTION', 0.3),
+    // The key Xero signs each webhook with (issue #45), from the Xero app's
+    // Webhooks page. Unset, Flow answers no webhook and reads by polling only.
+    webhookKey: readEnv(env, 'XERO_WEBHOOK_KEY') || null,
     endpoints: XERO_ENDPOINTS,
   };
 }