@arcforgelabs/flow 2026.10.18 → 2026.10.19

package/server/integrations/xero/migrations/0002_xero_invoice_pushes.sql

@@ -0,0 +1,32 @@
+-- One row for each issued Flow invoice version sent to Xero as a draft. It
+-- holds the exact request and its Idempotency-Key from before the request
+-- leaves, so an uncertain outcome is resolved without a second invoice.
+CREATE TABLE "xero_invoice_pushes" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"organisation_id" uuid NOT NULL,
+	"invoice_id" uuid NOT NULL,
+	"version" integer NOT NULL,
+	"state" text NOT NULL,
+	"idempotency_key" text NOT NULL,
+	"request_body" text NOT NULL,
+	"body_hash" text NOT NULL,
+	"pre_existing_ids" jsonb DEFAULT '[]'::jsonb NOT NULL,
+	"xero_invoice_id" text,
+	"xero_invoice_number" text,
+	"xero_status" text,
+	"verified" boolean DEFAULT false NOT NULL,
+	"error_code" text,
+	"error_message" text,
+	"attempts" integer DEFAULT 1 NOT NULL,
+	"pushed_by" uuid REFERENCES "people"("id") ON DELETE SET NULL,
+	"first_dispatched_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"last_dispatched_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "xero_invoice_pushes_invoice_version" UNIQUE("invoice_id", "version"),
+	CONSTRAINT "xero_invoice_pushes_invoice_same_org" FOREIGN KEY ("organisation_id", "invoice_id") REFERENCES "invoices"("organisation_id", "id"),
+	CONSTRAINT "xero_invoice_pushes_version_issued" FOREIGN KEY ("invoice_id", "version") REFERENCES "invoice_versions"("invoice_id", "version"),
+	CONSTRAINT "xero_invoice_pushes_state_valid" CHECK ("state" in ('dispatching', 'ambiguous', 'created', 'existing', 'mismatch')),
+	CONSTRAINT "xero_invoice_pushes_settled_has_id" CHECK ("state" in ('dispatching', 'ambiguous') or "xero_invoice_id" is not null)
+);
+--> statement-breakpoint
+CREATE INDEX "xero_invoice_pushes_org_invoice" ON "xero_invoice_pushes" ("organisation_id", "invoice_id");

package/server/integrations/xero/migrations/0003_xero_payment_cursors.sql

@@ -0,0 +1,7 @@
+-- Where the next read of Xero payments starts, for each Flow organisation.
+-- (This is the Xero adapter's own migration journal, not the core's.)
+CREATE TABLE "xero_payment_cursors" (
+	"organisation_id" uuid PRIMARY KEY NOT NULL REFERENCES "organisations"("id"),
+	"payments_since" timestamp with time zone NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);

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

@@ -0,0 +1,34 @@
+{
+  "version": "7",
+  "dialect": "postgresql",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "7",
+      "when": 1792368000000,
+      "tag": "0000_xero_connections",
+      "breakpoints": true
+    },
+    {
+      "idx": 1,
+      "version": "7",
+      "when": 1792368060000,
+      "tag": "0001_xero_catalogue",
+      "breakpoints": true
+    },
+    {
+      "idx": 2,
+      "version": "7",
+      "when": 1792368120000,
+      "tag": "0002_xero_invoice_pushes",
+      "breakpoints": true
+    },
+    {
+      "idx": 3,
+      "version": "7",
+      "when": 1792368180000,
+      "tag": "0003_xero_payment_cursors",
+      "breakpoints": true
+    }
+  ]
+}

package/server/integrations/xero/oauth.js

@@ -0,0 +1,143 @@
+import { randomBytes } from 'node:crypto';
+import { DEFAULT_TIMEOUT_MS, xeroError } from './client.js';
+
+// Xero OAuth 2.0 (authorisation code with offline_access). Bodies that carry
+// tokens never reach a log or an error message.
+
+export const STATE_TTL_MS = 10 * 60 * 1000;
+
+export function authorizeUrl(settings, state) {
+  const url = new URL(settings.endpoints.authorize);
+  url.searchParams.set('response_type', 'code');
+  url.searchParams.set('client_id', settings.clientId);
+  url.searchParams.set('redirect_uri', settings.redirectUri);
+  url.searchParams.set('scope', settings.scope);
+  url.searchParams.set('state', state);
+  return url.toString();
+}
+
+async function call(fetchImpl, url, init, what) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS);
+  try {
+    let response;
+    try {
+      response = await fetchImpl(url, { ...init, signal: controller.signal });
+    } catch (error) {
+      if (error?.code === 'xero_replay_no_match') throw error;
+      throw xeroError('xero_unreachable', `Flow could not reach Xero for ${what}.`, { status: 503 });
+    }
+    const text = await response.text().catch(() => '');
+    let body = null;
+    try {
+      body = text ? JSON.parse(text) : null;
+    } catch {
+      body = null;
+    }
+    return { response, body };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function tokenRequest(settings, fetchImpl, form, what) {
+  const basic = Buffer.from(`${settings.clientId}:${settings.clientSecret}`).toString('base64');
+  const { response, body } = await call(fetchImpl, settings.endpoints.token, {
+    method: 'POST',
+    headers: { Authorization: `Basic ${basic}`, 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
+    body: new URLSearchParams(form).toString(),
+  }, what);
+  if (!response.ok) {
+    // invalid_grant: the refresh token was revoked, expired (60 days unused)
+    // or already used. Only a new connection fixes that.
+    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 });
+  }
+  if (!body?.access_token || !body?.refresh_token) {
+    throw xeroError('xero_token_failed', `Xero's answer to ${what} had no tokens.`, { status: 502 });
+  }
+  return body;
+}
+
+export function exchangeCode(settings, fetchImpl, code) {
+  if (!code) throw xeroError('xero_oauth_failed', 'Xero sent no authorisation code.', { status: 400 });
+  return tokenRequest(settings, fetchImpl, { grant_type: 'authorization_code', code, redirect_uri: settings.redirectUri }, 'the authorisation code');
+}
+
+export function refreshTokens(settings, fetchImpl, refreshToken) {
+  return tokenRequest(settings, fetchImpl, { grant_type: 'refresh_token', refresh_token: refreshToken }, 'the token refresh');
+}
+
+// Best effort: a disconnect deletes Flow's copy even when Xero is down.
+export async function revokeToken(settings, fetchImpl, refreshToken) {
+  const basic = Buffer.from(`${settings.clientId}:${settings.clientSecret}`).toString('base64');
+  const { response } = await call(fetchImpl, settings.endpoints.revoke, {
+    method: 'POST',
+    headers: { Authorization: `Basic ${basic}`, 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams({ token: refreshToken }).toString(),
+  }, 'revoking the token');
+  return response.ok;
+}
+
+export async function fetchConnections(settings, fetchImpl, accessToken) {
+  const { response, body } = await call(fetchImpl, settings.endpoints.connections, {
+    method: 'GET',
+    headers: { Authorization: `Bearer ${accessToken}`, Accept: 'application/json' },
+  }, 'the organisation list');
+  if (!response.ok || !Array.isArray(body)) {
+    throw xeroError('xero_oauth_failed', `Xero did not list the authorised organisations (${response.status}).`, { status: 502 });
+  }
+  return body;
+}
+
+const sameName = (a, b) => String(a ?? '').trim().toLowerCase() === String(b ?? '').trim().toLowerCase();
+
+// The one Xero organisation this connection is for. XERO_TENANT_ID and
+// XERO_TENANT_NAME narrow the choice; more than one left is refused.
+export function selectConnection(connections, settings) {
+  let matches = connections.filter((c) => (c.tenantType ?? 'ORGANISATION') === 'ORGANISATION');
+  if (settings.tenantId) matches = matches.filter((c) => c.tenantId === settings.tenantId);
+  if (settings.tenantName) matches = matches.filter((c) => sameName(c.tenantName, settings.tenantName));
+  const names = connections.map((c) => c.tenantName).filter(Boolean);
+  if (!matches.length) {
+    const wanted = settings.tenantId || settings.tenantName;
+    throw xeroError('xero_wrong_organisation',
+      wanted
+        ? `The Xero organisation this installation is set to (XERO_TENANT_ID or XERO_TENANT_NAME) was not among the ones approved: ${names.join(', ') || 'none'}.`
+        : 'No Xero organisation was approved.',
+      { status: 409 });
+  }
+  if (matches.length > 1) {
+    throw xeroError('xero_ambiguous_organisation',
+      `More than one Xero organisation was approved (${names.join(', ')}). Set XERO_TENANT_ID or XERO_TENANT_NAME, or approve only one.`,
+      { status: 409 });
+  }
+  return matches[0];
+}
+
+// One-use OAuth states, kept in memory for ten minutes. One Flow process
+// serves one lab, and an owner finishes the Xero approval in the same
+// browser within minutes.
+export function createStateStore({ now = Date.now, ttlMs = STATE_TTL_MS } = {}) {
+  const states = new Map();
+  const purge = () => {
+    for (const [state, entry] of states) if (now() - entry.createdAt > ttlMs) states.delete(state);
+  };
+  return {
+    issue(entry) {
+      purge();
+      const state = randomBytes(24).toString('base64url');
+      states.set(state, { ...entry, createdAt: now() });
+      return state;
+    },
+    consume(state) {
+      purge();
+      if (typeof state !== 'string' || !states.has(state)) return null;
+      const entry = states.get(state);
+      states.delete(state);
+      return entry;
+    },
+  };
+}

package/server/integrations/xero/replay.js

@@ -0,0 +1,83 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+// Replay mode (XERO_MODE=replay): a stand-in for fetch that answers from
+// recorded, synthetic Xero responses and never opens a connection. Tests use
+// it, and so can a development workspace. A request no interaction matches
+// fails, so replay can never fall through to the real Xero.
+//
+// A fixture file is { "interactions": [ { "request": { "method", "url",
+// "query"? }, "response": { "status"?, "headers"?, "body"? }, "repeat"? } ] }.
+// A request matches on method, URL without query, and every query value the
+// interaction lists. Interactions are used once, in file order, unless
+// "repeat" is true. Fixtures hold synthetic data only (CONTRIBUTING.md).
+
+export const DEFAULT_REPLAY_FIXTURES = fileURLToPath(new URL('./fixtures/replay.json', import.meta.url));
+
+export function loadReplayFixtures(path = DEFAULT_REPLAY_FIXTURES) {
+  const parsed = JSON.parse(readFileSync(path, 'utf8'));
+  if (!Array.isArray(parsed?.interactions)) throw new Error('A Xero replay fixture needs an "interactions" list');
+  return parsed.interactions;
+}
+
+function noMatch(method, url) {
+  const error = new Error(`Xero replay has no recorded answer for ${method} ${url.origin}${url.pathname}`);
+  error.code = 'xero_replay_no_match';
+  return error;
+}
+
+function matches(interaction, method, url) {
+  const expected = interaction.request ?? {};
+  if ((expected.method ?? 'GET').toUpperCase() !== method) return false;
+  const want = new URL(expected.url);
+  if (want.origin !== url.origin || want.pathname !== url.pathname) return false;
+  for (const [key, value] of Object.entries(expected.query ?? {})) {
+    if (url.searchParams.get(key) !== String(value)) return false;
+  }
+  return true;
+}
+
+function readBody(body) {
+  if (body === undefined || body === null) return undefined;
+  if (typeof body === 'string') {
+    try {
+      return JSON.parse(body);
+    } catch {
+      return body;
+    }
+  }
+  return String(body);
+}
+
+// Returns a fetch function. `calls` records each request without its
+// Authorization header, for tests.
+export function createReplayFetch(interactions = loadReplayFixtures()) {
+  const pending = interactions.map((interaction) => ({ ...interaction, used: false }));
+  const calls = [];
+
+  async function replayFetch(input, init = {}) {
+    const url = new URL(typeof input === 'string' || input instanceof URL ? input : input.url);
+    const method = String(init.method ?? 'GET').toUpperCase();
+    const headers = Object.fromEntries(Object.entries(init.headers ?? {})
+      .filter(([name]) => name.toLowerCase() !== 'authorization'));
+    calls.push({ method, url: url.toString(), path: url.pathname, query: Object.fromEntries(url.searchParams), headers, body: readBody(init.body) });
+
+    const interaction = pending.find((entry) => (entry.repeat || !entry.used) && matches(entry, method, url));
+    if (!interaction) throw noMatch(method, url);
+    interaction.used = true;
+
+    const { status = 200, headers: responseHeaders = {}, body } = interaction.response ?? {};
+    if (interaction.response?.networkError) {
+      throw Object.assign(new Error('replayed network failure'), { name: 'TypeError' });
+    }
+    const text = body === undefined ? '' : typeof body === 'string' ? body : JSON.stringify(body);
+    return new Response(status === 204 || status === 304 ? null : text, {
+      status,
+      headers: { 'content-type': 'application/json', ...responseHeaders },
+    });
+  }
+
+  replayFetch.calls = calls;
+  replayFetch.unused = () => pending.filter((entry) => !entry.used && !entry.repeat);
+  return replayFetch;
+}

package/server/integrations/xero/routes.js

@@ -0,0 +1,234 @@
+import { and, eq } from 'drizzle-orm';
+import express from 'express';
+import { FlowError } from '../../core/errors.js';
+import { billingObligations, organisations } from '../../db/schema.js';
+import { lastSync, listContacts, listItems, syncCatalogue } from './catalogue.js';
+import { createXeroClient } from './client.js';
+import { describePush, listPushes, MAX_BATCH, previewDrafts, pushDrafts } from './drafts.js';
+import { recordXeroEvidence, recordXeroPayments } from './ledger.js';
+import { decryptToken, deleteConnection, describeConnection, readConnection, saveConnection } from './connections.js';
+import { authorizeUrl, exchangeCode, fetchConnections, revokeToken, selectConnection } from './oauth.js';
+import { writesAllowed } from './settings.js';
+
+// The Xero adapter's routes, mounted at /api/xero (server/integrations/port.js).
+//
+//   GET  /status?organisationId=   any signed-in person: mode and connection
+//   POST /connect                  owner: returns Xero's approval address
+//   GET  /oauth/callback           Xero sends the owner back here
+//   POST /disconnect               owner: revokes and forgets the connection
+//   POST /sync                     owner or admin: copies Xero contacts and items
+//   GET  /contacts?organisationId=&q=   any signed-in person: the copy
+//   GET  /items?organisationId=    any signed-in person: the copy
+//   POST /invoices/preview         any signed-in person: the Xero drafts Flow
+//                                  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 /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
+//
+// 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,
+// issued to that owner for that organisation, is what admits it.
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+function escapeHtml(value) {
+  return String(value ?? '').replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]);
+}
+
+function page(title, text) {
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>${escapeHtml(title)}</title></head>`
+    + `<body style="font-family: system-ui, sans-serif; max-width: 36rem; margin: 3rem auto; padding: 0 1rem; line-height: 1.5"><h1>${escapeHtml(title)}</h1><p>${escapeHtml(text)}</p></body></html>`;
+}
+
+export function sendError(res, error, log) {
+  const status = error instanceof FlowError ? (error.status ?? 400) : 500;
+  if (status >= 500) log.error?.(`[xero] ${error.code ?? 'error'}: ${error.message}`);
+  const body = { ok: false, code: error.code ?? 'xero_failed', error: status === 500 && !(error instanceof FlowError) ? 'Something went wrong talking to Xero.' : error.message };
+  if (error.details !== undefined) body.details = error.details;
+  if (error.retryAfterMs) res.set('Retry-After', String(Math.ceil(error.retryAfterMs / 1000)));
+  return res.status(status).json(body);
+}
+
+function requireInvoiceIds(raw, name = 'invoiceIds') {
+  if (!Array.isArray(raw) || !raw.length || raw.length > MAX_BATCH || !raw.every((id) => typeof id === 'string' && UUID.test(id))) {
+    throw new FlowError('invalid', `${name} must list 1 to ${MAX_BATCH} Flow invoice ids`);
+  }
+  return [...new Set(raw)];
+}
+
+export async function requireOrganisation(db, raw) {
+  const organisationId = typeof raw === 'string' ? raw.trim() : '';
+  if (!UUID.test(organisationId)) throw new FlowError('invalid', 'organisationId must be a Flow organisation id');
+  const [row] = await db.select({ id: organisations.id }).from(organisations).where(eq(organisations.id, organisationId));
+  if (!row) throw Object.assign(new FlowError('not_found', 'organisation not found'), { status: 404 });
+  return organisationId;
+}
+
+// Wraps an async handler so a thrown error becomes a JSON answer.
+export const handle = (log, fn) => async (req, res) => {
+  try {
+    await fn(req, res);
+  } catch (error) {
+    sendError(res, error, log);
+  }
+};
+
+export function createXeroRouter({ db, personAuth, runtime, log = console }) {
+  const { settings } = runtime;
+  const router = express.Router();
+  router.use(express.json({ limit: '256kb' }));
+
+  // Sign-in off: nothing but the callback answers, and it fails for want of
+  // a state.
+  const signedIn = personAuth
+    ? [personAuth.requireSession]
+    : [(_req, res) => res.status(503).json({ ok: false, code: 'sign_in_not_configured', error: 'Sign-in is not configured on this installation (FLOW_AUTH is unset).' })];
+  const owner = personAuth ? [...signedIn, personAuth.requireOwner] : signedIn;
+  const manager = personAuth ? [...signedIn, personAuth.requireRole('owner', 'admin')] : signedIn;
+
+  router.get('/status', ...signedIn, handle(log, async (req, res) => {
+    const organisationId = await requireOrganisation(db, req.query.organisationId);
+    const connection = await readConnection(db, organisationId);
+    res.json({
+      ok: true,
+      mode: settings.mode,
+      writesAllowed: writesAllowed(settings),
+      redirectUri: settings.redirectUri,
+      connected: Boolean(connection && connection.mode === settings.mode),
+      connection: describeConnection(connection),
+      rateLimit: connection ? runtime.governor.status(connection.tenantId) : null,
+      lastSync: await lastSync(db, organisationId),
+    });
+  }));
+
+  router.post('/connect', ...owner, handle(log, async (req, res) => {
+    const organisationId = await requireOrganisation(db, req.body?.organisationId);
+    if (!settings.redirectUri) {
+      throw Object.assign(new FlowError('xero_redirect_uri_missing', 'Set FLOW_PUBLIC_ORIGIN (or XERO_REDIRECT_URI) to this installation\'s address, and register its /api/xero/oauth/callback on the Xero app.'), { status: 503 });
+    }
+    const state = runtime.states.issue({ organisationId, personId: req.person.id });
+    res.json({ ok: true, authorizeUrl: authorizeUrl(settings, state), redirectUri: settings.redirectUri, mode: settings.mode });
+  }));
+
+  router.get('/oauth/callback', async (req, res) => {
+    res.set('Cache-Control', 'no-store');
+    const entry = runtime.states.consume(req.query.state);
+    if (!entry) {
+      return res.status(400).type('html').send(page('Xero was not connected', 'This approval link has expired or was already used. Start again from Flow.'));
+    }
+    if (req.query.error) {
+      return res.status(400).type('html').send(page('Xero was not connected', 'The approval was cancelled in Xero. Start again from Flow if you meant to connect.'));
+    }
+    try {
+      const tokens = await exchangeCode(settings, runtime.transport, typeof req.query.code === 'string' ? req.query.code : '');
+      const connections = await fetchConnections(settings, runtime.transport, tokens.access_token);
+      let chosen;
+      try {
+        chosen = selectConnection(connections, settings);
+        const probe = createXeroClient({
+          tenantId: chosen.tenantId,
+          accessToken: async () => tokens.access_token,
+          fetch: runtime.transport,
+          governor: runtime.governor,
+          apiBase: settings.endpoints.api,
+          log,
+        });
+        await runtime.assertEnvironment(probe);
+      } catch (error) {
+        // Refused: Xero keeps no grant for an organisation Flow will not use.
+        await revokeToken(settings, runtime.transport, tokens.refresh_token).catch(() => false);
+        throw error;
+      }
+      const connection = await saveConnection(db, {
+        organisationId: entry.organisationId,
+        mode: settings.mode,
+        tenantId: chosen.tenantId,
+        tenantName: chosen.tenantName ?? null,
+        scope: tokens.scope ?? settings.scope,
+        refreshToken: tokens.refresh_token,
+        connectedBy: entry.personId,
+        key: settings.tokenKey,
+      });
+      runtime.remember(entry.organisationId, tokens);
+      log.info?.(`[xero] organisation ${entry.organisationId} connected to Xero tenant ${connection.tenantId} (${settings.mode}) by person ${entry.personId}`);
+      return res.type('html').send(page('Xero is connected', `Flow is connected to ${connection.tenantName || 'your Xero organisation'} (${settings.mode}). You can close this tab.`));
+    } catch (error) {
+      log.error?.(`[xero] connect failed: ${error.code ?? 'error'}: ${error.message}`);
+      const message = error instanceof FlowError ? error.message : 'Something went wrong talking to Xero. Try again.';
+      return res.status(error.status && error.status < 500 ? error.status : 502).type('html').send(page('Xero was not connected', message));
+    }
+  });
+
+  router.post('/disconnect', ...owner, handle(log, async (req, res) => {
+    const organisationId = await requireOrganisation(db, req.body?.organisationId);
+    const connection = await readConnection(db, organisationId);
+    if (!connection) return res.json({ ok: true, disconnected: false });
+    let revoked = false;
+    try {
+      revoked = await revokeToken(settings, runtime.transport, decryptToken(connection.refreshTokenEnc, settings.tokenKey, organisationId));
+    } catch (error) {
+      log.warn?.(`[xero] could not revoke the Xero token for organisation ${organisationId}: ${error.code ?? 'error'}`);
+    }
+    await deleteConnection(db, organisationId);
+    runtime.forget(organisationId);
+    log.info?.(`[xero] organisation ${organisationId} disconnected from Xero by person ${req.person.id}`);
+    return res.json({ ok: true, disconnected: true, revoked });
+  }));
+
+  router.post('/sync', ...manager, handle(log, async (req, res) => {
+    const organisationId = await requireOrganisation(db, req.body?.organisationId);
+    const run = await syncCatalogue(db, runtime, organisationId, { startedBy: req.person.id });
+    res.json({ ok: true, sync: run });
+  }));
+
+  router.get('/contacts', ...signedIn, handle(log, async (req, res) => {
+    const organisationId = await requireOrganisation(db, req.query.organisationId);
+    res.json({ ok: true, contacts: await listContacts(db, organisationId, { q: typeof req.query.q === 'string' ? req.query.q : '' }) });
+  }));
+
+  router.get('/items', ...signedIn, handle(log, async (req, res) => {
+    const organisationId = await requireOrganisation(db, req.query.organisationId);
+    res.json({ ok: true, items: await listItems(db, organisationId) });
+  }));
+
+  router.post('/invoices/preview', ...signedIn, handle(log, async (req, res) => {
+    const organisationId = await requireOrganisation(db, req.body?.organisationId);
+    const preview = await previewDrafts(db, runtime, organisationId, requireInvoiceIds(req.body?.invoiceIds));
+    res.json({ ok: true, mode: settings.mode, writesAllowed: writesAllowed(settings), ...preview });
+  }));
+
+  router.post('/invoices/push', ...manager, handle(log, async (req, res) => {
+    const organisationId = await requireOrganisation(db, req.body?.organisationId);
+    const invoiceIds = requireInvoiceIds(req.body?.invoiceIds);
+    const allowExistingReference = req.body?.allowExistingReference === undefined ? [] : requireInvoiceIds(req.body.allowExistingReference, 'allowExistingReference');
+    const result = await pushDrafts(db, runtime, organisationId, invoiceIds, { pushedBy: req.person.id, allowExistingReference });
+    log.info?.(`[xero] organisation ${organisationId}: person ${req.person.id} sent ${invoiceIds.length} invoice(s) to Xero: ${JSON.stringify(result.summary)}`);
+    res.json({ ok: true, ...result });
+  }));
+
+  router.get('/invoices/:invoiceId/pushes', ...signedIn, handle(log, async (req, res) => {
+    const organisationId = await requireOrganisation(db, req.query.organisationId);
+    const [invoiceId] = requireInvoiceIds([req.params.invoiceId], 'invoiceId');
+    res.json({ ok: true, pushes: (await listPushes(db, organisationId, invoiceId)).map(describePush) });
+  }));
+
+  router.post('/obligations/:obligationId/check', ...manager, handle(log, async (req, res) => {
+    const organisationId = await requireOrganisation(db, req.body?.organisationId);
+    const [obligationId] = requireInvoiceIds([req.params.obligationId], 'obligationId');
+    const [obligation] = await db.select().from(billingObligations)
+      .where(and(eq(billingObligations.organisationId, organisationId), eq(billingObligations.id, obligationId)));
+    if (!obligation) throw Object.assign(new FlowError('not_found', 'obligation not found'), { status: 404 });
+    const row = await recordXeroEvidence(db, runtime, organisationId, obligation, { actor: `person:${req.person.id}` });
+    res.json({ ok: true, obligation: row });
+  }));
+
+  router.post('/payments/sync', ...manager, handle(log, async (req, res) => {
+    const organisationId = await requireOrganisation(db, req.body?.organisationId);
+    const result = await recordXeroPayments(db, runtime, organisationId, { actor: `person:${req.person.id}` });
+    res.json({ ok: true, ...result });
+  }));
+
+  return router;
+}