@arcforgelabs/flow 2026.10.36 → 2026.10.38

package/README.md

@@ -55,6 +55,7 @@ run a lab.
 | `docs/REPLIT.md` | A Replit workspace of this repository that follows a release channel (`FLOW_DEPLOY_REF`) |
 | `docs/INTEGRATIONS.md` | How an integration adapter is built, turned on and off, and owns its tables |
 | `docs/XERO.md` | The Xero adapter: modes, settings, rate limits, connecting Xero and draft invoices |
+| `docs/XERO_IMPORT.md` | Xero › Import: each Xero invoice in Flow's copy linked to its Flow invoice, or made into one |
 | `docs/SEAZONA.md` | The Seazona adapter: modes, settings, the rate governor, replay files and its tables |
 | `docs/SENTRY.md` | The Sentry adapter: errors and problem reports to the installation's own Sentry project |
 | `server/integrations/port.js` | The integration port every adapter implements |

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@arcforgelabs/flow",
-  "version": "2026.10.36",
+  "version": "2026.10.38",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@arcforgelabs/flow",
-      "version": "2026.10.36",
+      "version": "2026.10.38",
       "license": "MIT",
       "dependencies": {
         "@clerk/backend": "3.25.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcforgelabs/flow",
-  "version": "2026.10.36",
+  "version": "2026.10.38",
   "description": "Invoicing, bill entry and a financial dashboard for labs, with Seazona and Xero integrations.",
   "license": "MIT",
   "repository": {

package/server/api/custom-fields.js

@@ -1,6 +1,6 @@
 import express from 'express';
 import {
-  CUSTOM_FIELD_TYPES, GROUPABLE_TYPES, OPTION_COLORS, archiveField, choosablePeople, createField, jobFieldHistory, listFields,
+  CUSTOM_FIELD_TYPES, GROUPABLE_TYPES, OPTION_COLORS, archiveField, choosablePeople, createField, ensureAssignee, jobFieldHistory, listFields,
   listJobFieldValues, orderFields, setJobFieldValue, updateField,
 } from '../core/custom-fields.js';
 import { FlowError } from '../core/errors.js';
@@ -71,6 +71,7 @@ export function createCustomFieldsRouter({ db, personAuth, work = () => [], log
   router.get('/', ...signedIn, handle(async (req, res) => {
     const organisationId = await organisationOf(req);
     const archived = req.query.archived === '1' || req.query.archived === 'true';
+    await ensureAssignee(db, organisationId);
     const [fields, system, chosen] = await Promise.all([listFields(db, organisationId, { archived }), systemFields(), choosablePeople(db)]);
     res.json({ ok: true, fields, systemFields: system, people: chosen, types: CUSTOM_FIELD_TYPES, groupable: GROUPABLE_TYPES, colors: OPTION_COLORS });
   }));

package/server/api/invoicing.js

@@ -17,12 +17,14 @@ import {
 } from '../core/invoicing-rules.js';
 import { boardJobs, describeObligations } from '../core/job-board.js';
 import { readBeforeAct } from '../core/read-before-act.js';
+import { invoiceMatchDetail, jobMatchDetail, listReconcile } from '../core/job-match.js';
 import { jobReference } from '../core/references.js';
 import {
   acceptFindings, archivePriceItem, checkPrices, createPriceItem, linkPriceItem, readCatalogues, readPriceList, unlinkPriceItem, updatePriceItem,
 } from '../core/price-list.js';
 import {
-  draftInvoiceForObligation, explainObligation, jobChangeFor, listObligations, setReady, useSourceLines,
+  confirmNoInvoice, draftInvoiceForObligation, explainObligation, jobChangeFor, linkJobToInvoice, listObligations,
+  setReady, useSourceLines,
 } from '../core/ledger.js';
 import { isHistoryHeld } from '../core/history.js';
 import { invoicePdfDocument, pdfFields, pdfFilename, renderInvoicePdf } from '../core/invoice-pdf.js';
@@ -245,6 +247,13 @@ function withLink(job, systems) {
   return { ...job, systemName: source?.name ?? job.sourceSystem, link: link ?? null };
 }
 
+// The connected systems an invoice can link to: work systems, then the
+// accounting system.
+const linkedSystems = (work, accounting) => [
+  ...work.map((a) => ({ id: a.id, name: a.name, kind: 'work' })),
+  ...(accounting ? [{ id: accounting.id, name: accounting.name, kind: 'accounting' }] : []),
+];
+
 async function jobsByInvoice(db, organisationId, invoiceIds) {
   if (!invoiceIds.length) return new Map();
   const rows = await db.select().from(billingObligations)
@@ -291,7 +300,9 @@ async function invoiceDetail(db, organisationId, invoiceId, accounting = null, w
       ? { mode: await sendModeFor(db, organisationId, invoice.contactId), otherCustomers: 0, ...(await accounting.capabilities.sendStatus({ organisationId })) }
       : null,
     contact: contact ?? null,
-    job: jobs.get(invoiceId) ?? null,
+    job: withLink(jobs.get(invoiceId) ?? null, work),
+    // The Linked card: each connected system, and this invoice's link there.
+    linksTo: linkedSystems(work, accounting),
     versions: versions.map(({ version, issuedAt, issuedBy }) => ({ version, issuedAt, issuedBy })),
   };
 }
@@ -374,7 +385,7 @@ export function createInvoicingRouter({
       sendsTo: system?.name ?? null,
       sendMode: mode,
       // The Linked column: one icon for each connected system.
-      linksTo: [...systems.map((a) => ({ id: a.id, name: a.name, kind: 'work' })), ...(system ? [{ id: system.id, name: system.name, kind: 'accounting' }] : [])],
+      linksTo: linkedSystems(systems, system),
     });
   }));
 
@@ -579,6 +590,53 @@ export function createInvoicingRouter({
     res.json({ ok: true, invoice: await invoiceDetail(db, organisationId, invoice.id, accounting(), work()) });
   }));
 
+  // A job with no invoice whose match is unclear (ledger.js). The linking
+  // tool lists the matcher's suggestions, read from the accounting copy;
+  // "Make invoice" says there is none yet; "Link" picks one of them.
+  // The Reconcile page: Flow's jobs with no Flow invoice, Flow invoices with
+  // no job, and one of them beside its possible other side
+  // (core/job-match.js). Flow's own records only; no integration is called.
+  router.get('/reconcile', ...signedIn, handle(log, async (req, res) => {
+    const organisationId = await organisationOf(req);
+    res.json({ ok: true, ...await listReconcile(db, organisationId) });
+  }));
+
+  router.get('/jobs/:id/reconcile', ...signedIn, handle(log, async (req, res) => {
+    const obligationId = pathId(req.params.id, 'job');
+    const organisationId = await organisationOf(req);
+    const [obligation] = await db.select().from(billingObligations)
+      .where(and(eq(billingObligations.organisationId, organisationId), eq(billingObligations.id, obligationId)));
+    if (!obligation) throw new FlowError('not_found', 'job not found');
+    // The Reference Flow would give its invoice, from Flow's own copy only.
+    const { referenceTemplate: template } = await readInvoicingSettings(db, organisationId);
+    const source = work().find((a) => a.id === obligation.sourceSystem) ?? null;
+    const reference = await jobReference(db, organisationId, obligation, { template, work: source });
+    const detail = await jobMatchDetail(db, organisationId, obligationId, { reference, q: text(req.query.q) ?? '' });
+    res.json({ ok: true, ...detail, job: { ...detail.job, sourceName: source?.name ?? null } });
+  }));
+
+  router.get('/invoices/:id/reconcile', ...signedIn, handle(log, async (req, res) => {
+    const invoiceId = pathId(req.params.id, 'invoice');
+    const organisationId = await organisationOf(req);
+    res.json({ ok: true, ...await invoiceMatchDetail(db, organisationId, invoiceId, { q: text(req.query.q) ?? '' }) });
+  }));
+
+  router.post('/jobs/:id/no-invoice', ...manager, handle(log, async (req, res) => {
+    const obligationId = pathId(req.params.id, 'job');
+    const organisationId = await organisationOf(req);
+    const job = await confirmNoInvoice(db, organisationId, obligationId, { actor: `person:${req.person.id}` });
+    res.json({ ok: true, job: { id: job.id, accountingState: job.accountingState } });
+  }));
+
+  // Links a job to a Flow invoice that already exists.
+  router.post('/jobs/:id/link', ...manager, handle(log, async (req, res) => {
+    const obligationId = pathId(req.params.id, 'job');
+    const organisationId = await organisationOf(req);
+    const invoiceId = pathId(text(req.body?.invoiceId) ?? '', 'invoice');
+    const job = await linkJobToInvoice(db, organisationId, obligationId, { invoiceId, actor: `person:${req.person.id}` });
+    res.json({ ok: true, job: { id: job.id, invoiceId: job.invoiceId } });
+  }));
+
   router.post('/jobs/:id/ready', ...signedIn, handle(log, async (req, res) => {
     const obligationId = pathId(req.params.id, 'job');
     const organisationId = await organisationOf(req);

package/server/auth/clerk.js

@@ -8,6 +8,9 @@ import { normaliseEmail } from './people.js';
 //   getUser(clerkUserId)     the Clerk user (emails, external accounts)
 //   findUserIdByEmail(email) the Clerk user with this email, or null
 //   createUser({ email })    a Clerk account with no password, for an invitee
+//   deleteUser(clerkUserId)  removes a Clerk account (an unused invitee's only)
+//   inviteByEmail({ email, redirectUrl })
+//                            Clerk emails an invitation link to `email`
 //
 // The real one is loaded only when FLOW_AUTH=clerk.
 export async function loadClerkAdapter({ secretKey, publishableKey, proxyUrl, authorizedParties = [] }) {
@@ -36,9 +39,41 @@ export async function loadClerkAdapter({ secretKey, publishableKey, proxyUrl, au
       const user = await client.users.createUser({ emailAddress: [email], skipPasswordRequirement: true });
       return user.id;
     },
+    async deleteUser(clerkUserId) {
+      await client.users.deleteUser(clerkUserId);
+    },
+    // Clerk sends the email. Its link opens `redirectUrl` with a sign-up
+    // ticket; a pending invitation for the same address is replaced.
+    async inviteByEmail({ email, redirectUrl }) {
+      await client.invitations.createInvitation({ emailAddress: email, redirectUrl, notify: true, ignoreExisting: true });
+    },
   };
 }
 
+// A Clerk account nobody has used: never signed in, no password and no
+// connected account. Flow made it for an invitee (ensureClerkAccount).
+export function unusedClerkAccount(clerkUser) {
+  return Boolean(clerkUser)
+    && !clerkUser.lastSignInAt
+    && clerkUser.passwordEnabled === false
+    && !(Array.isArray(clerkUser.externalAccounts) && clerkUser.externalAccounts.length);
+}
+
+// Has Clerk email an invitation to `email`. Clerk does not invite an address
+// that already has an account, so an unused account Flow made earlier is
+// removed first; the invitee's account is made when they take up the
+// invitation. An address with a used account gets no email: that person can
+// already sign in. Returns { emailed }.
+export async function sendClerkInvitation(clerk, email, redirectUrl) {
+  const existing = await clerk.findUserIdByEmail(email);
+  if (existing) {
+    if (!unusedClerkAccount(await clerk.getUser(existing))) return { emailed: false };
+    await clerk.deleteUser(existing);
+  }
+  await clerk.inviteByEmail({ email, redirectUrl });
+  return { emailed: true };
+}
+
 // An invitee needs a Clerk account before their first sign-in, because with
 // public sign-up off Flow's sign-in page never creates one. The account has
 // the invitee's email (verified, since the backend made it) and no password;

package/server/auth/routes.js

@@ -1,9 +1,10 @@
 import express from 'express';
 import { FlowError } from '../core/errors.js';
 import { rateLimit } from '../rate-limit.js';
-import { ensureClerkAccount } from './clerk.js';
+import { ensureClerkAccount, sendClerkInvitation } from './clerk.js';
 import {
   findPersonByEmail,
+  findPersonById,
   invitePerson,
   listPeople,
   normaliseEmail,
@@ -139,23 +140,61 @@ export function createSignInRouter({ settings, db, clerk, personAuth, defaultFam
     }
   });
 
-  // Invite someone. Flow also makes sure they have a Clerk account, because
-  // with public sign-up off the sign-in page never creates one.
+  // The invitation email's link opens this installation's sign-in page.
+  const signInUrl = (req) => `${req.protocol}://${req.get('host')}/sign-in`;
+
+  // Clerk emails the invitation. If Clerk cannot, Flow makes the invitee's
+  // Clerk account itself (with public sign-up off the sign-in page never
+  // creates one) and the owner sends the sign-in message by hand.
+  async function inviteWithClerk(req, email) {
+    try {
+      return await sendClerkInvitation(clerk, email, signInUrl(req));
+    } catch (error) {
+      log.error?.(`[people] Clerk invitation email failed: ${error.message}`);
+    }
+    await ensureClerkAccount(clerk, email);
+    return { emailed: false };
+  }
+
+  // Invite someone.
   people.post('/', async (req, res) => {
     try {
       const email = normaliseEmail(req.body?.email);
       const role = req.body?.role;
       if (!isPlainEmail(email)) throw new FlowError('invalid', 'email must be a plain (ASCII) email address');
       if (await findPersonByEmail(db, email)) throw new FlowError('conflict', 'that email address is already on the people list');
+      let invite;
       try {
-        await ensureClerkAccount(clerk, email);
+        invite = await inviteWithClerk(req, email);
       } catch (error) {
         log.error?.(`[people] Clerk account for an invitation failed: ${error.message}`);
         return res.status(503).json({ ok: false, code: 'sign_in_unavailable', error: 'Flow could not prepare the sign-in account. Try again shortly.' });
       }
       const person = await invitePerson(db, { email, name: req.body?.name ?? null, role, invitedBy: req.person.id });
-      log.info?.(`[people] ${req.person.id} invited ${person.id} as ${person.role}`);
-      res.status(201).json({ ok: true, person: publicPerson(person) });
+      log.info?.(`[people] ${req.person.id} invited ${person.id} as ${person.role} (${invite.emailed ? 'emailed' : 'not emailed'})`);
+      res.status(201).json({ ok: true, person: publicPerson(person), invite });
+    } catch (error) {
+      sendError(res, error, log);
+    }
+  });
+
+  // Email an invited person's invitation again. Only for someone who has
+  // not signed in yet.
+  people.post('/:id/invite', async (req, res) => {
+    try {
+      const person = await findPersonById(db, req.params.id);
+      if (!person) throw new FlowError('not_found', 'person not found');
+      if (person.clerkUserId || person.status !== 'active') throw new FlowError('conflict', 'only an invited person who has not signed in yet gets an invitation email');
+      let invite;
+      try {
+        invite = await sendClerkInvitation(clerk, person.email, signInUrl(req));
+      } catch (error) {
+        log.error?.(`[people] Clerk invitation email failed: ${error.message}`);
+        return res.status(503).json({ ok: false, code: 'sign_in_unavailable', error: 'Clerk could not send the invitation email. Try again shortly.' });
+      }
+      if (!invite.emailed) throw new FlowError('conflict', 'they already have a sign-in account: they can sign in now');
+      log.info?.(`[people] ${req.person.id} emailed the invitation for ${person.id} again`);
+      res.json({ ok: true, invite });
     } catch (error) {
       sendError(res, error, log);
     }

package/server/core/custom-fields.js

@@ -133,6 +133,24 @@ export async function createField(db, organisationId, raw, { personId = null } =
   });
 }
 
+// Every lab gets an Assignee: a person field, made once, the first time
+// the lab's fields are read and it has no person field at all (live or
+// archived). The lab can then rename it or archive it like any field, and
+// Flow does not make it again. A field already named Assignee of another
+// type is left alone.
+export const ASSIGNEE = { name: 'Assignee', type: 'person' };
+export async function ensureAssignee(db, organisationId) {
+  const [{ count }] = await db.select({ count: sql`count(*)`.mapWith(Number) }).from(jobFields)
+    .where(and(eq(jobFields.organisationId, organisationId), eq(jobFields.type, 'person')));
+  if (count > 0) return null;
+  try {
+    return await createField(db, organisationId, ASSIGNEE);
+  } catch (error) {
+    if (error.code === 'conflict' || error.code === 'invalid' || error.code === '23505') return null;
+    throw error;
+  }
+}
+
 export async function updateField(db, organisationId, id, raw, { personId = null } = {}) {
   const previous = await readRow(db, organisationId, id);
   if (previous.archivedAt) throw new FlowError('conflict', 'the field is archived; bring it back first');

package/server/core/host.js

@@ -0,0 +1,24 @@
+// Where this copy of Flow runs. A Replit workspace (the editor's Run button)
+// shares its secrets with the published app, so without a rule it would sync,
+// draft and send next to the live copy: twice the calls to Xero and Seazona,
+// and a second sender. FLOW_BACKGROUND_JOBS decides; unset, it is off in a
+// Replit workspace and on everywhere else (docs/SELF_HOSTING.md).
+
+const read = (env, name) => String(env?.[name] ?? '').trim();
+
+// Replit sets REPL_ID in the workspace and REPLIT_DEPLOYMENT on the published
+// app only.
+export function isReplitWorkspace(env = process.env) {
+  return Boolean(read(env, 'REPL_ID')) && !read(env, 'REPLIT_DEPLOYMENT');
+}
+
+// Whether this copy runs the jobs that call or write to other systems: the
+// Seazona sync, the Xero read, the pipeline, the daily reconcile and the send
+// worker. Off, it also never writes to Xero.
+export function backgroundJobsOn(env = process.env) {
+  const value = read(env, 'FLOW_BACKGROUND_JOBS').toLowerCase();
+  if (value === 'on') return true;
+  if (value === 'off') return false;
+  if (value) throw new Error('FLOW_BACKGROUND_JOBS must be "on", "off" or unset');
+  return !isReplitWorkspace(env);
+}

package/server/core/job-board.js

@@ -102,7 +102,7 @@ export async function boardJobs(db, organisationId, { work = [], accounting = nu
       if (status && !statuses.has(status)) statuses.set(status, { label: status, final: false, firstSeenAt: null });
       return {
         sourceSystem: o.sourceSystem, sourceJobRef: o.sourceJobRef, caseRef: o.caseRef, status,
-        clientName: o.contactName, workClientName: null, practitioner: o.practitioner, department: null,
+        clientName: o.contactName, workClientName: null, practitioner: o.practitioner, patient: null, department: null,
         orderedOn: null, dueOn: null, jobDate: o.jobDate, shippedOn: o.shippedOn,
         totalCents: o.totalCents, lines: ledgerLines(o.lines), obligation: o,
       };
@@ -129,6 +129,7 @@ export async function boardJobs(db, organisationId, { work = [], accounting = nu
         workClientName: item.clientName ?? null,
         practitioner: item.practitioner ?? o?.practitioner ?? null,
         department: item.department ?? null,
+        patient: item.patient ?? null,
         orderedOn: item.orderedOn ?? null,
         dueOn: item.dueOn ?? null,
         jobDate: o?.jobDate ?? null,

package/server/core/job-match.js

@@ -0,0 +1,241 @@
+import { and, asc, desc, eq, ilike, inArray, isNotNull, isNull, ne, or, sql } from 'drizzle-orm';
+import { billingObligations, contacts, invoiceLines, invoices, priceItems } from '../db/schema.js';
+import { notFound } from './errors.js';
+
+// The Reconcile page (docs/JOB_INVOICE_LINKS.md, "Reconcile"): Flow's own
+// jobs against Flow's own invoices. A job that is ready to invoice and has
+// no Flow invoice, and a Flow invoice that no job is linked to, are gaps.
+// For one of them it lists the possible other side, each fact compared. It
+// only reads; linkJobToInvoice and confirmNoInvoice (ledger.js) write.
+// Matching a Flow invoice to one in an accounting system is that
+// integration's own work, not this page's.
+
+// A job with no Flow invoice that should have one: ready, not held, and not
+// tied to an accounting invoice by the earlier matcher.
+const JOB_GAP = and(
+  isNotNull(billingObligations.readyAt),
+  isNull(billingObligations.invoiceId),
+  isNull(billingObligations.accountingRef),
+  ne(billingObligations.holdState, 'held'),
+);
+
+const hasJob = sql`exists (select 1 from billing_obligations o
+  where o.organisation_id = ${invoices.organisationId} and o.invoice_id = ${invoices.id})`;
+
+const SAME = 'same';
+const DIFFERS = 'differs';
+const daysApart = (a, b) => Math.round((Date.parse(b) - Date.parse(a)) / 86_400_000);
+const norm = (text) => String(text ?? '').trim().replace(/\s+/g, ' ').toLowerCase();
+const WINDOW_DAYS = 60;
+// An invoice's date: its issue date, or the day a draft was made.
+const dateOf = (i) => i.issueDate ?? (i.createdAt ? new Date(i.createdAt).toISOString().slice(0, 10) : null);
+const SHOWN = 3;
+const SEARCHED = 8;
+
+// One fact against the other side's: `same`, `differs`, or null when either
+// side does not know.
+function compare(ours, theirs) {
+  if (ours == null || ours === '' || theirs == null || theirs === '') return null;
+  return norm(ours) === norm(theirs) ? SAME : DIFFERS;
+}
+
+// Two sets of lines, the same price items and amounts in any order.
+function compareLines(a, b) {
+  if (!a.length || !b.length) return null;
+  const key = (l) => `${l.priceItemId ?? norm(l.code)}|${l.amountCents ?? ''}`;
+  return a.map(key).sort().join(',') === b.map(key).sort().join(',') ? SAME : DIFFERS;
+}
+
+// A job line's amount before tax.
+function lineCents(line) {
+  if (line.lineAmountCents != null) return line.lineAmountCents;
+  if (line.unitAmountCents == null) return null;
+  return line.unitAmountCents * (line.quantity ?? 1);
+}
+
+// Every fact of one candidate against the record it may belong to. `a` and
+// `b` are { contactId, reference, date, lines, totalCents }.
+function checksOf(a, b, otherCount) {
+  return {
+    client: a.contactId && b.contactId ? (a.contactId === b.contactId ? SAME : DIFFERS) : null,
+    reference: compare(a.reference, b.reference),
+    date: a.date && b.date ? { days: daysApart(a.date, b.date) } : null,
+    lines: compareLines(a.lines, b.lines),
+    total: a.totalCents == null || b.totalCents == null ? null : a.totalCents === b.totalCents ? SAME : DIFFERS,
+    others: otherCount,
+  };
+}
+
+// Higher is a better match: the total, the lines, the Reference, the date,
+// and not taken by another record.
+function scoreOf(c) {
+  return (c.total === SAME ? 4 : 0) + (c.lines === SAME ? 3 : 0) + (c.reference === SAME ? 3 : 0) + (c.client === SAME ? 2 : 0)
+    + (c.date && Math.abs(c.date.days) <= 3 ? 1 : 0) - (c.others ? 2 : 0);
+}
+
+async function codesFor(db, organisationId, ids) {
+  if (!ids.length) return new Map();
+  const rows = await db.select({ id: priceItems.id, code: priceItems.code }).from(priceItems)
+    .where(and(eq(priceItems.organisationId, organisationId), inArray(priceItems.id, ids)));
+  return new Map(rows.map((r) => [r.id, r.code]));
+}
+
+function jobLines(o, codes) {
+  return (o.lines ?? []).map((l) => ({
+    priceItemId: l.priceItemId ?? null, code: l.itemCode ?? codes.get(l.priceItemId) ?? null, description: l.description ?? null, amountCents: lineCents(l),
+  }));
+}
+
+// The two queues, oldest first. jobs: { id, clientName, practitioner,
+// jobDate, totalCents, possible }; invoices: { id, number, clientName,
+// issueDate, status, totalCents, possible }. `possible` counts the other
+// side with the same client and total.
+export async function listReconcile(db, organisationId) {
+  const jobs = await db.select({
+    id: billingObligations.id,
+    clientName: contacts.name,
+    practitioner: billingObligations.practitioner,
+    jobDate: billingObligations.jobDate,
+    totalCents: billingObligations.totalCents,
+    possible: sql`(select count(*) from invoices i
+      where i.organisation_id = ${billingObligations.organisationId} and i.contact_id = ${billingObligations.contactId}
+        and i.status <> 'void' and i.total_cents = ${billingObligations.totalCents}
+        and not exists (select 1 from billing_obligations x where x.organisation_id = i.organisation_id and x.invoice_id = i.id))`.mapWith(Number),
+  }).from(billingObligations)
+    .leftJoin(contacts, eq(contacts.id, billingObligations.contactId))
+    .where(and(eq(billingObligations.organisationId, organisationId), JOB_GAP))
+    .orderBy(sql`${billingObligations.jobDate} asc nulls last`, asc(billingObligations.createdAt));
+  const lonely = await db.select({
+    id: invoices.id,
+    number: invoices.number,
+    clientName: contacts.name,
+    issueDate: sql`coalesce(${invoices.issueDate}, ${invoices.createdAt}::date)::text`,
+    status: invoices.status,
+    totalCents: invoices.totalCents,
+    possible: sql`(select count(*) from billing_obligations o
+      where o.organisation_id = ${invoices.organisationId} and o.contact_id = ${invoices.contactId}
+        and o.invoice_id is null and o.accounting_ref is null and o.total_cents = ${invoices.totalCents})`.mapWith(Number),
+  }).from(invoices)
+    .leftJoin(contacts, eq(contacts.id, invoices.contactId))
+    .where(and(eq(invoices.organisationId, organisationId), ne(invoices.status, 'void'), sql`not ${hasJob}`))
+    .orderBy(sql`${invoices.issueDate} asc nulls last`, asc(invoices.createdAt));
+  return { jobs, invoices: lonely };
+}
+
+// One job and the Flow invoices that may be its own, best first. With `q`,
+// any Flow invoice whose number, client, Reference or total matches.
+// `reference` is the Reference Flow would give the job's invoice.
+export async function jobMatchDetail(db, organisationId, obligationId, { reference = null, q = '' } = {}) {
+  const [row] = await db.select({ obligation: billingObligations, clientName: contacts.name })
+    .from(billingObligations)
+    .leftJoin(contacts, eq(contacts.id, billingObligations.contactId))
+    .where(and(eq(billingObligations.organisationId, organisationId), eq(billingObligations.id, obligationId)));
+  if (!row) throw notFound('job');
+  const o = row.obligation;
+  const codes = await codesFor(db, organisationId, (o.lines ?? []).map((l) => l.priceItemId).filter(Boolean));
+  const job = {
+    id: o.id,
+    clientName: row.clientName,
+    practitioner: o.practitioner,
+    reference,
+    jobDate: o.jobDate,
+    sourceSystem: o.sourceSystem,
+    sourceJobRef: o.sourceJobRef,
+    caseRef: o.caseRef,
+    sourceStatus: o.sourceStatus,
+    lines: jobLines(o, codes),
+    totalCents: o.totalCents,
+    open: !o.invoiceId && !o.accountingRef,
+    // An unclear accounting match: "Make invoice" settles it first.
+    unclear: o.accountingState === 'ambiguous',
+  };
+
+  const search = String(q ?? '').trim();
+  const where = [eq(invoices.organisationId, organisationId), ne(invoices.status, 'void')];
+  if (search) where.push(searchInvoices(search));
+  else {
+    if (!o.contactId) return { job, invoices: [] };
+    where.push(eq(invoices.contactId, o.contactId));
+    if (o.jobDate) where.push(sql`abs(coalesce(${invoices.issueDate}, ${invoices.createdAt}::date) - ${o.jobDate}::date) <= ${WINDOW_DAYS}`);
+  }
+  const found = await db.select({ invoice: invoices, clientName: contacts.name }).from(invoices)
+    .leftJoin(contacts, eq(contacts.id, invoices.contactId))
+    .where(and(...where)).orderBy(desc(invoices.createdAt)).limit(50);
+  const detail = await invoiceFacts(db, organisationId, found.map((f) => f.invoice));
+  const ours = { contactId: o.contactId, reference, date: o.jobDate, lines: job.lines, totalCents: o.totalCents };
+  const ranked = found.map(({ invoice, clientName }) => {
+    const d = detail.get(invoice.id);
+    const checks = checksOf(ours, { contactId: invoice.contactId, reference: invoice.reference, date: dateOf(invoice), lines: d.lines, totalCents: invoice.totalCents }, d.jobs.length);
+    return {
+      id: invoice.id, number: invoice.number, clientName, issueDate: invoice.issueDate, date: dateOf(invoice), status: invoice.status,
+      reference: invoice.reference, lines: d.lines, totalCents: invoice.totalCents, jobs: d.jobs, checks, score: scoreOf(checks),
+    };
+  }).sort((a, b) => b.score - a.score).slice(0, search ? SEARCHED : SHOWN);
+  return { job, invoices: ranked.map((c, index) => ({ ...c, best: index === 0 && c.score > 0 })) };
+}
+
+// One Flow invoice with no job, and the jobs with no invoice that may be its
+// own, best first.
+export async function invoiceMatchDetail(db, organisationId, invoiceId, { q = '' } = {}) {
+  const [row] = await db.select({ invoice: invoices, clientName: contacts.name }).from(invoices)
+    .leftJoin(contacts, eq(contacts.id, invoices.contactId))
+    .where(and(eq(invoices.organisationId, organisationId), eq(invoices.id, invoiceId)));
+  if (!row) throw notFound('invoice');
+  const i = row.invoice;
+  const d = (await invoiceFacts(db, organisationId, [i])).get(i.id);
+  const invoice = {
+    id: i.id, number: i.number, clientName: row.clientName, issueDate: i.issueDate, date: dateOf(i), status: i.status, reference: i.reference,
+    lines: d.lines, totalCents: i.totalCents, jobs: d.jobs, open: d.jobs.length === 0 && i.status !== 'void',
+  };
+  const search = String(q ?? '').trim();
+  const where = [eq(billingObligations.organisationId, organisationId), isNull(billingObligations.invoiceId), isNull(billingObligations.accountingRef)];
+  if (search) {
+    const like = `%${search.replace(/[%_\\]/g, '\\$&')}%`;
+    where.push(or(ilike(contacts.name, like), ilike(billingObligations.practitioner, like), ilike(billingObligations.caseRef, like), ilike(billingObligations.sourceJobRef, like)));
+  } else {
+    where.push(eq(billingObligations.contactId, i.contactId));
+    if (invoice.date) where.push(sql`abs(coalesce(${billingObligations.jobDate}, ${billingObligations.createdAt}::date) - ${invoice.date}::date) <= ${WINDOW_DAYS}`);
+  }
+  const found = await db.select({ obligation: billingObligations, clientName: contacts.name }).from(billingObligations)
+    .leftJoin(contacts, eq(contacts.id, billingObligations.contactId))
+    .where(and(...where)).orderBy(desc(billingObligations.createdAt)).limit(50);
+  const codes = await codesFor(db, organisationId, found.flatMap((f) => (f.obligation.lines ?? []).map((l) => l.priceItemId)).filter(Boolean));
+  const theirs = { contactId: i.contactId, reference: i.reference, date: invoice.date, lines: d.lines, totalCents: i.totalCents };
+  const ranked = found.map(({ obligation: o, clientName }) => {
+    const lines = jobLines(o, codes);
+    const checks = checksOf(theirs, { contactId: o.contactId, reference: null, date: o.jobDate, lines, totalCents: o.totalCents }, 0);
+    return {
+      id: o.id, clientName, practitioner: o.practitioner, jobDate: o.jobDate, caseRef: o.caseRef, sourceStatus: o.sourceStatus,
+      sourceSystem: o.sourceSystem, lines, totalCents: o.totalCents, ready: Boolean(o.readyAt), checks, score: scoreOf(checks),
+    };
+  }).sort((a, b) => b.score - a.score).slice(0, search ? SEARCHED : SHOWN);
+  return { invoice, jobs: ranked.map((c, index) => ({ ...c, best: index === 0 && c.score > 0 })) };
+}
+
+// A search box's words against Flow invoices: number, client, Reference, or
+// a total in dollars ("150" or "$150.00").
+function searchInvoices(search) {
+  const like = `%${search.replace(/[%_\\]/g, '\\$&')}%`;
+  const terms = [ilike(invoices.number, like), ilike(contacts.name, like), ilike(invoices.reference, like)];
+  const amount = /^\$?\s*(\d+(?:,\d{3})*(?:\.\d{1,2})?)$/.exec(search);
+  if (amount) terms.push(eq(invoices.totalCents, Math.round(Number(amount[1].replace(/,/g, '')) * 100)));
+  return or(...terms);
+}
+
+// Each invoice's lines (code and amount before tax) and the jobs linked to it.
+async function invoiceFacts(db, organisationId, rows) {
+  const ids = rows.map((r) => r.id);
+  const facts = new Map(ids.map((id) => [id, { lines: [], jobs: [] }]));
+  if (!ids.length) return facts;
+  const lines = await db.select({ invoiceId: invoiceLines.invoiceId, priceItemId: invoiceLines.priceItemId, code: priceItems.code, description: invoiceLines.description, amountCents: invoiceLines.lineAmountCents })
+    .from(invoiceLines)
+    .leftJoin(priceItems, eq(priceItems.id, invoiceLines.priceItemId))
+    .where(and(eq(invoiceLines.organisationId, organisationId), inArray(invoiceLines.invoiceId, ids)))
+    .orderBy(asc(invoiceLines.position));
+  for (const { invoiceId, ...line } of lines) facts.get(invoiceId).lines.push(line);
+  const jobs = await db.select({ id: billingObligations.id, invoiceId: billingObligations.invoiceId, jobDate: billingObligations.jobDate, practitioner: billingObligations.practitioner })
+    .from(billingObligations)
+    .where(and(eq(billingObligations.organisationId, organisationId), inArray(billingObligations.invoiceId, ids)));
+  for (const { invoiceId, ...job } of jobs) facts.get(invoiceId).jobs.push(job);
+  return facts;
+}