@arcforgelabs/flow 2026.10.37 → 2026.10.39

package/server/db/migrations/meta/_journal.json

@@ -141,6 +141,13 @@
       "when": 1792474607940,
       "tag": "0019_people_views",
       "breakpoints": true
+    },
+    {
+      "idx": 20,
+      "version": "7",
+      "when": 1792507133665,
+      "tag": "0020_custom_field_colours",
+      "breakpoints": true
     }
   ]
 }

package/server/db/schema.js

@@ -784,6 +784,8 @@ export const jobFields = pgTable('job_fields', {
   name: text('name').notNull(),
   type: text('type').notNull(),
   options: jsonb('options').notNull().default(sql`'[]'::jsonb`),
+  // The field's colour, one of the option colours; null is its type's colour.
+  color: text('color'),
   position: integer('position').notNull(),
   archivedAt: timestamp('archived_at', { withTimezone: true }),
   createdBy: uuid('created_by').references(() => people.id, { onDelete: 'set null' }),
@@ -794,8 +796,20 @@ export const jobFields = pgTable('job_fields', {
   unique('job_fields_org_id').on(t.organisationId, t.id),
   check('job_fields_type_valid', sql`${t.type} in ('dropdown', 'person', 'checkbox', 'date', 'number', 'text')`),
   check('job_fields_name_valid', sql`length(${t.name}) between 1 and 60`),
+  check('job_fields_color_valid', sql`${t.color} is null or ${t.color} in ('gray', 'blue', 'teal', 'green', 'amber', 'red', 'purple', 'pink')`),
 ]);
 
+// One row per organisation for Settings, Custom fields: each type group's
+// colour ({ dropdown: 'red' }; a type not named keeps its own colour), and
+// when Flow made the Assignee, so a lab that deletes it does not get it back.
+export const jobFieldSettings = pgTable('job_field_settings', {
+  organisationId: uuid('organisation_id').primaryKey().references(() => organisations.id),
+  groupColors: jsonb('group_colors').notNull().default(sql`'{}'::jsonb`),
+  assigneeMadeAt: timestamp('assignee_made_at', { withTimezone: true }),
+  updatedBy: uuid('updated_by').references(() => people.id, { onDelete: 'set null' }),
+  updatedAt: updatedAt(),
+});
+
 // A job's value for one custom field. A job is the work system's job
 // (source_system, source_job_ref), the same key the Jobs board uses, so a
 // value needs no Flow copy of the job. `value` is JSON: an option id, a person

package/server/integrations/call-guard.js

@@ -360,3 +360,151 @@ export function createCallGuard({
 
   return { integration, policy, check, stoppedNow, record, halt, resume, status };
 }
+
+// ── Button presses ─────────────────────────────────────────────────────────
+//
+// The action guard: a person's button press that calls an outside system (a
+// copy, a recheck, a send) is one action. Pressed again and again, it spends
+// the provider's rate limit and can trip the call guard above. So each
+// guarded route:
+//
+//   - runs once at a time per key: a second press while it runs waits
+//     (429, `action_running`);
+//   - after a run, waits `cooldownMs` before it runs again for that key
+//     (429, `action_cooldown`);
+//   - after a failed run (a 5xx, a 429 or a stopped call), waits twice as
+//     long each time, to at most `maxCooldownMs`; a good run resets it;
+//   - shares one budget per integration: at most `budget` runs in `budgetMs`
+//     for all its actions together (429, `action_budget`). An action with
+//     `budget: false` (a send a person makes one invoice at a time) is
+//     outside it; the provider's rate limit still paces its calls.
+//
+// A 429 carries Retry-After and `retryAfterMs`, so the page shows the wait.
+// A good run says its cooldown in the `Flow-Cooldown-Ms` header. A refused
+// request (another 4xx) costs nothing: no call went. The state is in memory:
+// one Flow process serves one lab (server/rate-limit.js), and the call guard
+// above still protects every process.
+
+export const ACTION_GUARD_POLICY = Object.freeze({
+  cooldownMs: 30_000,
+  maxCooldownMs: 15 * 60_000,
+  budget: 30,
+  budgetMs: 10 * 60_000,
+});
+
+const ACTION_TEXT = {
+  action_running: () => 'This is already running. Wait for it to finish.',
+  action_cooldown: (seconds) => `Flow just did this. Try again in ${seconds} seconds.`,
+  action_budget: (seconds) => `Too many requests to this system. Try again in ${seconds} seconds.`,
+};
+
+// The wait after `failures` failed runs in a row.
+export function actionCooldownMs(failures, { cooldownMs, maxCooldownMs }) {
+  if (failures <= 0) return cooldownMs;
+  return Math.min(maxCooldownMs, Math.max(cooldownMs, 5_000) * 2 ** Math.min(failures, 10));
+}
+
+// How a response ends a run: 'ok', 'failed' (the system or the call guard
+// said no) or 'refused' (Flow refused the request; nothing was called).
+export function actionOutcome(statusCode) {
+  if (statusCode >= 500 || statusCode === 429) return 'failed';
+  if (statusCode >= 400) return 'refused';
+  return 'ok';
+}
+
+const cleanPart = (value) => String(value ?? '').replace(/[^A-Za-z0-9_.:-]+/g, '').slice(0, 80);
+
+// `integration` names the budget; `actions` maps each action name to its
+// policy ({ cooldownMs, maxCooldownMs, budget }). `route(name, { key })` answers the
+// Express middleware for one route; `key(req)` names what the cooldown
+// covers inside the organisation (an invoice id, say), or null for all of it.
+// `off: true` lets every press through (tests that press one route often).
+export function createActionGuard({ integration, actions = {}, policy: overrides = {}, off = false, now = Date.now } = {}) {
+  if (!/^[a-z][a-z0-9-]{1,31}$/.test(integration ?? '')) throw new TypeError('createActionGuard: integration must be an adapter id');
+  const policy = { ...ACTION_GUARD_POLICY, ...overrides };
+  const runs = new Map(); // key -> { running, failures, readyAt }
+  const started = []; // start times inside the budget window
+  const policyOf = (name) => ({ cooldownMs: policy.cooldownMs, maxCooldownMs: policy.maxCooldownMs, ...(actions[name] ?? {}) });
+
+  const runOf = (key) => {
+    let run = runs.get(key);
+    if (!run) runs.set(key, (run = { running: false, failures: 0, readyAt: 0 }));
+    return run;
+  };
+
+  // Why `name` may not run for `key` now, or null.
+  function waitFor(name, key) {
+    const nowMs = Number(now());
+    const run = runs.get(key);
+    if (run?.running) return { code: 'action_running', retryAfterMs: 5_000 };
+    if (run && run.readyAt > nowMs) return { code: 'action_cooldown', retryAfterMs: run.readyAt - nowMs };
+    if (policyOf(name).budget === false) return null;
+    while (started.length && started[0] <= nowMs - policy.budgetMs) started.shift();
+    if (started.length >= policy.budget) return { code: 'action_budget', retryAfterMs: started[0] + policy.budgetMs - nowMs };
+    return null;
+  }
+
+  function begin(name, key) {
+    const wait = waitFor(name, key);
+    if (wait) return wait;
+    runOf(key).running = true;
+    if (policyOf(name).budget !== false) started.push(Number(now()));
+    return null;
+  }
+
+  // `retryAfterMs`: a wait the system or the call guard asked for.
+  function end(name, key, outcome, { retryAfterMs = 0 } = {}) {
+    const run = runOf(key);
+    const rule = policyOf(name);
+    run.running = false;
+    if (outcome === 'refused') {
+      if (rule.budget !== false) started.pop();
+      return 0;
+    }
+    run.failures = outcome === 'failed' ? run.failures + 1 : 0;
+    const waitMs = Math.max(actionCooldownMs(run.failures, rule), retryAfterMs || 0);
+    run.readyAt = Number(now()) + waitMs;
+    return waitMs;
+  }
+
+  function route(name, { key = () => null } = {}) {
+    if (!actions[name]) throw new TypeError(`createActionGuard: ${name} is not a declared action`);
+    if (off) return (_req, _res, next) => next();
+    return (req, res, next) => {
+      const organisation = cleanPart(req.body?.organisationId ?? req.query?.organisationId) || 'sole';
+      const sub = key(req);
+      const runKey = [name, organisation, sub === null || sub === undefined ? '' : cleanPart(sub)].join('|');
+      const wait = begin(name, runKey);
+      if (wait) {
+        const seconds = Math.max(1, Math.ceil(wait.retryAfterMs / 1000));
+        res.set('Retry-After', String(seconds));
+        return res.status(429).json({ ok: false, code: wait.code, error: ACTION_TEXT[wait.code](seconds), retryAfterMs: wait.retryAfterMs });
+      }
+      let ended = false;
+      const finish = (statusCode) => {
+        if (ended) return 0;
+        ended = true;
+        const asked = Number(res.getHeader('Retry-After')) * 1000;
+        return end(name, runKey, actionOutcome(statusCode), { retryAfterMs: Number.isFinite(asked) ? asked : 0 });
+      };
+      // The cooldown is set as the answer is written, so a press right after
+      // it already waits, and the page learns the wait from the header.
+      const writeHead = res.writeHead;
+      res.writeHead = function writeHeadWithCooldown(statusCode, ...rest) {
+        const waitMs = finish(statusCode);
+        if (waitMs && actionOutcome(statusCode) === 'ok' && !res.headersSent) res.setHeader('Flow-Cooldown-Ms', String(waitMs));
+        return writeHead.call(this, statusCode, ...rest);
+      };
+      res.on('close', () => finish(res.headersSent ? res.statusCode : 500));
+      return next();
+    };
+  }
+
+  // Forget every run: for tests, and when a person connects again.
+  const reset = () => {
+    runs.clear();
+    started.length = 0;
+  };
+
+  return { integration, policy, actions, route, waitFor, reset };
+}

package/server/integrations/port.js

@@ -16,6 +16,7 @@ export const CAPABILITIES = Object.freeze([
   'pushInvoice', // send an issued invoice; the Flow record id is the idempotency key
   'pushInvoices', // send several issued invoices in one pass (Send all ready, server/core/sending.js)
   'checkDrafts', // the accounting system's problems with Flow drafts, from its copy; null while not connected
+  'invoiceStages', // { organisationId, invoiceIds? }: Map(invoiceId -> draft | approved | sent | void | pending) for issued invoices, from its copy
   'documentFacts', // what the customer's copy of a sent invoice says (number, reference, dates), from the system's copy in Flow; never a live call
   'sendStatus', // { connected, writesAllowed }: may Flow send invoices now?
   'pushBill', // send an approved bill; the Flow record id is the idempotency key
@@ -150,7 +151,7 @@ export function defineAdapter(adapter) {
     // integration id, its two tables, and its policy. An adapter that calls
     // an outside system declares it (docs/INTEGRATIONS.md, "Outbound calls").
     callGuard: callGuard ? Object.freeze({ ...callGuard }) : null,
-    // Optional HTTP routes: routes({ db, personAuth, log, messagePage }) returns a router
+    // Optional HTTP routes: routes({ db, personAuth, log, messagePage, buttonCooldowns }) returns a router
     // mounted at /api/<id> (registry.routes).
     routes: routes ?? null,
     // Optional: the settings an owner may enter in Settings, Integrations
@@ -317,7 +318,7 @@ export function createRegistry({ log = console, env = process.env } = {}) {
         .filter((a) => ready(a) && typeof a.capabilities[capability] === 'function');
     },
     // The adapters' own HTTP routes, each under /api/<id>. `context` is
-    // { db, personAuth, log, messagePage }. An enabled, ready adapter's router is built
+    // { db, personAuth, log, messagePage, buttonCooldowns }. An enabled, ready adapter's router is built
     // once, here; a request to an adapter that is off gets its turned-off
     // answer (503), so a turned-off adapter never reads its settings or
     // tables.

package/server/integrations/schema.js

@@ -1,5 +1,6 @@
 import { sql } from 'drizzle-orm';
 import { migrate } from 'drizzle-orm/node-postgres/migrator';
+import { withMigrationLock } from '../db/index.js';
 
 // An adapter's tables: created from its own migrations while it is enabled,
 // never dropped by turning it off. Each adapter keeps its own migration
@@ -24,12 +25,15 @@ export async function missingAdapterTables(db, adapter) {
 
 // Runs the adapter's pending migrations, then checks they created every table
 // it declares, so the declaration stays true.
+// It holds Flow's migration lock (server/db/index.js) while it does.
 export async function migrateAdapterSchema(db, adapter) {
-  await migrate(db, { migrationsFolder: adapter.schema.migrationsFolder, migrationsTable: migrationsTable(adapter) });
-  const missing = await missingAdapterTables(db, adapter);
-  if (missing.length) {
-    throw new Error(`Adapter ${adapter.id} migrations did not create ${missing.join(', ')}`);
-  }
+  await withMigrationLock(db, async (locked) => {
+    await migrate(locked, { migrationsFolder: adapter.schema.migrationsFolder, migrationsTable: migrationsTable(adapter) });
+    const missing = await missingAdapterTables(locked, adapter);
+    if (missing.length) {
+      throw new Error(`Adapter ${adapter.id} migrations did not create ${missing.join(', ')}`);
+    }
+  });
 }
 
 export function isMissingTable(error) {

package/server/integrations/seazona/feed.js

@@ -202,7 +202,7 @@ export async function listWork(db, { now = Date.now(), finishedDays = WORK_FINIS
     return {
       sourceSystem: 'seazona',
       sourceJobRef: order.id,
-      // The Seazona order id is the case number. Never patient data.
+      // The Seazona order id is the case number.
       caseRef: order.id,
       status,
       clientId: order.clientId,
@@ -211,6 +211,9 @@ export async function listWork(db, { now = Date.now(), finishedDays = WORK_FINIS
       department: order.department,
       orderedOn: parseSeazonaDate(order.orderedText),
       dueOn: parseSeazonaDate(order.dueText),
+      // The patient, only when this installation keeps patient names
+      // (SEAZONA_KEEP_PATIENT_REFERENCE); otherwise the copy has none.
+      patient: order.patientReference ?? null,
       lines: (order.lines ?? []).map((l) => ({ code: l.code ?? null, description: l.description, amountCents: l.amountCents ?? null })),
       totalCents: order.subtotalCents,
     };

package/server/integrations/seazona/settings.js

@@ -77,15 +77,19 @@ export function orderUrlTemplate(value) {
 }
 
 // The link to one order for "Open in Seazona": the order's own page when the
-// installation set SEAZONA_ORDER_URL, else the home page of the lab's
-// Seazona web app when the API address names it (https://{lab}.seazonaapi.net),
-// else null. `exact` is true only for the order's own page.
+// installation set SEAZONA_ORDER_URL; else, when the API address names the
+// lab (https://{lab}.seazonaapi.net), its order page
+// (https://{lab}.seazona.net/OrderEdit.aspx?id={order id}), or its home page
+// with no order id; else null. `exact` is true only for the order's own page.
 export function orderLink(settings, { sourceJobRef } = {}) {
   const template = settings?.orderUrlTemplate ?? null;
   if (template && sourceJobRef) return { url: template.replaceAll('{ref}', encodeURIComponent(sourceJobRef)), exact: true };
   const host = settings?.baseUrl ? new URL(settings.baseUrl).hostname : '';
   const lab = /^([a-z0-9-]+)\.seazonaapi\.net$/i.exec(host)?.[1];
-  return lab ? { url: `https://${lab}.seazona.net/`, exact: false } : null;
+  if (!lab) return null;
+  // Seazona's own order screen takes the order id (a GUID) Flow syncs.
+  if (new RegExp(`^${ORDER_ID.source}$`, 'i').test(sourceJobRef ?? '')) return { url: `https://${lab}.seazona.net/OrderEdit.aspx?id=${encodeURIComponent(sourceJobRef)}`, exact: true };
+  return { url: `https://${lab}.seazona.net/`, exact: false };
 }
 
 // Returns the resolved settings, or throws SeazonaSettingsError. `mode` is

package/server/integrations/xero/drafts.js

@@ -131,7 +131,7 @@ export function buildDraft(document, { settings, contact, items, sendMode = 'acc
     };
     if (line.itemCode) {
       if (items.has(line.itemCode)) out.ItemCode = line.itemCode;
-      else problems.push(problem('xero_item_missing', `Line ${line.position}: item ${line.itemCode} is not in Xero. Add it in Xero, then sync.`, { itemCode: line.itemCode }));
+      else problems.push(problem('xero_item_missing', `Line ${line.position}: item ${line.itemCode} is not in Xero. Add it in Xero, then sync.`, { itemCode: line.itemCode, short: `${line.itemCode} not in Xero` }));
     } else if (line.accountCode) {
       // A line with no item books to its own account, such as a surcharge.
       out.AccountCode = line.accountCode;
@@ -289,8 +289,8 @@ async function previewOne(db, runtime, organisationId, invoiceId) {
   if (invoice.status === 'void') problems.push(problem('invoice_void', 'This invoice is void. Flow does not send it to Xero.'));
   if (invoice.status === 'draft') problems.push(problem('invoice_not_issued', 'This invoice is a draft. Issue it, then send it to Xero.'));
   const match = await matchContact(db, organisationId, document.contact.name);
-  if (match.state === 'missing') problems.push(problem('xero_contact_missing', `No Xero contact is named "${document.contact.name}". Add it in Xero (Flow never creates Xero contacts), then sync.`));
-  if (match.state === 'ambiguous') problems.push(problem('xero_contact_ambiguous', `More than one Xero contact is named "${document.contact.name}". Merge or rename them in Xero, then sync.`));
+  if (match.state === 'missing') problems.push(problem('xero_contact_missing', `No Xero contact is named "${document.contact.name}". Add it in Xero (Flow never creates Xero contacts), then sync.`, { short: 'Client not in Xero' }));
+  if (match.state === 'ambiguous') problems.push(problem('xero_contact_ambiguous', `More than one Xero contact is named "${document.contact.name}". Merge or rename them in Xero, then sync.`, { short: 'Client twice in Xero' }));
   const items = await itemsByCode(db, organisationId, document.lines.map((l) => l.itemCode));
   const sendMode = await sendModeFor(db, organisationId, invoice.contactId);
   const { draft, problems: lineProblems } = buildDraft(document, { settings: runtime.settings, contact: match.contact, items, sendMode });
@@ -389,7 +389,7 @@ export async function checkDrafts(db, runtime, { organisationId, invoiceIds }) {
     for (const preview of invoices) {
       found.set(preview.invoiceId, preview.problems
         .filter((p) => p.blocking !== false && p.code !== 'invoice_not_issued')
-        .map(({ code, message }) => ({ code, message })));
+        .map(({ code, message, short }) => ({ code, message, ...(short ? { short } : {}) })));
     }
   }
   return found;

package/server/integrations/xero/fit.js

@@ -0,0 +1,108 @@
+// How sure Flow is that a Xero invoice in the copy is one Flow invoice
+// (docs/XERO_IMPORT.md, "Sure match"). The checks are the ones the job
+// matcher learned on work-system jobs against Xero (server/core/pipeline.js
+// scoreCandidate), plus what the Flow invoice's own jobs know: the matcher's
+// tie to this Xero invoice, and the work system's invoice number.
+//
+// A pair is sure only when one piece of hard evidence ties it, or when the
+// score is high and clearly ahead; and in both cases only when it is the one
+// fit both ways (`sureFits`).
+
+export const SURE_SCORE = 11; // total, same items, and within 3 days
+export const SURE_LEAD = 3;
+export const POOL_DAYS = 14;
+const day = (iso) => Date.parse(`${iso}T00:00:00Z`);
+const daysApart = (a, b) => (a && b ? Math.abs(day(a) - day(b)) / 86_400_000 : null);
+const withGst = (cents) => Math.round(cents * 1.1);
+const withoutReissue = (ref) => String(ref ?? '').trim().replace(/R$/i, '').toLowerCase();
+const words = (text) => String(text ?? '').trim().toLowerCase().replace(/\s+/g, ' ');
+
+// xero: { id, number, contactId, totalCents, issuedOn, itemCodes[], reference }
+// flow: { id, contactId, totalCents, subtotalCents, date, itemCodes[], reference,
+//         jobs: [{ accountingRef, sourceInvoiceRef, practitioner }] }
+// Answers { score, signals, hard }; `hard` names the evidence that ties them.
+export function scoreFit(xero, flow) {
+  const signals = [];
+  const add = (signal, weight) => signals.push({ signal, weight });
+  const jobs = flow.jobs ?? [];
+  let hard = null;
+  if (jobs.some((j) => j.accountingRef && j.accountingRef === xero.id)) hard = 'job_tied';
+  else if (xero.number && jobs.some((j) => j.sourceInvoiceRef && withoutReissue(j.sourceInvoiceRef) === withoutReissue(xero.number))) hard = 'work_invoice_number';
+  if (hard) add(hard, 10);
+  if (xero.contactId && xero.contactId === flow.contactId) add('client', 2);
+  if (xero.totalCents === flow.totalCents) add('total', 6);
+  else if ([flow.subtotalCents, withGst(flow.subtotalCents)].includes(xero.totalCents)) add('total_gst', 5);
+  const ours = new Set(flow.itemCodes ?? []);
+  const theirs = new Set(xero.itemCodes ?? []);
+  if (ours.size && theirs.size) {
+    const shared = [...ours].filter((c) => theirs.has(c)).length;
+    if (shared === ours.size && shared === theirs.size) add('items_same', 3);
+    else if (shared) add('items_overlap', 1);
+    else add('items_differ', -3);
+  }
+  const apart = daysApart(xero.issuedOn, flow.date);
+  if (apart !== null && apart <= 3) add('date_close', 2);
+  else if (apart !== null && apart <= POOL_DAYS) add('date_near', 1);
+  // A Reference is in the copy unless XERO_KEEP_REFERENCE is off.
+  if (xero.reference && flow.reference) {
+    if (words(xero.reference) === words(flow.reference)) add('reference_same', 3);
+    else add('reference_differs', -2);
+  } else if (xero.reference && jobs.some((j) => j.practitioner && words(xero.reference).includes(words(j.practitioner)))) {
+    add('practitioner', 1);
+  }
+  return { score: signals.reduce((sum, s) => sum + s.weight, 0), signals, hard };
+}
+
+// Whether the pair may be offered at all: hard evidence, or the same client
+// with an amount that fits and dates within two weeks.
+export function canFit(xero, flow, scored) {
+  if (scored.hard) return true;
+  const amount = scored.signals.some((s) => s.signal === 'total' || s.signal === 'total_gst');
+  const near = scored.signals.some((s) => s.signal === 'date_close' || s.signal === 'date_near');
+  return Boolean(xero.contactId && xero.contactId === flow.contactId && amount && near);
+}
+
+// pairs: [{ xeroId, flowId, apart, fit }], `fit` being the candidate with its
+// score. A fit loses RIVAL_WEIGHT, and is marked `rival`, when the same Flow
+// invoice has another Xero invoice dated at least RIVAL_DAYS closer to it, or
+// the same Xero invoice has another Flow invoice that much closer. Fits a day
+// or two apart stay level, so a person picks.
+export const RIVAL_WEIGHT = 4;
+export const RIVAL_DAYS = 3;
+export function markRivals(pairs) {
+  for (const p of pairs) {
+    if (p.fit.hard) continue;
+    const closer = pairs.some((o) => o !== p && o.apart + RIVAL_DAYS <= p.apart && (o.flowId === p.flowId || o.xeroId === p.xeroId));
+    if (closer) {
+      p.fit.score -= RIVAL_WEIGHT;
+      p.fit.rival = true;
+    }
+  }
+}
+
+// pairs: [{ xeroId, flowId, score, hard }]. Answers the set of `xeroId` whose
+// best fit is sure: hard evidence or SURE_SCORE, at least SURE_LEAD ahead of
+// that Xero invoice's next fit, and that Flow invoice's best fit back.
+export function sureFits(pairs) {
+  const byXero = new Map();
+  const byFlow = new Map();
+  for (const p of pairs) {
+    if (!byXero.has(p.xeroId)) byXero.set(p.xeroId, []);
+    if (!byFlow.has(p.flowId)) byFlow.set(p.flowId, []);
+    byXero.get(p.xeroId).push(p);
+    byFlow.get(p.flowId).push(p);
+  }
+  const ranked = (list) => [...list].sort((a, b) => b.score - a.score);
+  const clear = (list) => {
+    const [top, next] = ranked(list);
+    if (!top || !(top.hard || top.score >= SURE_SCORE)) return null;
+    if (next && (next.hard || top.score - next.score < SURE_LEAD)) return null;
+    return top;
+  };
+  const sure = new Map();
+  for (const [xeroId, list] of byXero) {
+    const top = clear(list);
+    if (top && clear(byFlow.get(top.flowId))?.xeroId === xeroId) sure.set(xeroId, top.flowId);
+  }
+  return sure;
+}

package/server/integrations/xero/import.js

@@ -5,6 +5,7 @@ import { isCallsStopped } from '../call-guard.js';
 import { lastSync, syncCatalogue } from './catalogue.js';
 import { mirrorState } from './lookup.js';
 import { MIRROR_RESOURCES, mirrorXero } from './mirror.js';
+import { matchXero } from './links.js';
 import { checkSentInvoices } from './reconcile.js';
 import { runWebhookWork, WEBHOOK_REFRESH_MS, webhooksActive } from './webhooks.js';
 
@@ -82,7 +83,11 @@ export async function runImportSlice(db, runtime, job, { maxPages = SLICE_PAGES
   const sent = invoices && (invoices.inserted || invoices.changed || job.payload?.reason !== 'changes')
     ? await checkSentInvoices(db, runtime, job.organisationId)
     : null;
-  return { results, more: stopped, ...(sent ? { sent } : {}) };
+  // Each Xero invoice against Flow's own (links.js): sure fits are linked, and
+  // with the Import setting on, a Flow invoice is made for each with no fit.
+  // Flow's database only.
+  const matched = sent ? await matchXero(db, job.organisationId) : null;
+  return { results, more: stopped, ...(sent ? { sent } : {}), ...(matched ? { matched } : {}) };
 }
 
 // Claims and runs one due import job, then queues the next slice when one is

package/server/integrations/xero/index.js

@@ -6,6 +6,7 @@ import { readConnection } from './connections.js';
 import { createImportWorker } from './import.js';
 import { readPayments, xeroLiveCheck } from './ledger.js';
 import { findInvoices, listCustomers, listPriceItems, mirrorState } from './lookup.js';
+import { invoiceStages } from './reconcile.js';
 import { createXeroRouter } from './routes.js';
 import { createXeroRuntime, requireXeroSettings, XERO_CALL_GUARD } from './runtime.js';
 import { writesAllowed } from './settings.js';
@@ -15,7 +16,7 @@ import { readChangesFirst } from './webhooks.js';
 // XERO_MODE says which Xero it acts on. Its tables are created only while it
 // is on (docs/INTEGRATIONS.md).
 
-export const XERO_TABLES = Object.freeze(['xero_connections', 'xero_contacts', 'xero_items', 'xero_sync_runs', 'xero_invoice_pushes', 'xero_payment_cursors', 'xero_invoices', 'xero_credit_notes', 'xero_payments', 'xero_mirror_cursors', 'xero_call_guard', 'xero_calls', 'xero_webhook_events', 'xero_daily_checks']);
+export const XERO_TABLES = Object.freeze(['xero_connections', 'xero_contacts', 'xero_items', 'xero_sync_runs', 'xero_invoice_pushes', 'xero_payment_cursors', 'xero_invoices', 'xero_credit_notes', 'xero_payments', 'xero_mirror_cursors', 'xero_call_guard', 'xero_calls', 'xero_webhook_events', 'xero_daily_checks', 'xero_invoice_links', 'xero_import_settings']);
 
 // What an owner enters in Settings, Integrations (server/integrations/setup.js).
 // The refresh token's key comes from Flow's secrets key.
@@ -116,6 +117,9 @@ export function createXeroAdapter({ runtime: given = null } = {}) {
       pushInvoice: ({ organisationId, invoiceId, pushedBy = null }) => pushInvoice(database, current(), { organisationId, invoiceId, pushedBy }),
       // Several issued invoices, in batches of MAX_BATCH (drafts.js).
       pushInvoices: ({ organisationId, invoiceIds, pushedBy = null }) => pushInvoices(database, current(), { organisationId, invoiceIds, pushedBy }),
+      // The Invoices page tab of each issued invoice (reconcile.js), from
+      // Flow's copy of Xero: draft, approved, sent, void or pending.
+      invoiceStages: ({ organisationId, invoiceIds = null }) => invoiceStages(database, current(), organisationId, invoiceIds),
       // What would stop each Flow draft in Xero, from Flow's copy (no calls).
       checkDrafts: ({ organisationId, invoiceIds }) => checkDrafts(database, current(), { organisationId, invoiceIds }),
       sendStatus: async ({ organisationId }) => {
@@ -142,7 +146,7 @@ export function createXeroAdapter({ runtime: given = null } = {}) {
       // Xero items, from Flow's copy, for the price list (lookup.js).
       listPriceItems: ({ organisationId }) => listPriceItems(database, organisationId, { taxTypes: current().settings.taxTypes }),
     },
-    routes: ({ db, personAuth, log, messagePage }) => createXeroRouter({ db, personAuth, runtime: current(), log, messagePage }),
+    routes: ({ db, personAuth, log, messagePage, buttonCooldowns }) => createXeroRouter({ db, personAuth, runtime: current(), log, messagePage, buttonCooldowns }),
   };
 }
 

package/server/integrations/xero/ledger.js

@@ -218,7 +218,10 @@ export async function recordXeroPayments(db, runtime, organisationId, { actor, s
     const xeroIds = [...new Set(payments.map((p) => p.xeroInvoiceId))];
     const byFlowInvoice = new Map();
     if (xeroIds.length) {
+      // Flow invoices sent to Xero, and those the Import page linked (links.js).
       const { rows } = await db.execute(sql`select xero_invoice_id, invoice_id from xero_invoice_pushes
+        where organisation_id = ${organisationId} and xero_invoice_id = any(${sql.param(xeroIds)}::text[])
+        union all select xero_invoice_id, invoice_id from xero_invoice_links
         where organisation_id = ${organisationId} and xero_invoice_id = any(${sql.param(xeroIds)}::text[])`);
       for (const row of rows) byFlowInvoice.set(row.xero_invoice_id, row.invoice_id);
     }