@arcforgelabs/flow 2026.10.18 → 2026.10.19

package/server/integrations/xero/governor.js

@@ -0,0 +1,275 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+// Xero rate-limit governor. Every Xero API call passes through it.
+//
+// Xero's limits, per connected organisation (tenant) unless noted: 5 calls
+// at once, 60 a minute, a daily limit that depends on the app's plan (1,000
+// on Starter, 5,000 on Core and above), and 10,000 a minute across all
+// tenants of one app. The governor keeps one call and five a minute of
+// headroom, so a 429 comes only from the app-wide bucket or a quota change
+// Flow could not see. The daily limit starts at XERO_DAY_LIMIT and follows
+// Xero's X-DayLimit-Remaining header once a response shows it.
+//
+// State is per process and per tenant: a counting semaphore, a sliding
+// one-minute window, a day counter, and a circuit that opens when Xero says
+// the day's calls are used up. One Flow process serves one lab.
+
+// Each call counts against the lane that made it, so status shows where the
+// day's budget went. Callers set the lane with withXeroLane().
+export const XERO_LANES = Object.freeze(['writes', 'sync', 'reads', 'other']);
+const laneStorage = new AsyncLocalStorage();
+
+export function withXeroLane(lane, fn) {
+  return laneStorage.run(XERO_LANES.includes(lane) ? lane : 'other', fn);
+}
+
+export function currentXeroLane() {
+  return laneStorage.getStore() || 'other';
+}
+
+export const DEFAULT_GOVERNOR_CONFIG = Object.freeze({
+  maxConcurrent: 4,
+  maxPerMinute: 55,
+  dayLimit: 1000,
+  usageWarningFraction: 0.7,
+  appMinuteLimit: 10000,
+  minuteWindowMs: 60_000,
+  dayMs: 24 * 60 * 60 * 1000,
+  maxRetrySleepMs: 60_000,
+});
+
+function dayKeyOf(ms) {
+  return new Date(ms).toISOString().slice(0, 10);
+}
+
+function circuitOpenError(circuit, now) {
+  const error = new Error(`Xero rate-limit circuit open (${circuit.reason}).`);
+  error.code = 'xero_rate_limited';
+  error.status = 429;
+  error.retryAfterMs = Math.max(0, circuit.until - now);
+  return error;
+}
+
+export function createGovernor({ config: overrides = {}, now = Date.now, random = Math.random, sleep, log = console } = {}) {
+  const config = { ...DEFAULT_GOVERNOR_CONFIG, ...overrides };
+  const sleepFn = sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const tenants = new Map();
+  const appMinuteWindow = [];
+
+  function tenantState(tenantId) {
+    const key = String(tenantId || 'unknown');
+    if (!tenants.has(key)) {
+      tenants.set(key, {
+        tenantId: key,
+        inFlight: 0,
+        waiters: [],
+        minuteWindow: [],
+        dayCount: 0,
+        dayKey: dayKeyOf(now()),
+        laneCounts: {},
+        observedDayLimit: null,
+        observedDayRemaining: null,
+        observedMinuteRemaining: null,
+        observedAppMinuteRemaining: null,
+        warnedDayKey: null,
+        circuit: { state: 'closed', reason: '', openedAt: 0, until: 0 },
+        wakeScheduled: false,
+      });
+    }
+    return tenants.get(key);
+  }
+
+  function prune(window, at) {
+    while (window.length && window[0] <= at - config.minuteWindowMs) window.shift();
+  }
+
+  function rollover(tenant) {
+    const today = dayKeyOf(now());
+    if (tenant.dayKey === today) return;
+    tenant.dayKey = today;
+    tenant.dayCount = 0;
+    tenant.laneCounts = {};
+    if (tenant.circuit.state === 'open' && tenant.circuit.reason === 'DayLimit') {
+      tenant.circuit = { state: 'closed', reason: '', openedAt: 0, until: 0 };
+    }
+  }
+
+  // Xero's own count wins once a response has shown it.
+  function dayLimitOf(tenant) {
+    return Number.isFinite(tenant.observedDayLimit) && tenant.observedDayLimit > 0
+      ? tenant.observedDayLimit
+      : config.dayLimit;
+  }
+
+  function count(tenant, lane) {
+    tenant.dayCount += 1;
+    tenant.laneCounts[lane] = (tenant.laneCounts[lane] || 0) + 1;
+    const limit = dayLimitOf(tenant);
+    if (tenant.warnedDayKey !== tenant.dayKey && tenant.dayCount >= limit * config.usageWarningFraction) {
+      tenant.warnedDayKey = tenant.dayKey;
+      log.warn?.(`[xero] ${tenant.dayCount} of ${limit} Xero calls used today (${Math.round(config.usageWarningFraction * 100)}% warning). By lane: ${JSON.stringify(tenant.laneCounts)}`);
+    }
+  }
+
+  function checkCircuit(tenant) {
+    const at = now();
+    if (tenant.circuit.state === 'open' && tenant.circuit.until && at >= tenant.circuit.until) {
+      tenant.circuit = { ...tenant.circuit, state: 'half_open', until: 0 };
+    }
+    if (tenant.circuit.state === 'open') throw circuitOpenError(tenant.circuit, at);
+  }
+
+  function hasRoom(tenant) {
+    return tenant.inFlight < config.maxConcurrent
+      && tenant.minuteWindow.length < config.maxPerMinute
+      && appMinuteWindow.length < config.appMinuteLimit;
+  }
+
+  function take(tenant, lane) {
+    const at = now();
+    tenant.inFlight += 1;
+    tenant.minuteWindow.push(at);
+    appMinuteWindow.push(at);
+    count(tenant, lane);
+  }
+
+  function admitWaiting(tenant) {
+    while (tenant.waiters.length && tenant.inFlight < config.maxConcurrent) {
+      const at = now();
+      prune(tenant.minuteWindow, at);
+      prune(appMinuteWindow, at);
+      if (!hasRoom(tenant)) {
+        scheduleWake(tenant);
+        return;
+      }
+      const waiter = tenant.waiters.shift();
+      take(tenant, waiter.lane);
+      waiter.resolve();
+    }
+  }
+
+  function scheduleWake(tenant) {
+    if (!tenant.waiters.length || tenant.wakeScheduled) return;
+    const at = now();
+    prune(tenant.minuteWindow, at);
+    prune(appMinuteWindow, at);
+    const wakeTimes = [];
+    if (tenant.minuteWindow.length >= config.maxPerMinute) wakeTimes.push(tenant.minuteWindow[0] + config.minuteWindowMs);
+    if (appMinuteWindow.length >= config.appMinuteLimit) wakeTimes.push(appMinuteWindow[0] + config.minuteWindowMs);
+    const waitMs = wakeTimes.length ? Math.max(10, Math.max(...wakeTimes) - at) : 100;
+    tenant.wakeScheduled = true;
+    Promise.resolve(sleepFn(waitMs)).then(() => {
+      tenant.wakeScheduled = false;
+      admitWaiting(tenant);
+    }, () => {
+      tenant.wakeScheduled = false;
+      scheduleWake(tenant);
+    });
+  }
+
+  async function acquire(tenantId) {
+    const tenant = tenantState(tenantId);
+    rollover(tenant);
+    checkCircuit(tenant);
+    if (tenant.dayCount >= dayLimitOf(tenant)) {
+      tripCircuit(tenantId, 'DayLimit', config.dayMs);
+      checkCircuit(tenant);
+    }
+    const lane = currentXeroLane();
+    const at = now();
+    prune(tenant.minuteWindow, at);
+    prune(appMinuteWindow, at);
+    if (!tenant.waiters.length && hasRoom(tenant)) {
+      take(tenant, lane);
+      return;
+    }
+    await new Promise((resolve) => {
+      tenant.waiters.push({ resolve, lane });
+      scheduleWake(tenant);
+    });
+  }
+
+  function release(tenantId) {
+    const tenant = tenantState(tenantId);
+    tenant.inFlight = Math.max(0, tenant.inFlight - 1);
+    admitWaiting(tenant);
+  }
+
+  // Folds in Xero's rate-limit headers (see readRateLimitHeaders).
+  function observe(tenantId, info) {
+    if (!info) return;
+    const tenant = tenantState(tenantId);
+    if (typeof info.dayRemaining === 'number') {
+      tenant.observedDayRemaining = info.dayRemaining;
+      // Calls made today plus what Xero says is left. Xero's day does not
+      // reset at UTC midnight, so this is an estimate the next response
+      // corrects.
+      tenant.observedDayLimit = Math.max(1, tenant.dayCount + info.dayRemaining);
+      if (info.dayRemaining <= 0) tripCircuit(tenantId, 'DayLimit', config.dayMs);
+    }
+    if (typeof info.minuteRemaining === 'number') tenant.observedMinuteRemaining = info.minuteRemaining;
+    if (typeof info.appMinuteRemaining === 'number') tenant.observedAppMinuteRemaining = info.appMinuteRemaining;
+  }
+
+  function tripCircuit(tenantId, reason, durationMs) {
+    const tenant = tenantState(tenantId);
+    const at = now();
+    tenant.circuit = { state: 'open', reason: String(reason || 'Unknown'), openedAt: at, until: at + Math.max(1000, Number(durationMs) || 0) };
+  }
+
+  // How long to wait before retrying a 429, by Xero's X-Rate-Limit-Problem.
+  // Never more than a minute inside one request: a longer wait fails fast and
+  // the circuit and the caller decide when to try again.
+  function retryDelayMs(problem, retryAfterMs) {
+    const jitter = Math.floor(random() * 500);
+    const hinted = Number.isFinite(retryAfterMs) && retryAfterMs >= 0 ? retryAfterMs : null;
+    const clamp = (ms) => Math.max(0, Math.min(config.maxRetrySleepMs, ms));
+    switch (problem) {
+      case 'ConcurrentLimit':
+        return clamp((hinted ?? 200) + jitter);
+      case 'MinuteLimit':
+      case 'AppMinuteLimit':
+        if (hinted !== null) return clamp(hinted + jitter);
+        return clamp(60_000 - (now() % 60_000) + jitter);
+      case 'DayLimit':
+        return 0;
+      default:
+        return clamp((hinted ?? 1000) + jitter);
+    }
+  }
+
+  function status(tenantId) {
+    const tenant = tenantState(tenantId);
+    rollover(tenant);
+    const at = now();
+    prune(tenant.minuteWindow, at);
+    prune(appMinuteWindow, at);
+    const dayLimit = dayLimitOf(tenant);
+    return {
+      inFlight: tenant.inFlight,
+      waiting: tenant.waiters.length,
+      minuteUsed: tenant.minuteWindow.length,
+      minuteMax: config.maxPerMinute,
+      dayCount: tenant.dayCount,
+      dayLimit,
+      dayLimitSource: Number.isFinite(tenant.observedDayLimit) ? 'xero' : 'setting',
+      dayRemaining: Math.max(0, dayLimit - tenant.dayCount),
+      usageWarning: tenant.dayCount >= dayLimit * config.usageWarningFraction,
+      laneCounts: { ...tenant.laneCounts },
+      observedDayRemaining: tenant.observedDayRemaining,
+      observedMinuteRemaining: tenant.observedMinuteRemaining,
+      circuit: { ...tenant.circuit },
+    };
+  }
+
+  return {
+    config,
+    acquire,
+    release,
+    observe,
+    tripCircuit,
+    retryDelayMs,
+    status,
+    sleep: (ms) => sleepFn(ms),
+  };
+}

package/server/integrations/xero/index.js

@@ -0,0 +1,56 @@
+import { fileURLToPath } from 'node:url';
+import { sql } from 'drizzle-orm';
+import { pushInvoice } from './drafts.js';
+import { readPayments } from './ledger.js';
+import { createXeroRouter } from './routes.js';
+import { createXeroRuntime, requireXeroSettings } 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']);
+
+// `runtime` is for tests. Otherwise start() builds it from the environment,
+// so a turned-off adapter never reads its settings, and a malformed setting
+// stops boot when Xero is on.
+export function createXeroAdapter({ runtime: given = null } = {}) {
+  let runtime = given;
+  let database = null;
+  const current = () => {
+    runtime ??= createXeroRuntime({ settings: requireXeroSettings(process.env) });
+    return runtime;
+  };
+
+  return {
+    id: 'xero',
+    name: 'Xero',
+    bundled: false,
+    schema: {
+      migrationsFolder: fileURLToPath(new URL('./migrations', import.meta.url)),
+      tables: [...XERO_TABLES],
+    },
+    async start({ db, log }) {
+      database = db;
+      const { settings } = current();
+      log.info?.(`[xero] mode ${settings.mode}; writes ${writesAllowed(settings) ? 'on' : 'off (XERO_ALLOW_LIVE_WRITES)'}; redirect URI ${settings.redirectUri ?? 'not set (FLOW_PUBLIC_ORIGIN)'}`);
+    },
+    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 };
+      },
+      // One issued invoice to a Xero draft (drafts.js). The Flow invoice id
+      // and version are the idempotency key.
+      pushInvoice: ({ organisationId, invoiceId, pushedBy = null }) => pushInvoice(database, current(), { organisationId, invoiceId, pushedBy }),
+      // 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) }),
+    },
+    routes: ({ db, personAuth, log }) => createXeroRouter({ db, personAuth, runtime: current(), log }),
+  };
+}
+
+export const xeroAdapter = createXeroAdapter();

package/server/integrations/xero/ledger.js

@@ -0,0 +1,269 @@
+import { and, eq, inArray, sql } from 'drizzle-orm';
+import { recordAccountingEvidence, recordPayment } from '../../core/ledger.js';
+import { billingObligations, contacts as flowContacts } from '../../db/schema.js';
+import { matchContact, parseXeroDate } from './catalogue.js';
+import { withXeroLane } from './governor.js';
+
+// What the billing obligation ledger (server/core/ledger.js) needs from Xero:
+//
+// - checkInvoice: does Xero hold an invoice for this job? It answers in the
+//   ledger's evidence shape ({ state, accountingRef, accountingUrl,
+//   matchedBy, checkedAt }) and is the `liveCheck` for
+//   draftInvoiceForObligation, so a draft is made only when Xero has none.
+// - readPayments: sales invoice payments changed since a time, in the shape
+//   recordPayment takes.
+// - recordXeroPayments: reads those payments, ties each to its job by an
+//   exact match only, refreshes the job's invoice state, and records them.
+//
+// Exact matches, as the ledger defines them:
+//   flow_invoice        the Xero invoice Flow made from the job's Flow invoice
+//                       (xero_invoice_pushes)
+//   accounting_ref      the Xero invoice id the ledger already holds
+//   source_invoice_ref  a Xero invoice whose number or reference is the work
+//                       system's own invoice number for the job
+// A Xero invoice for the same customer with the job's case reference is not
+// exact: it is reported with matchedBy "reference", which the ledger records
+// as ambiguous and which refuses a draft. Any doubt fails closed.
+
+export const PAYMENTS_FIRST_DAYS = 90;
+
+// Xero invoice status to the ledger's accounting state.
+export function ledgerState(invoice) {
+  switch (invoice?.Status) {
+    case 'DRAFT':
+    case 'SUBMITTED':
+      return 'drafted';
+    case 'AUTHORISED':
+      return Number(invoice.AmountPaid) > 0 || Number(invoice.AmountCredited) > 0 ? 'part_paid' : 'authorised';
+    case 'PAID':
+      return 'paid';
+    case 'VOIDED':
+      return 'voided';
+    case 'DELETED':
+      return 'deleted';
+    default:
+      return null;
+  }
+}
+
+const shortCodes = new Map(); // tenant id -> Xero organisation short code
+
+async function invoiceUrl(runtime, client, invoiceId) {
+  if (!shortCodes.has(client.tenantId)) {
+    const organisation = await client.getOrganisation().catch(() => null);
+    if (organisation?.ShortCode) shortCodes.set(client.tenantId, organisation.ShortCode);
+  }
+  const shortCode = shortCodes.get(client.tenantId);
+  const view = `/AccountsReceivable/View.aspx?InvoiceID=${encodeURIComponent(invoiceId)}`;
+  if (!shortCode) return null;
+  return `${runtime.settings.endpoints.web}/organisationlogin/default.aspx?shortcode=${encodeURIComponent(shortCode)}&redirecturl=${encodeURIComponent(view)}`;
+}
+
+async function evidenceFor(runtime, client, invoice, matchedBy, checkedAt) {
+  return {
+    state: ledgerState(invoice),
+    accountingRef: invoice.InvoiceID,
+    accountingUrl: await invoiceUrl(runtime, client, invoice.InvoiceID),
+    matchedBy,
+    checkedAt,
+    xero: { invoiceId: invoice.InvoiceID, number: invoice.InvoiceNumber ?? null, status: invoice.Status, totalCents: Math.round(Number(invoice.Total ?? 0) * 100) },
+  };
+}
+
+const notFound = (checkedAt) => ({ state: 'not_found', accountingRef: null, accountingUrl: null, matchedBy: null, checkedAt });
+
+// More than one Xero invoice answers for the job: report one, with no exact
+// match, so the ledger records the job as ambiguous for a person.
+async function several(runtime, client, found, checkedAt) {
+  const evidence = await evidenceFor(runtime, client, found[0], 'several', checkedAt);
+  return { ...evidence, candidates: found.map((inv) => ({ invoiceId: inv.InvoiceID, number: inv.InvoiceNumber ?? null, status: inv.Status })) };
+}
+
+// The Xero invoice for one obligation (a row of billing_obligations), looked
+// up live. Costs 1 to 4 Xero calls.
+export async function checkInvoice(db, runtime, client, organisationId, obligation) {
+  const checkedAt = new Date(runtime.now()).toISOString();
+
+  // 1. The Xero invoice Flow made from the job's Flow invoice.
+  if (obligation.invoiceId) {
+    const { rows } = await db.execute(sql`select xero_invoice_id, state from xero_invoice_pushes
+      where organisation_id = ${organisationId} and invoice_id = ${obligation.invoiceId} order by version desc`);
+    const unsettled = rows.find((r) => !r.xero_invoice_id);
+    if (unsettled) {
+      // A push whose outcome is unknown: Xero may hold a draft. Never "not found".
+      return { state: 'drafted', accountingRef: null, accountingUrl: null, matchedBy: 'unsettled_push', checkedAt };
+    }
+    // The newest version's Xero invoice that is still live; if every one is
+    // deleted or voided, the newest one, so the ledger sees that.
+    let newest = null;
+    for (const row of rows) {
+      const live = await client.getInvoice(row.xero_invoice_id);
+      if (live && !['DELETED', 'VOIDED'].includes(live.Status)) return evidenceFor(runtime, client, live, 'flow_invoice', checkedAt);
+      newest ??= live;
+    }
+    if (newest) return evidenceFor(runtime, client, newest, 'flow_invoice', checkedAt);
+  }
+
+  // 2. The Xero invoice the ledger already holds.
+  if (obligation.accountingRef) {
+    const live = await client.getInvoice(obligation.accountingRef).catch((error) => {
+      if (error.status === 404) return null;
+      throw error;
+    });
+    if (live) return evidenceFor(runtime, client, live, 'accounting_ref', checkedAt);
+    return notFound(checkedAt); // the ledger records "seen before, now not found" as a conflict
+  }
+
+  const sales = (list) => list.filter((inv) => (inv.Type ?? 'ACCREC') === 'ACCREC' && !['DELETED', 'VOIDED'].includes(inv.Status));
+
+  // 3. The work system's own invoice number, as Xero's number or reference.
+  if (obligation.sourceInvoiceRef) {
+    const byId = new Map();
+    for (const inv of sales(await client.findInvoicesByNumber(obligation.sourceInvoiceRef))) byId.set(inv.InvoiceID, inv);
+    for (const inv of sales(await client.findInvoicesByReference(obligation.sourceInvoiceRef))) byId.set(inv.InvoiceID, inv);
+    const found = [...byId.values()];
+    if (found.length === 1) return evidenceFor(runtime, client, found[0], 'source_invoice_ref', checkedAt);
+    if (found.length > 1) return several(runtime, client, found, checkedAt);
+  }
+
+  // 4. The reference Flow would give the job's invoice, for the same
+  // customer. Not exact: it refuses a draft and goes to a person.
+  const reference = obligation.caseRef ?? obligation.sourceJobRef;
+  if (reference) {
+    let customer = null;
+    if (obligation.contactId) {
+      const [contact] = await db.select({ name: flowContacts.name }).from(flowContacts)
+        .where(and(eq(flowContacts.organisationId, organisationId), eq(flowContacts.id, obligation.contactId)));
+      const match = contact ? await matchContact(db, organisationId, contact.name) : { state: 'missing' };
+      customer = match.state === 'matched' ? match.contact.xeroContactId : null;
+      if (match.state === 'ambiguous') {
+        const error = new Error(`More than one Xero contact is named "${contact.name}"; Flow cannot tell which invoices are this customer's.`);
+        error.code = 'xero_contact_ambiguous';
+        throw error;
+      }
+    }
+    // Another customer's invoice with the same reference is not this job's.
+    const found = sales(await client.findInvoicesByReference(reference))
+      .filter((inv) => !customer || inv.Contact?.ContactID === customer);
+    if (found.length === 1) return evidenceFor(runtime, client, found[0], 'reference', checkedAt);
+    if (found.length > 1) return several(runtime, client, found, checkedAt);
+  }
+  return notFound(checkedAt);
+}
+
+// The ledger's liveCheck for draftInvoiceForObligation:
+//   draftInvoiceForObligation(db, org, id, { liveCheck: xeroLiveCheck(db, runtime, org), actor })
+// A Xero error throws, and the ledger then refuses the draft.
+export function xeroLiveCheck(db, runtime, organisationId) {
+  return (obligation) => withXeroLane('reads', async () => {
+    const { client } = await runtime.clientFor(db, organisationId);
+    return checkInvoice(db, runtime, client, organisationId, obligation);
+  });
+}
+
+// Checks Xero for one obligation and records what it found as accounting
+// evidence on the ledger.
+export async function recordXeroEvidence(db, runtime, organisationId, obligation, { actor }) {
+  const evidence = await xeroLiveCheck(db, runtime, organisationId)(obligation);
+  if (evidence.state === null) return obligation;
+  if (evidence.matchedBy === 'unsettled_push') return obligation;
+  const { state, accountingRef, accountingUrl, matchedBy, checkedAt } = evidence;
+  return recordAccountingEvidence(db, organisationId, obligation.id, { state, accountingRef, accountingUrl, matchedBy, checkedAt, actor });
+}
+
+function mapPayment(payment) {
+  return {
+    paymentRef: payment.PaymentID,
+    paidOn: parseXeroDate(payment.Date)?.toISOString().slice(0, 10) ?? null,
+    amountCents: Math.round(Number(payment.Amount) * 100),
+    reference: payment.Reference || null,
+    reconciled: Boolean(payment.IsReconciled),
+    status: payment.Status ?? 'AUTHORISED',
+    xeroInvoiceId: payment.Invoice?.InvoiceID ?? null,
+    xeroInvoiceNumber: payment.Invoice?.InvoiceNumber ?? null,
+    updatedAt: parseXeroDate(payment.UpdatedDateUTC),
+  };
+}
+
+// Sales invoice payments changed since `since` (a Date). `cursor` is the
+// latest change seen: pass it as `since` next time.
+export async function readPayments(db, runtime, organisationId, { since }) {
+  return withXeroLane('reads', async () => {
+    const { client } = await runtime.clientFor(db, organisationId);
+    const payments = (await client.listPaymentsSince(since)).map(mapPayment).filter((p) => p.paymentRef && p.xeroInvoiceId);
+    const latest = payments.reduce((max, p) => (p.updatedAt && p.updatedAt > max ? p.updatedAt : max), since);
+    return { payments, cursor: latest };
+  });
+}
+
+async function readCursor(db, organisationId) {
+  const { rows } = await db.execute(sql`select payments_since from xero_payment_cursors where organisation_id = ${organisationId}`);
+  return rows[0]?.payments_since ?? null;
+}
+
+// Reads Xero payments since the stored cursor and records each on its job.
+// A payment counts only when its Xero invoice ties to one job exactly: the
+// Xero invoice Flow made from the job's Flow invoice (flow_invoice), or the
+// one the ledger holds (accounting_ref). Before it records, Flow refreshes
+// that job's invoice state from Xero, so the ledger takes the payment. Others
+// are listed, not recorded. A deleted payment is listed for a person: the
+// ledger keeps what it recorded.
+export async function recordXeroPayments(db, runtime, organisationId, { actor, since: given = null } = {}) {
+  return runtime.serial(organisationId, async () => {
+    const since = given ?? await readCursor(db, organisationId)
+      ?? new Date(runtime.now() - PAYMENTS_FIRST_DAYS * 86_400_000);
+    const { payments, cursor } = await readPayments(db, runtime, organisationId, { since: new Date(since) });
+    const result = { since: new Date(since).toISOString(), cursor: cursor.toISOString(), recorded: [], unmatched: [], deleted: [], failed: [] };
+
+    const xeroIds = [...new Set(payments.map((p) => p.xeroInvoiceId))];
+    const byFlowInvoice = new Map();
+    if (xeroIds.length) {
+      const { rows } = await db.execute(sql`select xero_invoice_id, invoice_id from xero_invoice_pushes
+        where organisation_id = ${organisationId} and xero_invoice_id = any(${sql.param(xeroIds)}::text[])`);
+      for (const row of rows) byFlowInvoice.set(row.xero_invoice_id, row.invoice_id);
+    }
+    const flowInvoiceIds = [...new Set(byFlowInvoice.values())];
+    const obligations = xeroIds.length ? await db.select().from(billingObligations).where(and(
+      eq(billingObligations.organisationId, organisationId),
+      sql`(${flowInvoiceIds.length ? inArray(billingObligations.invoiceId, flowInvoiceIds) : sql`false`} or ${inArray(billingObligations.accountingRef, xeroIds)})`,
+    )) : [];
+
+    const refreshed = new Set();
+    for (const payment of payments) {
+      const shown = { paymentRef: payment.paymentRef, xeroInvoiceId: payment.xeroInvoiceId, amountCents: payment.amountCents, paidOn: payment.paidOn };
+      if (payment.status === 'DELETED') {
+        result.deleted.push(shown);
+        continue;
+      }
+      const flowInvoiceId = byFlowInvoice.get(payment.xeroInvoiceId);
+      const byFlow = flowInvoiceId ? obligations.filter((o) => o.invoiceId === flowInvoiceId) : [];
+      const byRef = obligations.filter((o) => o.accountingRef === payment.xeroInvoiceId);
+      const [obligation, matchedBy] = byFlow.length === 1 ? [byFlow[0], 'flow_invoice'] : byRef.length === 1 ? [byRef[0], 'accounting_ref'] : [null, null];
+      if (!obligation) {
+        result.unmatched.push(shown);
+        continue;
+      }
+      try {
+        if (!refreshed.has(obligation.id)) {
+          await recordXeroEvidence(db, runtime, organisationId, obligation, { actor });
+          refreshed.add(obligation.id);
+        }
+        const { paymentRef, paidOn, amountCents, reference, reconciled } = payment;
+        const accountingUrl = (await db.select({ url: billingObligations.accountingUrl }).from(billingObligations)
+          .where(eq(billingObligations.id, obligation.id)))[0]?.url ?? null;
+        await recordPayment(db, organisationId, obligation.id, { paymentRef, paidOn, amountCents, reference, reconciled, accountingUrl, matchedBy, actor });
+        result.recorded.push({ ...shown, obligationId: obligation.id, matchedBy });
+      } catch (error) {
+        result.failed.push({ ...shown, obligationId: obligation.id, error: { code: error.code ?? 'failed', message: error.message } });
+      }
+    }
+
+    // Move the cursor only when every payment was settled one way or another,
+    // so a failed one is read again next time.
+    if (!result.failed.length) {
+      await db.execute(sql`insert into xero_payment_cursors (organisation_id, payments_since) values (${organisationId}, ${cursor})
+        on conflict (organisation_id) do update set payments_since = excluded.payments_since, updated_at = now()`);
+    }
+    return result;
+  });
+}

package/server/integrations/xero/migrations/0000_xero_connections.sql

@@ -0,0 +1,17 @@
+-- The Xero connection of each Flow organisation. The refresh token is
+-- AES-256-GCM ciphertext (XERO_TOKEN_KEY); the plain token is never stored.
+CREATE TABLE "xero_connections" (
+	"organisation_id" uuid PRIMARY KEY NOT NULL REFERENCES "organisations"("id"),
+	"mode" text NOT NULL,
+	"tenant_id" text NOT NULL,
+	"tenant_name" text,
+	"scope" text,
+	"refresh_token_enc" text NOT NULL,
+	"connected_by" uuid REFERENCES "people"("id") ON DELETE SET NULL,
+	"connected_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"refreshed_at" timestamp with time zone,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "xero_connections_tenant" UNIQUE("tenant_id"),
+	CONSTRAINT "xero_connections_mode_valid" CHECK ("mode" in ('live', 'sandbox', 'replay')),
+	CONSTRAINT "xero_connections_token_sealed" CHECK ("refresh_token_enc" like 'v1:%')
+);

package/server/integrations/xero/migrations/0001_xero_catalogue.sql

@@ -0,0 +1,49 @@
+-- Flow's copy of the Xero contacts and items of each connected organisation,
+-- and a record of each sync. Xero owns these records; a sync replaces the copy.
+CREATE TABLE "xero_contacts" (
+	"organisation_id" uuid NOT NULL REFERENCES "organisations"("id"),
+	"xero_contact_id" text NOT NULL,
+	"name" text NOT NULL,
+	"email" text,
+	"status" text NOT NULL,
+	"is_customer" boolean DEFAULT false NOT NULL,
+	"is_supplier" boolean DEFAULT false NOT NULL,
+	"sales_tracking" jsonb DEFAULT '[]'::jsonb NOT NULL,
+	"xero_updated_at" timestamp with time zone,
+	"synced_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "xero_contacts_pk" PRIMARY KEY("organisation_id", "xero_contact_id")
+);
+--> statement-breakpoint
+CREATE INDEX "xero_contacts_org_name" ON "xero_contacts" ("organisation_id", lower("name"));
+--> statement-breakpoint
+CREATE TABLE "xero_items" (
+	"organisation_id" uuid NOT NULL REFERENCES "organisations"("id"),
+	"xero_item_id" text NOT NULL,
+	"code" text NOT NULL,
+	"name" text,
+	"description" text,
+	"is_sold" boolean DEFAULT true NOT NULL,
+	"sales_unit_amount_cents" integer,
+	"sales_account_code" text,
+	"sales_tax_type" text,
+	"xero_updated_at" timestamp with time zone,
+	"synced_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "xero_items_pk" PRIMARY KEY("organisation_id", "xero_item_id"),
+	CONSTRAINT "xero_items_org_code" UNIQUE("organisation_id", "code")
+);
+--> statement-breakpoint
+CREATE TABLE "xero_sync_runs" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"organisation_id" uuid NOT NULL REFERENCES "organisations"("id"),
+	"status" text DEFAULT 'running' NOT NULL,
+	"started_by" uuid REFERENCES "people"("id") ON DELETE SET NULL,
+	"started_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"finished_at" timestamp with time zone,
+	"contact_count" integer,
+	"item_count" integer,
+	"error_code" text,
+	"error_message" text,
+	CONSTRAINT "xero_sync_runs_status_valid" CHECK ("status" in ('running', 'succeeded', 'failed'))
+);
+--> statement-breakpoint
+CREATE INDEX "xero_sync_runs_org_started" ON "xero_sync_runs" ("organisation_id", "started_at");