@arcforgelabs/flow 2026.10.37 → 2026.10.39

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/0009_xero_sent_to_contact.sql

@@ -0,0 +1,3 @@
+-- Whether Xero sent the invoice to the customer (Xero's SentToContact), for
+-- the Invoices page Sent tab. Null until the copy reads the invoice again.
+ALTER TABLE "xero_invoices" ADD COLUMN IF NOT EXISTS "sent_to_contact" boolean;

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

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

package/server/integrations/xero/mirror.js

@@ -77,6 +77,7 @@ export function mapInvoice(invoice, { keepReference = false } = {}) {
     amountDueCents: toCents(invoice.AmountDue),
     amountPaidCents: toCents(invoice.AmountPaid),
     amountCreditedCents: toCents(invoice.AmountCredited),
+    sentToContact: typeof invoice.SentToContact === 'boolean' ? invoice.SentToContact : null,
     lines: mapLines(invoice.LineItems, keepReference),
     xeroUpdatedAt: parseXeroDate(invoice.UpdatedDateUTC),
   };
@@ -135,17 +136,17 @@ const UPSERT = {
   invoices: (org, r, hash) => sql`
     insert into xero_invoices (organisation_id, xero_invoice_id, type, invoice_number, reference, xero_contact_id, status,
       issued_on, due_on, fully_paid_on, currency, subtotal_cents, tax_cents, total_cents, amount_due_cents,
-      amount_paid_cents, amount_credited_cents, lines, xero_updated_at, record_hash)
+      amount_paid_cents, amount_credited_cents, sent_to_contact, lines, xero_updated_at, record_hash)
     values (${org}, ${r.xeroInvoiceId}, ${r.type}, ${r.invoiceNumber}, ${r.reference}, ${r.xeroContactId}, ${r.status},
       ${r.issuedOn}, ${r.dueOn}, ${r.fullyPaidOn}, ${r.currency}, ${r.subtotalCents}, ${r.taxCents}, ${r.totalCents},
-      ${r.amountDueCents}, ${r.amountPaidCents}, ${r.amountCreditedCents}, ${json(r.lines)}::jsonb, ${r.xeroUpdatedAt}, ${hash})
+      ${r.amountDueCents}, ${r.amountPaidCents}, ${r.amountCreditedCents}, ${r.sentToContact ?? null}, ${json(r.lines)}::jsonb, ${r.xeroUpdatedAt}, ${hash})
     on conflict (organisation_id, xero_invoice_id) do update set
       type = excluded.type, invoice_number = excluded.invoice_number, reference = excluded.reference,
       xero_contact_id = excluded.xero_contact_id, status = excluded.status, issued_on = excluded.issued_on,
       due_on = excluded.due_on, fully_paid_on = excluded.fully_paid_on, currency = excluded.currency,
       subtotal_cents = excluded.subtotal_cents, tax_cents = excluded.tax_cents, total_cents = excluded.total_cents,
       amount_due_cents = excluded.amount_due_cents, amount_paid_cents = excluded.amount_paid_cents,
-      amount_credited_cents = excluded.amount_credited_cents, lines = excluded.lines,
+      amount_credited_cents = excluded.amount_credited_cents, sent_to_contact = excluded.sent_to_contact, lines = excluded.lines,
       xero_updated_at = excluded.xero_updated_at, record_hash = excluded.record_hash, last_changed_at = now()
     where xero_invoices.record_hash is distinct from excluded.record_hash
     returning (xmax = 0) as inserted`,

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,14 +89,14 @@ 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
+      x.total_cents as x_total_cents, x.amount_paid_cents, x.amount_due_cents, x.sent_to_contact, x.lines, x.issued_on
     from invoices i
     left join lateral (
       select * from xero_invoice_pushes
@@ -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,27 @@ 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)}`,
+      sentToContact: r.sent_to_contact ?? null,
+      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);
@@ -147,6 +154,29 @@ export async function accountingStatus(db, runtime, organisationId, invoiceIds =
   return out;
 }
 
+// The Invoices page tab of each issued Flow invoice, from Flow's copy of
+// Xero (no calls): draft (on its way, or a Xero DRAFT), approved (AUTHORISED,
+// not sent to the customer yet), sent (Xero sent it, or it is part or fully
+// paid), void (voided or deleted in Xero), or pending (out of sync: a person
+// looks). Answers Map(invoiceId -> stage).
+export async function invoiceStages(db, runtime, organisationId, invoiceIds = null) {
+  const statuses = await accountingStatus(db, runtime, organisationId, invoiceIds);
+  const out = new Map();
+  for (const status of statuses.values()) {
+    if (status.flowStatus !== 'issued') continue;
+    out.set(status.invoiceId, stageOf(status));
+  }
+  return out;
+}
+
+export function stageOf(status) {
+  if (status.finding) return 'pending';
+  if (['part_paid', 'paid'].includes(status.state)) return 'sent';
+  if (status.state === 'approved') return status.xero?.sentToContact ? 'sent' : 'approved';
+  if (['voided', 'deleted'].includes(status.state)) return 'void';
+  return 'draft';
+}
+
 // 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 } = {}) {

package/server/integrations/xero/routes.js

@@ -1,11 +1,13 @@
 import { and, eq } from 'drizzle-orm';
 import express from 'express';
 import { FlowError } from '../../core/errors.js';
+import { createActionGuard } from '../call-guard.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 { 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';
@@ -42,10 +44,25 @@ import { messagePage as themedMessagePage } from '../../ui/page.js';
 //   POST /webhooks                 Xero: change events, signed with the
 //                                  webhook key (XERO_WEBHOOK_KEY); no session
 //
+// Each POST that calls Xero waits between presses (XERO_ACTIONS, the action
+// guard): a press too soon answers 429 with the wait.
+//
 // 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.
 
+// The buttons that call Xero, and how long each waits before it runs again
+// (the action guard, call-guard.js). A send is one invoice at a time, so it
+// only runs once at a time and backs off after a failure.
+export const XERO_ACTIONS = Object.freeze({
+  sync: { cooldownMs: 5 * 60_000 },
+  recheck: { cooldownMs: 30_000 },
+  push: { cooldownMs: 0, budget: false },
+  obligationCheck: { cooldownMs: 30_000 },
+  paymentsSync: { cooldownMs: 5 * 60_000 },
+  mirror: { cooldownMs: 2 * 60_000 },
+});
+
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
 
@@ -92,10 +109,11 @@ export function callsState(status) {
   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 }) }) {
+export function createXeroRouter({ db, personAuth, runtime, log = console, buttonCooldowns = true, actions = createActionGuard({ integration: 'xero', actions: XERO_ACTIONS, off: !buttonCooldowns }), messagePage = (options) => themedMessagePage({ ...options, defaultFamily: DEFAULT_FAMILY }) }) {
   const page = (title, text, tone) => messagePage({ title, text, tone });
   const { settings } = runtime;
   const router = express.Router();
+  const act = (name, key) => actions.route(name, { key });
 
   // 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
@@ -219,7 +237,7 @@ export function createXeroRouter({ db, personAuth, runtime, log = console, messa
     return res.json({ ok: true, disconnected: true, revoked });
   }));
 
-  router.post('/sync', ...manager, handle(log, async (req, res) => {
+  router.post('/sync', ...manager, act('sync'), 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 });
@@ -251,7 +269,7 @@ export function createXeroRouter({ db, personAuth, runtime, log = console, messa
   // 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) => {
+  router.post('/invoices/:invoiceId/recheck', ...manager, act('recheck', (req) => req.params.invoiceId), 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'] });
@@ -260,7 +278,7 @@ export function createXeroRouter({ db, personAuth, runtime, log = console, messa
     res.json({ ok: true, resolved: !status?.finding, closed: result.closed, status });
   }));
 
-  router.post('/invoices/push', ...manager, handle(log, async (req, res) => {
+  router.post('/invoices/push', ...manager, act('push'), 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');
@@ -275,7 +293,7 @@ export function createXeroRouter({ db, personAuth, runtime, log = console, messa
     res.json({ ok: true, pushes: (await listPushes(db, organisationId, invoiceId)).map(describePush) });
   }));
 
-  router.post('/obligations/:obligationId/check', ...manager, handle(log, async (req, res) => {
+  router.post('/obligations/:obligationId/check', ...manager, act('obligationCheck', (req) => req.params.obligationId), 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)
@@ -285,13 +303,13 @@ export function createXeroRouter({ db, personAuth, runtime, log = console, messa
     res.json({ ok: true, obligation: row });
   }));
 
-  router.post('/payments/sync', ...manager, handle(log, async (req, res) => {
+  router.post('/payments/sync', ...manager, act('paymentsSync'), 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 });
   }));
 
-  router.post('/mirror', ...manager, handle(log, async (req, res) => {
+  router.post('/mirror', ...manager, act('mirror'), handle(log, async (req, res) => {
     const organisationId = await requireOrganisation(db, req.body?.organisationId);
     const resources = req.body?.resources ?? MIRROR_RESOURCES;
     if (!Array.isArray(resources) || !resources.length || !resources.every((r) => MIRROR_RESOURCES.includes(r))) {
@@ -307,5 +325,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;
 }