@arcforgelabs/flow 2026.10.25 → 2026.10.26

package/README.md

@@ -33,6 +33,7 @@ run a lab.
 | `docs/DESIGN.md` | The design systems (theme families), how pages and Clerk's components take them, and the screens |
 | `docs/DATA_MODEL.md` | The PostgreSQL records, the rules the database holds, and how to change the schema |
 | `docs/DATA_SPINE.md` | The design of the tables and jobs every integration shares: mirror, identity map, job queue, outbox, review queue |
+| `docs/JOB_INVOICE_LINKS.md` | The pipeline: how each job links to its customer and to the accounting invoice that bills it |
 | `docs/RELEASING.md` | Versions and channels, the release workflows, how to cut and roll back a release, and the one-time setup |
 | `docs/SELF_HOSTING.md` | Running a Flow release with Docker, Node or Replit, the update notice, and Clerk sign-in |
 | `docs/REPLIT.md` | A Replit workspace of this repository that follows a release channel (`FLOW_DEPLOY_REF`) |

package/npm-shrinkwrap.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcforgelabs/flow",
-  "version": "2026.10.25",
+  "version": "2026.10.26",
   "description": "Invoicing, bill entry and a financial dashboard for labs, with Seazona and Xero integrations.",
   "license": "MIT",
   "repository": {
@@ -31,6 +31,7 @@
   "scripts": {
     "start": "node server/index.js",
     "test": "node --test --test-concurrency=1 test/*.test.js",
+    "theme:contrast": "node scripts/theme-contrast.mjs",
     "db:generate": "drizzle-kit generate"
   },
   "dependencies": {

package/server/api/invoicing.js

@@ -0,0 +1,375 @@
+import { and, asc, desc, eq, ilike, inArray, isNull, or, sql } from 'drizzle-orm';
+import express from 'express';
+import { FlowError } from '../core/errors.js';
+import {
+  createDraftInvoice, getInvoice, issueInvoice, listInvoiceVersions, reviseInvoice, updateDraftInvoice, voidInvoice,
+} from '../core/invoices.js';
+import { draftInvoiceForObligation, listObligations } from '../core/ledger.js';
+import {
+  billingObligations, contacts, invoices, INVOICE_STATUSES, organisations, priceItems, TAX_CODES,
+} from '../db/schema.js';
+
+// Invoicing for people signed in to Flow, mounted at /api/invoicing. The web
+// UI's invoices, customers, price list and jobs pages read and write here.
+//
+//   GET   /context                    the organisations, and whether this person may issue
+//   GET   /invoices?organisationId=&status=&q=&limit=   newest first, with counts by status
+//   GET   /invoices/:id               one invoice: lines, contact, job, issued versions
+//   POST  /invoices                   a new draft
+//   PATCH /invoices/:id               change a draft
+//   POST  /invoices/:id/issue         owner or admin: number it and keep the document as sent
+//   POST  /invoices/:id/revise        owner or admin: an issued invoice back to a draft
+//   POST  /invoices/:id/void          owner or admin
+//   GET   /contacts?q=&limit=         customers, by name
+//   GET   /price-items?q=             the price list, by code
+//   GET   /jobs?view=&limit=          billable jobs (the obligation ledger), with counts by view
+//   POST  /jobs/:id/draft             owner or admin: a job's draft invoice, after a live
+//                                     check that the accounting system holds none
+//
+// Every route needs a signed-in, active person; reading and drafting are open
+// to every role. `organisationId` (query or body) names the organisation; it
+// may be left out while the installation has exactly one. Money is integer
+// cents. `liveCheckFor(organisationId)` returns the ledger's live check for
+// that organisation, or null when no accounting integration offers one.
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+const VIEWS = ['ready', 'pending', 'drafted', 'invoiced', 'paid', 'held', 'review_required'];
+const MAX_LINES = 200;
+const MAX_TEXT = 500;
+// Each line's amount must fit the database's integer columns with room for
+// the invoice total.
+const MAX_QUANTITY = 100_000;
+const MAX_UNIT_CENTS = 100_000_000;
+
+const ERROR_STATUS = {
+  invalid: 400, organisation_required: 400, not_found: 404, not_draft: 409, not_issued: 409,
+  never_issued: 409, not_ready: 409, live_check_unavailable: 409,
+};
+
+function sendError(res, error, log) {
+  // A value PostgreSQL refuses (a number out of range, a date that does not
+  // exist) is the caller's mistake, not a server fault.
+  const pgCode = error.code ?? error.cause?.code;
+  if (!(error instanceof FlowError) && ['22003', '22008', '22007', '22P02'].includes(pgCode)) {
+    return res.status(400).json({ ok: false, code: 'invalid', error: 'a value is out of range or not valid' });
+  }
+  if (!(error instanceof FlowError)) {
+    log.error?.(`[invoicing] ${error.message}`);
+    return res.status(500).json({ ok: false, code: 'internal', error: 'Something went wrong.' });
+  }
+  const body = { ok: false, code: error.code, error: error.message };
+  if (error.details !== undefined) body.details = error.details;
+  return res.status(error.status ?? ERROR_STATUS[error.code] ?? 400).json(body);
+}
+
+const handle = (log, fn) => async (req, res) => {
+  try {
+    await fn(req, res);
+  } catch (error) {
+    sendError(res, error, log);
+  }
+};
+
+const invalid = (message) => new FlowError('invalid', message);
+const text = (raw) => (typeof raw === 'string' ? raw.trim() : '');
+const pathId = (raw, what) => {
+  if (!UUID.test(raw ?? '')) throw new FlowError('not_found', `${what} not found`);
+  return raw;
+};
+
+function limitOf(raw, fallback, max) {
+  if (raw === undefined) return fallback;
+  const n = Number(text(raw));
+  if (!Number.isInteger(n) || n < 1) throw invalid(`limit must be a whole number from 1 to ${max}`);
+  return Math.min(n, max);
+}
+
+// A LIKE pattern that matches the text anywhere, with its wildcards escaped.
+const containing = (q) => `%${q.replace(/[\\%_]/g, (c) => `\\${c}`)}%`;
+
+function isRealDate(value) {
+  if (!DATE.test(value)) return false;
+  const d = new Date(`${value}T00:00:00Z`);
+  return !Number.isNaN(d.getTime()) && d.toISOString().slice(0, 10) === value;
+}
+
+function optionalText(raw, name) {
+  if (raw === undefined || raw === null) return null;
+  if (typeof raw !== 'string') throw invalid(`${name} must be text`);
+  if (raw.length > MAX_TEXT) throw invalid(`${name} is too long (${MAX_TEXT} characters at most)`);
+  return raw.trim() || null;
+}
+
+function optionalDate(raw, name) {
+  if (raw === undefined || raw === null || raw === '') return null;
+  if (typeof raw !== 'string' || !isRealDate(raw)) throw invalid(`${name} must be a date, YYYY-MM-DD`);
+  return raw;
+}
+
+function requireBodyId(raw, name) {
+  if (typeof raw !== 'string' || !UUID.test(raw)) throw invalid(`${name} must be a Flow id`);
+  return raw;
+}
+
+function readLines(raw) {
+  if (!Array.isArray(raw)) throw invalid('lines must be a list');
+  if (raw.length > MAX_LINES) throw invalid(`an invoice has ${MAX_LINES} lines at most`);
+  return raw.map((line, index) => {
+    const at = `line ${index + 1}`;
+    if (!line || typeof line !== 'object' || Array.isArray(line)) throw invalid(`${at} must be an object`);
+    const out = {};
+    if (line.priceItemId !== undefined && line.priceItemId !== null) out.priceItemId = requireBodyId(line.priceItemId, `${at}: priceItemId`);
+    // A blank description takes the price item's name.
+    const description = optionalText(line.description, `${at}: description`);
+    if (description) out.description = description;
+    if (line.quantity !== undefined) {
+      if (!Number.isInteger(line.quantity) || line.quantity < 1 || line.quantity > MAX_QUANTITY) {
+        throw invalid(`${at}: quantity must be a whole number from 1 to ${MAX_QUANTITY}`);
+      }
+      out.quantity = line.quantity;
+    }
+    if (line.unitAmountCents !== undefined && line.unitAmountCents !== null) {
+      if (!Number.isInteger(line.unitAmountCents) || Math.abs(line.unitAmountCents) > MAX_UNIT_CENTS) {
+        throw invalid(`${at}: unitAmountCents must be whole cents`);
+      }
+      out.unitAmountCents = line.unitAmountCents;
+    }
+    if (line.taxCode !== undefined && line.taxCode !== null) {
+      if (!TAX_CODES.includes(line.taxCode)) throw invalid(`${at}: taxCode must be one of ${TAX_CODES.join(', ')}`);
+      out.taxCode = line.taxCode;
+    }
+    return out;
+  });
+}
+
+// The server's own calendar date.
+function today() {
+  const d = new Date();
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
+}
+
+// The organisation a request is about: the one it names, or the only one.
+export async function resolveOrganisation(db, raw) {
+  if (raw !== undefined && raw !== null && raw !== '') {
+    const organisationId = text(raw);
+    if (!UUID.test(organisationId)) throw invalid('organisationId must be a Flow organisation id');
+    const [row] = await db.select({ id: organisations.id }).from(organisations).where(eq(organisations.id, organisationId));
+    if (!row) throw new FlowError('not_found', 'organisation not found');
+    return organisationId;
+  }
+  const rows = await db.select({ id: organisations.id }).from(organisations).limit(2);
+  if (rows.length === 1) return rows[0].id;
+  throw new FlowError('organisation_required', rows.length
+    ? 'This installation has more than one organisation: say which one (organisationId).'
+    : 'This installation has no organisation yet.');
+}
+
+const jobOf = (o) => (o ? {
+  id: o.id, sourceSystem: o.sourceSystem, sourceJobRef: o.sourceJobRef, caseRef: o.caseRef, practitioner: o.practitioner, shippedOn: o.shippedOn,
+} : null);
+
+async function jobsByInvoice(db, organisationId, invoiceIds) {
+  if (!invoiceIds.length) return new Map();
+  const rows = await db.select().from(billingObligations)
+    .where(and(eq(billingObligations.organisationId, organisationId), inArray(billingObligations.invoiceId, invoiceIds)));
+  return new Map(rows.map((o) => [o.invoiceId, jobOf(o)]));
+}
+
+async function invoiceDetail(db, organisationId, invoiceId) {
+  const invoice = await getInvoice(db, organisationId, invoiceId);
+  const [[contact], versions, jobs] = await Promise.all([
+    db.select({ id: contacts.id, name: contacts.name, email: contacts.email }).from(contacts)
+      .where(and(eq(contacts.organisationId, organisationId), eq(contacts.id, invoice.contactId))),
+    listInvoiceVersions(db, organisationId, invoiceId),
+    jobsByInvoice(db, organisationId, [invoiceId]),
+  ]);
+  return {
+    ...invoice,
+    contact: contact ?? null,
+    job: jobs.get(invoiceId) ?? null,
+    versions: versions.map(({ version, issuedAt, issuedBy }) => ({ version, issuedAt, issuedBy })),
+  };
+}
+
+export function createInvoicingRouter({ db, personAuth, log = console, liveCheckFor = () => null }) {
+  const router = express.Router();
+  router.use(express.json({ limit: '64kb' }));
+
+  const signedIn = [personAuth.requireSession];
+  const manager = [...signedIn, personAuth.requireRole('owner', 'admin')];
+  const organisationOf = (req) => resolveOrganisation(db, req.method === 'GET' ? req.query.organisationId : (req.body?.organisationId ?? req.query.organisationId));
+
+  router.get('/context', ...signedIn, handle(log, async (req, res) => {
+    const rows = await db.select({
+      id: organisations.id, name: organisations.name, invoicePrefix: organisations.invoicePrefix, nextInvoiceNumber: organisations.nextInvoiceNumber,
+    }).from(organisations).orderBy(asc(organisations.name));
+    res.json({ ok: true, organisations: rows, canIssue: ['owner', 'admin'].includes(req.person.role) });
+  }));
+
+  router.get('/invoices', ...signedIn, handle(log, async (req, res) => {
+    const organisationId = await organisationOf(req);
+    const status = text(req.query.status);
+    if (status && !INVOICE_STATUSES.includes(status)) throw invalid(`status must be one of ${INVOICE_STATUSES.join(', ')}`);
+    const q = text(req.query.q);
+    const limit = limitOf(req.query.limit, 200, 500);
+    const where = [eq(invoices.organisationId, organisationId)];
+    if (status) where.push(eq(invoices.status, status));
+    if (q) {
+      const pattern = containing(q);
+      where.push(or(ilike(invoices.number, pattern), ilike(invoices.reference, pattern), ilike(contacts.name, pattern)));
+    }
+    const rows = await db.select({ invoice: invoices, contactName: contacts.name }).from(invoices)
+      .leftJoin(contacts, eq(contacts.id, invoices.contactId))
+      .where(and(...where))
+      .orderBy(desc(invoices.createdAt), desc(invoices.id))
+      .limit(limit);
+    const jobs = await jobsByInvoice(db, organisationId, rows.map((r) => r.invoice.id));
+    const counted = await db.select({ status: invoices.status, n: sql`count(*)::int` }).from(invoices)
+      .where(eq(invoices.organisationId, organisationId)).groupBy(invoices.status);
+    const counts = Object.fromEntries(INVOICE_STATUSES.map((s) => [s, 0]));
+    for (const { status: s, n } of counted) counts[s] = n;
+    res.json({
+      ok: true,
+      invoices: rows.map(({ invoice, contactName }) => ({ ...invoice, contactName, job: jobs.get(invoice.id) ?? null })),
+      counts,
+    });
+  }));
+
+  router.get('/invoices/:id', ...signedIn, handle(log, async (req, res) => {
+    const invoiceId = pathId(req.params.id, 'invoice');
+    const organisationId = await organisationOf(req);
+    res.json({ ok: true, invoice: await invoiceDetail(db, organisationId, invoiceId) });
+  }));
+
+  router.post('/invoices', ...signedIn, handle(log, async (req, res) => {
+    const organisationId = await organisationOf(req);
+    const body = req.body ?? {};
+    const draft = await createDraftInvoice(db, organisationId, {
+      contactId: requireBodyId(body.contactId, 'contactId'),
+      reference: optionalText(body.reference, 'reference'),
+      dueDate: optionalDate(body.dueDate, 'dueDate'),
+      lines: body.lines === undefined ? [] : readLines(body.lines),
+    });
+    log.info?.(`[invoicing] organisation ${organisationId}: person ${req.person.id} made draft invoice ${draft.id}`);
+    res.status(201).json({ ok: true, invoice: await invoiceDetail(db, organisationId, draft.id) });
+  }));
+
+  router.patch('/invoices/:id', ...signedIn, handle(log, async (req, res) => {
+    const invoiceId = pathId(req.params.id, 'invoice');
+    const organisationId = await organisationOf(req);
+    const body = req.body ?? {};
+    const changes = {};
+    if (body.contactId !== undefined) changes.contactId = requireBodyId(body.contactId, 'contactId');
+    if (body.reference !== undefined) changes.reference = optionalText(body.reference, 'reference');
+    if (body.dueDate !== undefined) changes.dueDate = optionalDate(body.dueDate, 'dueDate');
+    if (body.lines !== undefined) changes.lines = readLines(body.lines);
+    if (!Object.keys(changes).length) throw invalid('nothing to change: send contactId, reference, dueDate or lines');
+    await updateDraftInvoice(db, organisationId, invoiceId, changes);
+    res.json({ ok: true, invoice: await invoiceDetail(db, organisationId, invoiceId) });
+  }));
+
+  router.post('/invoices/:id/issue', ...manager, handle(log, async (req, res) => {
+    const invoiceId = pathId(req.params.id, 'invoice');
+    const organisationId = await organisationOf(req);
+    const issueDate = optionalDate(req.body?.issueDate, 'issueDate') ?? today();
+    const issued = await issueInvoice(db, organisationId, invoiceId, { issuedBy: `person:${req.person.id}`, issueDate });
+    log.info?.(`[invoicing] organisation ${organisationId}: person ${req.person.id} issued invoice ${issued.number} (version ${issued.issuedVersion})`);
+    res.json({ ok: true, invoice: await invoiceDetail(db, organisationId, invoiceId) });
+  }));
+
+  router.post('/invoices/:id/revise', ...manager, handle(log, async (req, res) => {
+    const invoiceId = pathId(req.params.id, 'invoice');
+    const organisationId = await organisationOf(req);
+    await reviseInvoice(db, organisationId, invoiceId);
+    log.info?.(`[invoicing] organisation ${organisationId}: person ${req.person.id} opened invoice ${invoiceId} for revision`);
+    res.json({ ok: true, invoice: await invoiceDetail(db, organisationId, invoiceId) });
+  }));
+
+  router.post('/invoices/:id/void', ...manager, handle(log, async (req, res) => {
+    const invoiceId = pathId(req.params.id, 'invoice');
+    const organisationId = await organisationOf(req);
+    await voidInvoice(db, organisationId, invoiceId);
+    log.info?.(`[invoicing] organisation ${organisationId}: person ${req.person.id} voided invoice ${invoiceId}`);
+    res.json({ ok: true, invoice: await invoiceDetail(db, organisationId, invoiceId) });
+  }));
+
+  router.get('/contacts', ...signedIn, handle(log, async (req, res) => {
+    const organisationId = await organisationOf(req);
+    const q = text(req.query.q);
+    const where = [eq(contacts.organisationId, organisationId), eq(contacts.kind, 'customer')];
+    if (q) where.push(ilike(contacts.name, containing(q)));
+    const rows = await db.select({ id: contacts.id, name: contacts.name, email: contacts.email }).from(contacts)
+      .where(and(...where)).orderBy(asc(contacts.name), asc(contacts.id)).limit(limitOf(req.query.limit, 50, 500));
+    res.json({ ok: true, contacts: rows });
+  }));
+
+  router.get('/price-items', ...signedIn, handle(log, async (req, res) => {
+    const organisationId = await organisationOf(req);
+    const q = text(req.query.q);
+    const where = [eq(priceItems.organisationId, organisationId), isNull(priceItems.archivedAt)];
+    if (q) where.push(or(ilike(priceItems.code, containing(q)), ilike(priceItems.name, containing(q))));
+    const rows = await db.select({
+      id: priceItems.id, code: priceItems.code, name: priceItems.name, unitAmountCents: priceItems.unitAmountCents, taxCode: priceItems.taxCode,
+    }).from(priceItems).where(and(...where)).orderBy(asc(priceItems.code));
+    res.json({ ok: true, priceItems: rows });
+  }));
+
+  router.get('/jobs', ...signedIn, handle(log, async (req, res) => {
+    const organisationId = await organisationOf(req);
+    const view = text(req.query.view);
+    if (view && !VIEWS.includes(view)) throw invalid(`view must be one of ${VIEWS.join(', ')}`);
+    const limit = limitOf(req.query.limit, 200, 500);
+    const all = await listObligations(db, organisationId);
+    const counts = Object.fromEntries(VIEWS.map((v) => [v, 0]));
+    for (const entry of all) counts[entry.view] += 1;
+    const listed = (view ? all.filter((entry) => entry.view === view) : all).slice(0, limit);
+    const contactIds = [...new Set(listed.map((e) => e.obligation.contactId).filter(Boolean))];
+    const invoiceIds = [...new Set(listed.map((e) => e.obligation.invoiceId).filter(Boolean))];
+    const [names, numbers] = await Promise.all([
+      contactIds.length
+        ? db.select({ id: contacts.id, name: contacts.name }).from(contacts)
+          .where(and(eq(contacts.organisationId, organisationId), inArray(contacts.id, contactIds)))
+        : [],
+      invoiceIds.length
+        ? db.select({ id: invoices.id, number: invoices.number, status: invoices.status }).from(invoices)
+          .where(and(eq(invoices.organisationId, organisationId), inArray(invoices.id, invoiceIds)))
+        : [],
+    ]);
+    const nameOf = new Map(names.map((c) => [c.id, c.name]));
+    const invoiceOf = new Map(numbers.map((i) => [i.id, i]));
+    res.json({
+      ok: true,
+      jobs: listed.map(({ obligation: { lineFingerprint: _fingerprint, organisationId: _org, ...o }, view: v, reasons }) => ({
+        ...o,
+        contactName: nameOf.get(o.contactId) ?? null,
+        invoiceNumber: invoiceOf.get(o.invoiceId)?.number ?? null,
+        invoiceStatus: invoiceOf.get(o.invoiceId)?.status ?? null,
+        view: v,
+        reasons,
+      })),
+      counts,
+    });
+  }));
+
+  router.post('/jobs/:id/draft', ...manager, handle(log, async (req, res) => {
+    const obligationId = pathId(req.params.id, 'job');
+    const organisationId = await organisationOf(req);
+    const liveCheck = liveCheckFor(organisationId);
+    if (typeof liveCheck !== 'function') {
+      throw new FlowError('live_check_unavailable', 'Flow drafts a job\'s invoice only after checking that the accounting system holds none for it. Turn on and connect Xero first.');
+    }
+    const { invoice } = await draftInvoiceForObligation(db, organisationId, obligationId, { liveCheck, actor: `person:${req.person.id}` });
+    log.info?.(`[invoicing] organisation ${organisationId}: person ${req.person.id} drafted invoice ${invoice.id} from job ${obligationId}`);
+    res.status(201).json({ ok: true, invoice: await invoiceDetail(db, organisationId, invoice.id) });
+  }));
+
+  // A body that is not JSON, or too large, answers like every other refusal.
+  router.use((error, _req, res, next) => {
+    if (error?.type === 'entity.too.large') return res.status(413).json({ ok: false, code: 'too_large', error: 'The request body is too large.' });
+    if (error?.status === 400 || error?.type === 'entity.parse.failed') return res.status(400).json({ ok: false, code: 'invalid', error: 'The request body must be JSON.' });
+    return next(error);
+  });
+
+  return router;
+}

package/server/app.js

@@ -1,5 +1,6 @@
 import express from 'express';
 import { createConnectorApi } from './api/connector.js';
+import { createInvoicingRouter } from './api/invoicing.js';
 import { createSignInRouter } from './auth/routes.js';
 import { deployedBuildStatus } from './deployed-build.js';
 import { integrationsHealth } from './integrations/health.js';
@@ -100,6 +101,16 @@ export function createApp({
   if (integrations && database && auth?.personAuth) {
     app.use('/api/integrations', createSetupRouter({ db: database.db, registry: integrations, personAuth: auth.personAuth, secrets, log }));
   }
+  // Invoicing for signed-in people (server/api/invoicing.js). A job's draft
+  // invoice needs a live check in the accounting system: the first enabled
+  // integration that offers `checkInvoice` (Xero) answers it.
+  if (database && auth?.personAuth) {
+    const liveCheckFor = (organisationId) => {
+      const [adapter] = integrations?.with('checkInvoice') ?? [];
+      return adapter ? (obligation) => adapter.capabilities.checkInvoice({ organisationId, obligation }) : null;
+    };
+    app.use('/api/invoicing', createInvoicingRouter({ db: database.db, personAuth: auth.personAuth, log, liveCheckFor }));
+  }
   for (const { path, handler } of integrations?.routes({ db: database?.db ?? null, personAuth: auth?.personAuth ?? null, log, messagePage: page }) ?? []) {
     app.use(path, handler);
   }

package/server/auth/people.js

@@ -1,6 +1,7 @@
 import { and, asc, eq, isNull, ne, sql } from 'drizzle-orm';
 import { people, PERSON_ROLES } from '../db/schema.js';
 import { FlowError } from '../core/errors.js';
+import { isThemeFamily, normalizeAccent } from '../theme/themes.js';
 import { isPlainEmail } from './settings.js';
 
 // The people who may sign in, and their roles. Only an owner changes this
@@ -24,6 +25,31 @@ export function publicPerson(row) {
   };
 }
 
+const COLOR_MODES = ['light', 'dark', 'system'];
+
+// A person's appearance as Flow stores it: only the known keys, each checked.
+// A family Flow does not have, or a malformed accent, is dropped, so the page
+// falls back to the installation's default.
+export function normaliseAppearance(input) {
+  const value = input && typeof input === 'object' ? input : {};
+  const out = { colorMode: COLOR_MODES.includes(value.colorMode) ? value.colorMode : 'system' };
+  if (isThemeFamily(value.themeFamily)) out.themeFamily = value.themeFamily;
+  const accent = typeof value.accent === 'string' ? value.accent.trim().toLowerCase() : '';
+  if (normalizeAccent(accent)) out.accent = accent;
+  return out;
+}
+
+// Each person keeps their own appearance, so people who share a browser or
+// move between devices each see theirs.
+export async function setPersonAppearance(db, { id, appearance }) {
+  const [row] = await db.update(people)
+    .set({ appearance: normaliseAppearance(appearance), updatedAt: new Date() })
+    .where(eq(people.id, id))
+    .returning();
+  if (!row) throw new FlowError('not_found', 'person not found');
+  return row.appearance;
+}
+
 export async function findPersonById(db, id) {
   const [row] = await db.select().from(people).where(eq(people.id, id));
   return row ?? null;

package/server/auth/routes.js

@@ -7,8 +7,10 @@ import {
   invitePerson,
   listPeople,
   normaliseEmail,
+  normaliseAppearance,
   publicPerson,
   removePerson,
+  setPersonAppearance,
   updatePerson,
 } from './people.js';
 import { isPlainEmail } from './settings.js';
@@ -96,9 +98,20 @@ export function createSignInRouter({ settings, db, clerk, personAuth, defaultFam
       const check = await ownerVerification(req.person, req.clerkAuth);
       body.ownerActions = { allowed: Boolean(check.verified), by: check.by ?? null };
     }
+    body.appearance = req.person.appearance ? normaliseAppearance(req.person.appearance) : null;
     res.json(body);
   });
 
+  // Each person sets their own appearance; it follows their account.
+  router.put('/api/me/appearance', requireSession, express.json({ limit: '4kb' }), async (req, res) => {
+    try {
+      const appearance = await setPersonAppearance(db, { id: req.person.id, appearance: req.body });
+      res.json({ ok: true, appearance });
+    } catch (error) {
+      sendError(res, error, log);
+    }
+  });
+
   // Only an owner manages people.
   const people = express.Router();
   people.use(requireSession, requireOwner, express.json({ limit: '16kb' }));

package/server/core/invoices.js

@@ -87,6 +87,13 @@ export async function updateDraftInvoice(db, organisationId, invoiceId, changes)
     const invoice = await loadInvoice(tx, organisationId, invoiceId, { lock: true });
     if (invoice.status !== 'draft') throw new FlowError('not_draft', 'only a draft invoice can change; revise it first');
     const fields = {};
+    if ('contactId' in changes && changes.contactId !== invoice.contactId) {
+      const [contact] = await tx.select().from(contacts)
+        .where(and(eq(contacts.organisationId, organisationId), eq(contacts.id, changes.contactId)));
+      if (!contact) throw new FlowError('invalid', 'contact not found');
+      if (contact.kind !== 'customer') throw new FlowError('invalid', 'an invoice goes to a customer contact');
+      fields.contactId = changes.contactId;
+    }
     if ('reference' in changes) fields.reference = changes.reference;
     if ('dueDate' in changes) fields.dueDate = changes.dueDate;
     let row = invoice;

package/server/core/ledger.js

@@ -16,8 +16,10 @@ import { invoiceTotals, lineTotals } from './money.js';
 // How old the work system's report of a job may be when Flow drafts its invoice.
 export const SOURCE_MAX_AGE_MS = 24 * 60 * 60 * 1000;
 
-// Ways to tie accounting evidence to a job that are exact, not a guess.
-export const EXACT_MATCHES = ['flow_invoice', 'source_invoice_ref', 'accounting_ref'];
+// Ways to tie accounting evidence to a job that are exact, not a guess:
+// `prior_link` is a link the earlier installation held, checked against the
+// accounting mirror; `person` is a link a person chose.
+export const EXACT_MATCHES = ['flow_invoice', 'source_invoice_ref', 'accounting_ref', 'prior_link', 'person'];
 
 const LINKED_STATES = ['drafted', 'authorised', 'part_paid', 'paid', 'voided', 'deleted'];
 
@@ -107,6 +109,7 @@ export async function observeJob(db, organisationId, job) {
       contactId: job.contactId ?? null,
       practitioner: job.practitioner ?? null,
       shippedOn: job.shippedOn ?? null,
+      jobDate: job.jobDate ?? null,
       lines,
       lineFingerprint: fingerprint(lines),
       ...invoiceTotals(lines),
@@ -135,7 +138,7 @@ export async function observeJob(db, organisationId, job) {
     const changed = ['sourceInvoiceRef', 'caseRef', 'contactId', 'practitioner', 'shippedOn', 'lineFingerprint', 'totalCents']
       .filter((key) => String(existing[key] ?? '') !== String(facts[key] ?? ''));
     if (!changed.length) {
-      return update(tx, existing, { sourceSeenAt: seenAt, mappingComplete: facts.mappingComplete, lines });
+      return update(tx, existing, { sourceSeenAt: seenAt, mappingComplete: facts.mappingComplete, lines, jobDate: facts.jobDate });
     }
     const fields = { ...facts, sourceSeenAt: seenAt };
     if (existing.invoiceId && changed.some((key) => ['lineFingerprint', 'totalCents', 'contactId'].includes(key))) {

package/server/core/links.js

@@ -8,12 +8,12 @@ import { openReview, resolveReviewFor } from './review.js';
 // Pushes, imports and the ledger read the link first; matching by name only
 // ever proposes one.
 //
-// A link is exact when Flow made the external record, or both sides carry the
-// same id. A name match is a guess: it stays `proposed` and opens a review item
+// A link is exact when Flow made the external record, both sides carry the
+// same id, or one record on each side has the same name. A looser name match is a guess: it stays `proposed` and opens a review item
 // until a person confirms it. A link is never deleted; a replaced one is
 // `superseded`.
 
-const EXACT = new Set(['created_by_flow', 'exact_id', 'imported', 'person']);
+const EXACT = new Set(['created_by_flow', 'exact_id', 'exact_name', 'imported', 'person']);
 
 function check({ entity, flowId, system, externalId, matchedBy }) {
   if (!LINK_ENTITIES.includes(entity)) throw new FlowError('invalid', `unknown link entity: ${entity}`);