@arcforgelabs/flow 2026.10.36 → 2026.10.38

package/server/integrations/xero/links.js

@@ -0,0 +1,293 @@
+import { and, eq, sql } from 'drizzle-orm';
+import { contacts, priceItems } from '../../db/schema.js';
+import { createContact } from '../../core/directory.js';
+import { FlowError } from '../../core/errors.js';
+import { createDraftInvoice, issueInvoice } from '../../core/invoices.js';
+import { linkJobToInvoice } from '../../core/ledger.js';
+import { normaliseName } from './catalogue.js';
+import { canFit, markRivals, scoreFit, sureFits } from './fit.js';
+
+// The Import page (docs/XERO_IMPORT.md): each sales invoice in Flow's copy of
+// Xero against Flow's own invoices. Flow's own records are the ones it works
+// from; this integration says which Flow invoice each Xero invoice is.
+//
+//   linked        a Flow invoice is this Xero invoice: Flow sent it (a push),
+//                 the import matched it, or a person linked or made it.
+//   invoice_fits  a Flow invoice with no Xero invoice fits (fit.js: hard
+//                 evidence from its jobs, or the same client, an amount that
+//                 fits and dates within two weeks). A sure fit is linked by
+//                 `matchXero`; the rest wait for a person.
+//   job_fits      no Flow invoice, but a Flow job with no invoice fits: the
+//                 earlier matcher tied it to this Xero invoice, its work-system
+//                 invoice number is this Xero number, or it has the
+//                 same client and total within a week. A person makes the Flow
+//                 invoice from the Xero one and links the job.
+//   none          nothing in Flow fits. The Xero invoice stays in the copy; a
+//                 person can make its Flow invoice at any time, or the
+//                 `make_unmatched` setting makes one for each.
+//
+// It reads only Flow's database: no Xero call.
+
+export const IMPORT_STATES = Object.freeze(['linked', 'invoice_fits', 'job_fits', 'none']);
+const CHECK = new Set(['invoice_fits', 'job_fits']);
+const FIT_DAYS = 7;
+const SKIP_STATUSES = ['DELETED', 'VOIDED'];
+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 daysApart = (a, b) => (a && b ? Math.abs(Math.round((Date.parse(a) - Date.parse(b)) / 86_400_000)) : null);
+const near = (a, b) => {
+  const days = daysApart(a, b);
+  return days !== null && days <= FIT_DAYS;
+};
+
+// Every sales invoice in the copy, and what in Flow fits it.
+async function classify(db, organisationId) {
+  const { rows: xero } = await db.execute(sql`
+    select x.xero_invoice_id, x.invoice_number, x.reference, x.status, x.issued_on, x.total_cents, x.amount_due_cents,
+      x.xero_contact_id, x.lines, c.name as contact_name, c.email as contact_email
+    from xero_invoices x
+    left join xero_contacts c on c.organisation_id = x.organisation_id and c.xero_contact_id = x.xero_contact_id
+    where x.organisation_id = ${organisationId} and x.type = 'ACCREC'
+      and not (x.status = any(${sql.param(SKIP_STATUSES)}::text[]))
+    order by x.issued_on desc nulls last, x.invoice_number desc`);
+  const { rows: linkRows } = await db.execute(sql`
+    select xero_invoice_id, invoice_id, 'sent' as matched_by from xero_invoice_pushes
+      where organisation_id = ${organisationId} and xero_invoice_id is not null
+    union all
+    select xero_invoice_id, invoice_id, matched_by from xero_invoice_links where organisation_id = ${organisationId}`);
+  const linkOf = new Map();
+  const linkedInvoices = new Set();
+  for (const r of linkRows) {
+    if (!linkOf.has(r.xero_invoice_id)) linkOf.set(r.xero_invoice_id, r);
+    linkedInvoices.add(r.invoice_id);
+  }
+  // Flow's customers by name, as the drafts match them (only a name with one
+  // contact counts).
+  const people = await db.select({ id: contacts.id, name: contacts.name }).from(contacts)
+    .where(and(eq(contacts.organisationId, organisationId), eq(contacts.kind, 'customer')));
+  const byName = new Map();
+  for (const p of people) {
+    const key = normaliseName(p.name);
+    byName.set(key, byName.has(key) ? null : p.id);
+  }
+  const { rows: flowInvoices } = await db.execute(sql`
+    select i.id, i.number, i.contact_id, i.total_cents, i.subtotal_cents, i.reference, i.status, coalesce(i.issue_date, i.created_at::date) as date,
+      coalesce((select array_agg(distinct p.code) from invoice_lines l join price_items p on p.id = l.price_item_id
+        where l.invoice_id = i.id and p.code is not null), '{}') as item_codes,
+      coalesce((select jsonb_agg(jsonb_build_object('accountingRef', o.accounting_ref, 'sourceInvoiceRef', o.source_invoice_ref, 'practitioner', o.practitioner))
+        from billing_obligations o where o.organisation_id = i.organisation_id and o.invoice_id = i.id), '[]') as jobs
+    from invoices i
+    where i.organisation_id = ${organisationId} and i.status <> 'void'`);
+  const open = flowInvoices.filter((i) => !linkedInvoices.has(i.id));
+  const { rows: jobs } = await db.execute(sql`
+    select o.id, o.contact_id, o.total_cents, o.job_date, o.practitioner, o.case_ref, o.accounting_ref, o.source_invoice_ref, o.lines
+    from billing_obligations o
+    where o.organisation_id = ${organisationId} and o.invoice_id is null`);
+  const jobByRef = new Map(jobs.filter((j) => j.accounting_ref).map((j) => [j.accounting_ref, j]));
+  // The work system's own invoice number, as Xero numbers it (a trailing R is
+  // a reissue). Only a number one job holds counts.
+  const workNumber = (ref) => String(ref ?? '').trim().replace(/R$/i, '').toLowerCase();
+  const jobByNumber = new Map();
+  for (const j of jobs) {
+    if (!j.source_invoice_ref) continue;
+    const key = workNumber(j.source_invoice_ref);
+    jobByNumber.set(key, jobByNumber.has(key) ? null : j);
+  }
+
+  const rows = xero.map((x) => {
+    const contactId = x.contact_name ? byName.get(normaliseName(x.contact_name)) ?? null : null;
+    const row = {
+      xeroInvoiceId: x.xero_invoice_id,
+      number: x.invoice_number,
+      reference: x.reference,
+      status: x.status,
+      issuedOn: day(x.issued_on),
+      totalCents: num(x.total_cents),
+      amountDueCents: num(x.amount_due_cents),
+      clientName: x.contact_name,
+      contactId,
+      link: null,
+      invoices: [],
+      jobs: [],
+    };
+    const link = linkOf.get(x.xero_invoice_id);
+    if (link) {
+      const invoice = flowInvoices.find((i) => i.id === link.invoice_id);
+      row.link = { invoiceId: link.invoice_id, number: invoice?.number ?? null, matchedBy: link.matched_by };
+      return { ...row, state: 'linked' };
+    }
+    row.itemCodes = [...new Set((x.lines ?? []).map((l) => l.itemCode).filter(Boolean))];
+    const xeroFit = { id: x.xero_invoice_id, number: x.invoice_number, contactId, totalCents: row.totalCents, issuedOn: row.issuedOn,
+      itemCodes: (x.lines ?? []).map((l) => l.itemCode).filter(Boolean), reference: x.reference };
+    row.invoices = open.map((i) => {
+      const flowFit = { id: i.id, contactId: i.contact_id, totalCents: num(i.total_cents), subtotalCents: num(i.subtotal_cents), date: day(i.date),
+        itemCodes: i.item_codes ?? [], reference: i.reference, jobs: i.jobs ?? [] };
+      const scored = scoreFit(xeroFit, flowFit);
+      return canFit(xeroFit, flowFit, scored)
+        ? { id: i.id, number: i.number, status: i.status, date: day(i.date), totalCents: num(i.total_cents), reference: i.reference, itemCodes: flowFit.itemCodes,
+          score: scored.score, hard: scored.hard, apart: daysApart(day(i.date), row.issuedOn) ?? 99 }
+        : null;
+    }).filter(Boolean);
+    const tied = jobByRef.get(x.xero_invoice_id) ?? (x.invoice_number ? jobByNumber.get(workNumber(x.invoice_number)) : null) ?? null;
+    const fits = tied ? [tied] : contactId
+      ? jobs.filter((j) => !j.accounting_ref && j.contact_id === contactId && num(j.total_cents) === row.totalCents && near(day(j.job_date), row.issuedOn))
+      : [];
+    row.jobs = fits.map((j) => ({ id: j.id, jobDate: day(j.job_date), practitioner: j.practitioner, caseRef: j.case_ref, totalCents: num(j.total_cents), tied: j === tied,
+      itemCodes: [...new Set((j.lines ?? []).map((l) => l.itemCode).filter(Boolean))] }));
+    return row;
+  });
+  // A Flow invoice dated closer to another Xero invoice more likely is that
+  // one (the job matcher's closer_job lesson): those fits lose points.
+  markRivals(rows.flatMap((r) => r.invoices.map((i) => ({ xeroId: r.xeroInvoiceId, flowId: i.id, apart: i.apart, fit: i }))));
+  for (const r of rows) {
+    if (r.state === 'linked') continue;
+    r.invoices.sort((a, b) => b.score - a.score);
+    const hard = r.invoices.some((i) => i.hard);
+    const tiedJob = r.jobs.some((j) => j.tied);
+    const plain = r.invoices.some((i) => !i.rival);
+    // Hard evidence wins; a job tied to this Xero invoice beats a plain fit;
+    // a Flow invoice that is closer to another Xero invoice yields to a job.
+    if (hard || (!tiedJob && (plain || !r.jobs.length) && r.invoices.length)) r.state = 'invoice_fits';
+    else if (r.jobs.length) {
+      r.state = 'job_fits';
+      r.invoices = [];
+    } else r.state = 'none';
+    if (r.state === 'invoice_fits') r.jobs = [];
+  }
+  // Sure only when it is clearly the one fit both ways (fit.js).
+  const sure = sureFits(rows.filter((r) => r.state === 'invoice_fits')
+    .flatMap((r) => r.invoices.map((i) => ({ xeroId: r.xeroInvoiceId, flowId: i.id, score: i.score, hard: i.hard }))));
+  for (const r of rows) {
+    r.sure = r.state === 'invoice_fits' && sure.has(r.xeroInvoiceId);
+    if (r.sure) r.invoices.sort((a, b) => (b.id === sure.get(r.xeroInvoiceId)) - (a.id === sure.get(r.xeroInvoiceId)));
+    for (const i of r.invoices) { delete i.apart; delete i.rival; }
+  }
+  return rows;
+}
+
+const matches = (row, q) => {
+  const words = q.trim().toLowerCase();
+  if (!words) return true;
+  const amount = /^\$?\s*(\d+(?:,\d{3})*(?:\.\d{1,2})?)$/.exec(words);
+  if (amount && row.totalCents === Math.round(Number(amount[1].replace(/,/g, '')) * 100)) return true;
+  return [row.number, row.clientName, row.reference].some((v) => v && String(v).toLowerCase().includes(words));
+};
+
+// The page: counts by state, and one page of rows. `show` is a state, 'check'
+// (what a person checks: a Flow invoice or a job fits), or 'all'; `q`
+// searches number, client, Reference or amount.
+export async function importOverview(db, organisationId, { show = 'all', q = '', limit = 50, offset = 0 } = {}) {
+  const rows = await classify(db, organisationId);
+  const counts = Object.fromEntries(IMPORT_STATES.map((s) => [s, 0]));
+  for (const r of rows) counts[r.state] += 1;
+  const shown = rows.filter((r) => (show === 'all' || r.state === show || (show === 'check' && CHECK.has(r.state))) && matches(r, q));
+  const settings = await readImportSettings(db, organisationId);
+  return { counts, total: shown.length, rows: shown.slice(offset, offset + limit), settings };
+}
+
+// `autoLink` (on): the import links each sure fit. `makeUnmatched` (off):
+// it also makes a Flow invoice for each Xero invoice nothing fits.
+export async function readImportSettings(db, organisationId) {
+  const { rows } = await db.execute(sql`select auto_link, make_unmatched from xero_import_settings where organisation_id = ${organisationId}`);
+  return { autoLink: rows[0] ? Boolean(rows[0].auto_link) : true, makeUnmatched: Boolean(rows[0]?.make_unmatched) };
+}
+
+// Saves the settings given; a setting left out keeps its value.
+export async function saveImportSettings(db, organisationId, { autoLink, makeUnmatched, actor }) {
+  for (const [name, value] of [['autoLink', autoLink], ['makeUnmatched', makeUnmatched]]) {
+    if (value !== undefined && typeof value !== 'boolean') throw new FlowError('invalid', `${name} must be true or false`);
+  }
+  const next = { ...(await readImportSettings(db, organisationId)) };
+  if (autoLink !== undefined) next.autoLink = autoLink;
+  if (makeUnmatched !== undefined) next.makeUnmatched = makeUnmatched;
+  await db.execute(sql`insert into xero_import_settings (organisation_id, auto_link, make_unmatched, updated_by, updated_at)
+    values (${organisationId}, ${next.autoLink}, ${next.makeUnmatched}, ${actor}, now())
+    on conflict (organisation_id) do update set auto_link = excluded.auto_link, make_unmatched = excluded.make_unmatched,
+      updated_by = excluded.updated_by, updated_at = now()`);
+  return readImportSettings(db, organisationId);
+}
+
+async function insertLink(db, organisationId, { xeroInvoiceId, invoiceId, matchedBy, actor }) {
+  const { rows } = await db.execute(sql`insert into xero_invoice_links (organisation_id, xero_invoice_id, invoice_id, matched_by, linked_by)
+    values (${organisationId}, ${xeroInvoiceId}, ${invoiceId}, ${matchedBy}, ${actor})
+    on conflict do nothing returning xero_invoice_id`);
+  if (!rows.length) throw new FlowError('invalid', 'the Xero invoice or the Flow invoice is linked already');
+}
+
+async function rowFor(db, organisationId, xeroInvoiceId) {
+  const row = (await classify(db, organisationId)).find((r) => r.xeroInvoiceId === xeroInvoiceId);
+  if (!row) throw new FlowError('not_found', 'Xero invoice not found in the copy');
+  if (row.state === 'linked') throw new FlowError('invalid', 'the Xero invoice is linked already');
+  return row;
+}
+
+// A person says which Flow invoice a Xero invoice is. Any Flow invoice of the
+// same client with no Xero invoice may be picked, not only a fit.
+export async function linkXeroInvoice(db, organisationId, xeroInvoiceId, { invoiceId, actor }) {
+  await rowFor(db, organisationId, xeroInvoiceId);
+  const { rows } = await db.execute(sql`select id, status from invoices where organisation_id = ${organisationId} and id = ${invoiceId}`);
+  if (!rows.length) throw new FlowError('not_found', 'Flow invoice not found');
+  if (rows[0].status === 'void') throw new FlowError('invalid', 'the Flow invoice is void');
+  const { rows: pushed } = await db.execute(sql`select 1 from xero_invoice_pushes where organisation_id = ${organisationId} and invoice_id = ${invoiceId} and xero_invoice_id is not null limit 1`);
+  if (pushed.length) throw new FlowError('invalid', 'Flow sent that invoice to Xero already');
+  await insertLink(db, organisationId, { xeroInvoiceId, invoiceId, matchedBy: 'person', actor });
+  return { xeroInvoiceId, invoiceId };
+}
+
+// Makes Flow's own invoice from a Xero invoice in the copy, finalised on the
+// Xero invoice's date, and links the two. With `jobId`, the job gets it as its
+// invoice. The client is Flow's customer of the same name, or a new one.
+// Lines keep the Xero item code where Flow's price list has it; Flow works
+// out its own totals from the lines.
+export async function makeFlowInvoice(db, organisationId, xeroInvoiceId, { jobId = null, actor }) {
+  return makeFrom(db, organisationId, await rowFor(db, organisationId, xeroInvoiceId), { jobId, actor });
+}
+
+async function makeFrom(db, organisationId, row, { jobId = null, actor }) {
+  const { xeroInvoiceId } = row;
+  const { rows: [x] } = await db.execute(sql`select x.lines, x.due_on, c.email from xero_invoices x
+    left join xero_contacts c on c.organisation_id = x.organisation_id and c.xero_contact_id = x.xero_contact_id
+    where x.organisation_id = ${organisationId} and x.xero_invoice_id = ${xeroInvoiceId}`);
+  if (!row.clientName) throw new FlowError('invalid', 'the Xero invoice has no contact in the copy; sync contacts first');
+  return db.transaction(async (tx) => {
+    const contactId = row.contactId ?? (await createContact(tx, organisationId, { kind: 'customer', name: row.clientName, email: x.email ?? null })).id;
+    const items = await tx.select({ id: priceItems.id, code: priceItems.code, name: priceItems.name }).from(priceItems)
+      .where(eq(priceItems.organisationId, organisationId));
+    const byCode = new Map(items.map((i) => [i.code.toUpperCase(), i]));
+    const lines = (x.lines ?? []).filter((l) => l.lineAmountCents).map((l) => {
+      const item = l.itemCode ? byCode.get(String(l.itemCode).toUpperCase()) : null;
+      const whole = Number.isInteger(l.quantity) && l.quantity > 0 && l.lineAmountCents % l.quantity === 0;
+      return {
+        priceItemId: item?.id ?? null,
+        accountCode: item ? null : l.accountCode ?? null,
+        description: l.description ?? item?.name ?? l.itemCode ?? 'Line from Xero',
+        quantity: whole ? l.quantity : 1,
+        unitAmountCents: whole ? l.lineAmountCents / l.quantity : l.lineAmountCents,
+        taxCode: l.taxAmountCents ? 'GST' : 'GST_FREE',
+      };
+    });
+    if (!lines.length) throw new FlowError('invalid', 'the Xero invoice has no lines in the copy');
+    const draft = await createDraftInvoice(tx, organisationId, { contactId, reference: row.reference ?? null, dueDate: day(x.due_on), lines });
+    const invoice = await issueInvoice(tx, organisationId, draft.id, { issuedBy: actor, issueDate: row.issuedOn ?? new Date().toISOString().slice(0, 10) });
+    await insertLink(tx, organisationId, { xeroInvoiceId, invoiceId: invoice.id, matchedBy: 'made', actor });
+    if (jobId) await linkJobToInvoice(tx, organisationId, jobId, { invoiceId: invoice.id, accountingRef: xeroInvoiceId, actor });
+    return { xeroInvoiceId, invoice };
+  });
+}
+
+// With `autoLink` on, links each sure fit; with `makeUnmatched` on, makes a Flow invoice for
+// each Xero invoice nothing fits. Answers counts. The history import runs it
+// after each read of the copy; a person can run it from the page.
+export async function matchXero(db, organisationId, { actor = 'automation:xero-import' } = {}) {
+  const rows = await classify(db, organisationId);
+  const { autoLink, makeUnmatched } = await readImportSettings(db, organisationId);
+  const result = { linked: 0, made: 0, failed: 0 };
+  for (const row of rows) {
+    if (row.sure && autoLink) {
+      await insertLink(db, organisationId, { xeroInvoiceId: row.xeroInvoiceId, invoiceId: row.invoices[0].id, matchedBy: 'auto', actor }).then(() => { result.linked += 1; }, () => { result.failed += 1; });
+    } else if (makeUnmatched && row.state === 'none') {
+      await makeFrom(db, organisationId, row, { actor }).then(() => { result.made += 1; }, () => { result.failed += 1; });
+    }
+  }
+  return result;
+}

package/server/integrations/xero/migrations/0008_xero_invoice_links.sql

@@ -0,0 +1,26 @@
+-- Which Flow invoice each Xero invoice is (the Import page, xero/links.js). A
+-- Flow invoice that Flow sent to Xero is linked by its push already; this
+-- table holds the others: matched by the import (`auto`), picked by a person
+-- (`person`), or a Flow invoice made from the Xero invoice (`made`). One Flow
+-- invoice per Xero invoice, and one Xero invoice per Flow invoice.
+CREATE TABLE IF NOT EXISTS "xero_invoice_links" (
+	"organisation_id" uuid NOT NULL REFERENCES "organisations"("id"),
+	"xero_invoice_id" text NOT NULL,
+	"invoice_id" uuid NOT NULL,
+	"matched_by" text NOT NULL,
+	"linked_by" text NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "xero_invoice_links_pk" PRIMARY KEY("organisation_id", "xero_invoice_id"),
+	CONSTRAINT "xero_invoice_links_invoice" UNIQUE("organisation_id", "invoice_id"),
+	CONSTRAINT "xero_invoice_links_invoice_same_org" FOREIGN KEY ("organisation_id", "invoice_id") REFERENCES "invoices"("organisation_id", "id"),
+	CONSTRAINT "xero_invoice_links_matched_by_valid" CHECK ("matched_by" in ('auto', 'person', 'made'))
+);
+--> statement-breakpoint
+-- The Import page's settings, one row for each organisation.
+CREATE TABLE IF NOT EXISTS "xero_import_settings" (
+	"organisation_id" uuid PRIMARY KEY NOT NULL REFERENCES "organisations"("id"),
+	"auto_link" boolean DEFAULT true NOT NULL,
+	"make_unmatched" boolean DEFAULT false NOT NULL,
+	"updated_by" text,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);

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

@@ -57,6 +57,13 @@
       "when": 1792500000000,
       "tag": "0007_xero_webhooks",
       "breakpoints": true
+    },
+    {
+      "idx": 8,
+      "version": "7",
+      "when": 1792510000000,
+      "tag": "0008_xero_invoice_links",
+      "breakpoints": true
     }
   ]
 }

package/server/integrations/xero/reconcile.js

@@ -51,8 +51,7 @@ const day = (value) => (value instanceof Date ? value.toISOString().slice(0, 10)
 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).
+// (reference, descriptions) is not compared yet.
 export function sentDifferences(sent, document, copy) {
   const found = [];
   const add = (field, flow, xero) => found.push({ field, flow, xero });
@@ -90,12 +89,12 @@ const MESSAGES = {
 // 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`;
+  // Without ids: only invoices Flow sent or linked, for the check after each read.
+  const sentOnly = invoiceIds ? sql`` : sql`and (p.id is not null or l.xero_invoice_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,
+      v.document, l.xero_invoice_id as linked_xero_id, l.matched_by as linked_by,
       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
@@ -105,13 +104,17 @@ export async function accountingStatus(db, runtime, organisationId, invoiceIds =
       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
+    -- A Flow invoice the Import page linked to a Xero invoice (links.js).
+    left join xero_invoice_links l on l.organisation_id = i.organisation_id and l.invoice_id = i.id
+    left join xero_invoices x on x.organisation_id = i.organisation_id and x.xero_invoice_id = coalesce(p.xero_invoice_id, l.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';
+    const linked = !r.push_state && Boolean(r.linked_xero_id);
+    if (linked) state = r.x_status ? xeroState({ status: r.x_status, amount_paid_cents: r.amount_paid_cents }) : 'not_copied';
+    else 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 });
@@ -121,23 +124,26 @@ export async function accountingStatus(db, runtime, organisationId, invoiceIds =
     } catch {
       sent = null;
     }
+    const xeroInvoiceId = r.xero_invoice_id ?? r.linked_xero_id;
     const xero = r.x_status ? {
-      invoiceId: r.xero_invoice_id,
+      invoiceId: xeroInvoiceId,
       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)}`,
+      url: `${web}/AccountsReceivable/View.aspx?InvoiceID=${encodeURIComponent(xeroInvoiceId)}`,
     } : 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,
+      // A linked invoice was never sent: it is the Xero invoice, as it stands.
+      current: linked || (r.sent_version !== null && r.sent_version === r.issued_version),
+      linkedBy: linked ? r.linked_by : null,
       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 }) : [],
+      differences: !linked && 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);

package/server/integrations/xero/routes.js

@@ -6,6 +6,7 @@ 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 { IMPORT_STATES, importOverview, linkXeroInvoice, makeFlowInvoice, matchXero, saveImportSettings } from './links.js';
 import { queueHistoryImport, resetImport } from './import.js';
 import { MIRROR_RESOURCES, mirrorStatus, mirrorXero } from './mirror.js';
 import { accountingStatus, checkSentInvoices } from './reconcile.js';
@@ -307,5 +308,46 @@ export function createXeroRouter({ db, personAuth, runtime, log = console, messa
     res.json({ ok: true, ...(await mirrorStatus(db, organisationId)) });
   }));
 
+  // The Import page (links.js): each Xero sales invoice in Flow's copy against
+  // Flow's own invoices. Reads Flow's database only.
+  router.get('/import', ...signedIn, handle(log, async (req, res) => {
+    const organisationId = await requireOrganisation(db, req.query.organisationId);
+    const show = typeof req.query.show === 'string' && [...IMPORT_STATES, 'check', 'all'].includes(req.query.show) ? req.query.show : 'all';
+    const q = typeof req.query.q === 'string' ? req.query.q.slice(0, 200) : '';
+    const offset = Math.max(0, Math.min(Number.parseInt(req.query.offset, 10) || 0, 1_000_000));
+    const limit = Math.max(1, Math.min(Number.parseInt(req.query.limit, 10) || 50, 100));
+    res.json({ ok: true, ...(await importOverview(db, organisationId, { show, q, limit, offset })) });
+  }));
+
+  router.post('/import/match', ...manager, handle(log, async (req, res) => {
+    const organisationId = await requireOrganisation(db, req.body?.organisationId);
+    const result = await matchXero(db, organisationId, { actor: `person:${req.person.id}` });
+    log.info?.(`[xero] organisation ${organisationId}: person ${req.person.id} matched Xero invoices: ${JSON.stringify(result)}`);
+    res.json({ ok: true, ...result });
+  }));
+
+  router.put('/import/settings', ...manager, handle(log, async (req, res) => {
+    const organisationId = await requireOrganisation(db, req.body?.organisationId);
+    res.json({ ok: true, settings: await saveImportSettings(db, organisationId, { autoLink: req.body?.autoLink, makeUnmatched: req.body?.makeUnmatched, actor: `person:${req.person.id}` }) });
+  }));
+
+  const xeroId = (raw) => {
+    if (typeof raw !== 'string' || !UUID.test(raw)) throw Object.assign(new FlowError('not_found', 'Xero invoice not found'), { status: 404 });
+    return raw;
+  };
+
+  router.post('/import/:xeroInvoiceId/link', ...manager, handle(log, async (req, res) => {
+    const organisationId = await requireOrganisation(db, req.body?.organisationId);
+    const [invoiceId] = requireInvoiceIds([req.body?.invoiceId], 'invoiceId');
+    res.json({ ok: true, ...(await linkXeroInvoice(db, organisationId, xeroId(req.params.xeroInvoiceId), { invoiceId, actor: `person:${req.person.id}` })) });
+  }));
+
+  router.post('/import/:xeroInvoiceId/make', ...manager, handle(log, async (req, res) => {
+    const organisationId = await requireOrganisation(db, req.body?.organisationId);
+    const jobId = req.body?.jobId == null ? null : requireInvoiceIds([req.body.jobId], 'jobId')[0];
+    const { invoice } = await makeFlowInvoice(db, organisationId, xeroId(req.params.xeroInvoiceId), { jobId, actor: `person:${req.person.id}` });
+    res.json({ ok: true, invoice: { id: invoice.id, number: invoice.number } });
+  }));
+
   return router;
 }

package/server/integrations/xero/settings.js

@@ -11,6 +11,8 @@
 //   replay   no network: recorded, synthetic Xero responses
 //            (server/integrations/xero/fixtures). Development and CI.
 
+import { backgroundJobsOn } from '../../core/host.js';
+
 export const XERO_MODES = Object.freeze(['live', 'sandbox', 'replay']);
 
 // Xero's own public endpoints. They are the same for every installation.
@@ -36,9 +38,10 @@ function readEnv(env, name) {
   return typeof value === 'string' ? value.trim() : '';
 }
 
-function readOnOff(env, name) {
+function readOnOff(env, name, fallback = false) {
   const raw = readEnv(env, name).toLowerCase();
-  if (raw === '' || raw === 'off') return false;
+  if (raw === '') return fallback;
+  if (raw === 'off') return false;
   if (raw === 'on') return true;
   throw new Error(`${name} must be "on", "off" or unset`);
 }
@@ -154,6 +157,9 @@ export function resolveXeroSettings(env = process.env) {
     tenantId,
     tenantName,
     liveWrites: readOnOff(env, 'XERO_ALLOW_LIVE_WRITES'),
+    // Off in a Replit workspace (server/core/host.js): no history read and
+    // no writes, whatever XERO_ALLOW_LIVE_WRITES says.
+    backgroundJobs: backgroundJobsOn(env),
     dayLimit: readPositiveInteger(env, 'XERO_DAY_LIMIT', DEFAULT_XERO_DAY_LIMIT),
     usageWarningFraction: readFraction(env, 'XERO_USAGE_WARNING_FRACTION', 0.7),
     taxTypes: resolveTaxTypes(env),
@@ -161,9 +167,9 @@ export function resolveXeroSettings(env = process.env) {
     defaultDueDays: readPositiveInteger(env, 'XERO_DEFAULT_DUE_DAYS', DEFAULT_DUE_DAYS),
     invoiceNumber,
     replayFixtures: readEnv(env, 'XERO_REPLAY_FIXTURES') || null,
-    // Free text on Xero records (references, line descriptions) can name a
-    // patient. Flow keeps it only when the lab turns this on (VISION.md).
-    keepReference: readOnOff(env, 'XERO_KEEP_REFERENCE'),
+    // Free text on Xero records (references, line descriptions) is the lab's
+    // own data, and the Import matches on it. On unless the lab turns it off.
+    keepReference: readOnOff(env, 'XERO_KEEP_REFERENCE', true),
     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),
@@ -177,5 +183,6 @@ export function resolveXeroSettings(env = process.env) {
 // Whether this installation may write to Xero now. Reads always may.
 export function writesAllowed(settings) {
   if (!settings) return false;
+  if (settings.backgroundJobs === false) return false;
   return settings.mode !== 'live' || settings.liveWrites === true;
 }

package/server/ui/app-page.js

@@ -51,7 +51,7 @@ const BODY = `<div class="fx-app">
   <div id="toasts" class="fx-toasts" aria-live="polite"></div>
 </div>`;
 
-export const APP_PATHS = ['/sign-in', '/jobs', '/invoices', '/invoices/:id', '/people', '/integrations', '/integrations/:id', '/account', '/appearance', '/invoicing-settings', '/price-list', '/custom-fields'];
+export const APP_PATHS = ['/sign-in', '/jobs', '/invoices', '/invoices/:id', '/reconcile', '/reconcile/:id', '/xero-import', '/people', '/integrations', '/integrations/:id', '/account', '/appearance', '/invoicing-settings', '/price-list', '/custom-fields'];
 
 export function appPage({ defaultFamily }) {
   return renderPage({