@arcforgelabs/flow 2026.10.26 → 2026.10.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcforgelabs/flow",
-  "version": "2026.10.26",
+  "version": "2026.10.27",
   "description": "Invoicing, bill entry and a financial dashboard for labs, with Seazona and Xero integrations.",
   "license": "MIT",
   "repository": {
@@ -47,6 +47,7 @@
     "@fontsource-variable/playfair-display": "5.3.0",
     "@fontsource-variable/plus-jakarta-sans": "5.3.0",
     "@fontsource-variable/space-grotesk": "5.3.0",
+    "@sentry/node": "11.4.0",
     "drizzle-orm": "0.45.3",
     "express": "5.3.0",
     "express-rate-limit": "8.7.0",

package/server/api/invoicing.js

@@ -4,7 +4,16 @@ 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 { listAutomations, saveAutomation, workStatuses } from '../core/automations.js';
+import {
+  ACTIONS, createRule, deleteRule, FIELDS, listRules, TESTS, updateRule,
+} from '../core/invoice-rules.js';
+import {
+  customerBillingByContact, effectiveSettings, INVOICING_DEFAULTS, readCustomerBilling, readInvoicingSettings, ruleBlockers,
+  saveCustomerBilling, saveInvoicingSettings,
+} from '../core/invoicing-rules.js';
+import { draftInvoiceForObligation, listObligations, setReady } from '../core/ledger.js';
+import { invoiceView, invoiceViews, markNotReady, markReady, sendAgain, sendAllReady } from '../core/sending.js';
 import {
   billingObligations, contacts, invoices, INVOICE_STATUSES, organisations, priceItems, TAX_CODES,
 } from '../db/schema.js';
@@ -13,7 +22,13 @@ import {
 // 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?organisationId=&status=&q=&limit=   newest first, with counts by status;
+//                                     status to_check, ready or problem lists those views (server/core/sending.js)
+//   POST  /invoices/mark-ready        { invoiceIds }: a person checked these drafts; one with a problem stays
+//   POST  /invoices/mark-not-ready    { invoiceIds }: back to To check
+//   POST  /invoices/send-ready        owner or admin: issue every ready draft and queue it for the
+//                                     accounting system { issueDate }
+//   POST  /invoices/send-again        owner or admin: queue failed sends again { invoiceIds? }
 //   GET   /invoices/:id               one invoice: lines, contact, job, issued versions
 //   POST  /invoices                   a new draft
 //   PATCH /invoices/:id               change a draft
@@ -22,7 +37,21 @@ import {
 //   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
+//   GET   /jobs?view=&limit=          billable jobs (the obligation ledger), with counts by view;
+//                                     a job with no invoice lists the invoicing rules it waits on
+//   GET   /settings                   the invoicing settings (server/core/invoicing-rules.js)
+//   PUT   /settings                   owner or admin: change some of them
+//   GET   /rules                      the lab's invoice rules, in order (server/core/invoice-rules.js)
+//   GET   /rule-fields                what a rule can name, and the menus of values
+//   POST  /rules                      owner or admin: a new rule { name, enabled, conditions, action }
+//   PUT   /rules/:id                  owner or admin: change some of a rule
+//   DELETE /rules/:id                 owner or admin
+//   GET   /automations?place=         Flow's routines, each on or off (server/core/automations.js)
+//   PUT   /automations/:key           owner or admin: { enabled, config }
+//   GET   /work-statuses              the work system's job statuses, with job counts
+//   GET   /contacts/:id/billing       one customer's own invoicing settings
+//   PUT   /contacts/:id/billing       owner or admin: change them (null takes the organisation's)
+//   POST  /jobs/:id/ready             { ready }: mark a job ready to invoice, or back in work
 //   POST  /jobs/:id/draft             owner or admin: a job's draft invoice, after a live
 //                                     check that the accounting system holds none
 //
@@ -31,10 +60,12 @@ import {
 // 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.
+// `accounting()` is the accounting adapter that sends invoices, or null.
 
 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 VIEWS_OF_INVOICES = ['to_check', 'ready', 'problem'];
+const VIEWS = ['in_work', '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
@@ -45,6 +76,7 @@ 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,
+  accounting_not_connected: 409, accounting_writes_off: 409,
 };
 
 function sendError(res, error, log) {
@@ -176,7 +208,7 @@ async function jobsByInvoice(db, organisationId, invoiceIds) {
   return new Map(rows.map((o) => [o.invoiceId, jobOf(o)]));
 }
 
-async function invoiceDetail(db, organisationId, invoiceId) {
+async function invoiceDetail(db, organisationId, invoiceId, accounting = null) {
   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)
@@ -186,13 +218,14 @@ async function invoiceDetail(db, organisationId, invoiceId) {
   ]);
   return {
     ...invoice,
+    ...(await invoiceView(db, organisationId, invoice, { accounting })),
     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 }) {
+export function createInvoicingRouter({ db, personAuth, log = console, liveCheckFor = () => null, accounting = () => null }) {
   const router = express.Router();
   router.use(express.json({ limit: '64kb' }));
 
@@ -210,11 +243,18 @@ export function createInvoicingRouter({ db, personAuth, log = console, liveCheck
   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(', ')}`);
+    if (status && ![...INVOICE_STATUSES, ...VIEWS_OF_INVOICES].includes(status)) {
+      throw invalid(`status must be one of ${[...INVOICE_STATUSES, ...VIEWS_OF_INVOICES].join(', ')}`);
+    }
     const q = text(req.query.q);
     const limit = limitOf(req.query.limit, 200, 500);
+    const views = await invoiceViews(db, organisationId, { accounting: accounting() });
     const where = [eq(invoices.organisationId, organisationId)];
-    if (status) where.push(eq(invoices.status, status));
+    const only = (ids) => (ids.length ? inArray(invoices.id, ids) : sql`false`);
+    if (status === 'to_check') where.push(only(views.toCheck));
+    else if (status === 'ready') where.push(only(views.ready));
+    else if (status === 'problem') where.push(only([...views.problems.keys()]));
+    else 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)));
@@ -229,17 +269,68 @@ export function createInvoicingRouter({ db, personAuth, log = console, liveCheck
       .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;
+    counts.to_check = views.toCheck.length;
+    counts.ready = views.ready.length;
+    counts.problem = views.problems.size;
+    const ready = new Set(views.ready);
+    const toCheck = new Set(views.toCheck);
     res.json({
       ok: true,
-      invoices: rows.map(({ invoice, contactName }) => ({ ...invoice, contactName, job: jobs.get(invoice.id) ?? null })),
+      invoices: rows.map(({ invoice, contactName }) => ({
+        ...invoice,
+        contactName,
+        job: jobs.get(invoice.id) ?? null,
+        view: views.problems.has(invoice.id) ? 'problem' : ready.has(invoice.id) ? 'ready' : toCheck.has(invoice.id) ? 'to_check'
+          : views.sending.has(invoice.id) ? 'sending' : null,
+        problems: views.problems.get(invoice.id) ?? [],
+      })),
       counts,
+      sendsTo: accounting()?.name ?? null,
     });
   }));
 
+  const invoiceIdsOf = (body) => {
+    const ids = body?.invoiceIds;
+    if (!Array.isArray(ids) || !ids.length || ids.length > 500 || !ids.every((id) => UUID.test(String(id)))) {
+      throw invalid('invoiceIds must list 1 to 500 invoice ids');
+    }
+    return [...new Set(ids)];
+  };
+
+  // Anyone who drafts may say a draft is checked; issuing and sending stay
+  // with an owner or admin.
+  router.post('/invoices/mark-ready', ...signedIn, handle(log, async (req, res) => {
+    const organisationId = await organisationOf(req);
+    const result = await markReady(db, organisationId, invoiceIdsOf(req.body), { personId: req.person.id, accounting: accounting() });
+    log.info?.(`[invoicing] organisation ${organisationId}: person ${req.person.id} marked ${result.marked} invoice(s) ready`);
+    res.json({ ok: true, ...result });
+  }));
+
+  router.post('/invoices/mark-not-ready', ...signedIn, handle(log, async (req, res) => {
+    const organisationId = await organisationOf(req);
+    res.json({ ok: true, ...(await markNotReady(db, organisationId, invoiceIdsOf(req.body))) });
+  }));
+
+  router.post('/invoices/send-ready', ...manager, handle(log, async (req, res) => {
+    const organisationId = await organisationOf(req);
+    const issueDate = optionalDate(req.body?.issueDate, 'issueDate') ?? today();
+    const result = await sendAllReady(db, organisationId, { accounting: accounting(), personId: req.person.id, issueDate });
+    log.info?.(`[invoicing] organisation ${organisationId}: person ${req.person.id} sent all ready: ${JSON.stringify(result)}`);
+    res.json({ ok: true, ...result });
+  }));
+
+  router.post('/invoices/send-again', ...manager, handle(log, async (req, res) => {
+    const organisationId = await organisationOf(req);
+    const ids = req.body?.invoiceIds === undefined ? null : invoiceIdsOf(req.body);
+    const result = await sendAgain(db, organisationId, { accounting: accounting(), personId: req.person.id, invoiceIds: ids });
+    log.info?.(`[invoicing] organisation ${organisationId}: person ${req.person.id} sent again: ${JSON.stringify(result)}`);
+    res.json({ ok: true, ...result });
+  }));
+
   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) });
+    res.json({ ok: true, invoice: await invoiceDetail(db, organisationId, invoiceId, accounting()) });
   }));
 
   router.post('/invoices', ...signedIn, handle(log, async (req, res) => {
@@ -252,7 +343,7 @@ export function createInvoicingRouter({ db, personAuth, log = console, liveCheck
       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) });
+    res.status(201).json({ ok: true, invoice: await invoiceDetail(db, organisationId, draft.id, accounting()) });
   }));
 
   router.patch('/invoices/:id', ...signedIn, handle(log, async (req, res) => {
@@ -266,7 +357,7 @@ export function createInvoicingRouter({ db, personAuth, log = console, liveCheck
     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) });
+    res.json({ ok: true, invoice: await invoiceDetail(db, organisationId, invoiceId, accounting()) });
   }));
 
   router.post('/invoices/:id/issue', ...manager, handle(log, async (req, res) => {
@@ -275,7 +366,7 @@ export function createInvoicingRouter({ db, personAuth, log = console, liveCheck
     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) });
+    res.json({ ok: true, invoice: await invoiceDetail(db, organisationId, invoiceId, accounting()) });
   }));
 
   router.post('/invoices/:id/revise', ...manager, handle(log, async (req, res) => {
@@ -283,7 +374,7 @@ export function createInvoicingRouter({ db, personAuth, log = console, liveCheck
     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) });
+    res.json({ ok: true, invoice: await invoiceDetail(db, organisationId, invoiceId, accounting()) });
   }));
 
   router.post('/invoices/:id/void', ...manager, handle(log, async (req, res) => {
@@ -291,7 +382,7 @@ export function createInvoicingRouter({ db, personAuth, log = console, liveCheck
     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) });
+    res.json({ ok: true, invoice: await invoiceDetail(db, organisationId, invoiceId, accounting()) });
   }));
 
   router.get('/contacts', ...signedIn, handle(log, async (req, res) => {
@@ -320,7 +411,7 @@ export function createInvoicingRouter({ db, personAuth, log = console, liveCheck
     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 all = await listObligations(db, organisationId, { accounting: Boolean(liveCheckFor(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);
@@ -338,6 +429,13 @@ export function createInvoicingRouter({ db, personAuth, log = console, liveCheck
     ]);
     const nameOf = new Map(names.map((c) => [c.id, c.name]));
     const invoiceOf = new Map(numbers.map((i) => [i.id, i]));
+    const settings = await readInvoicingSettings(db, organisationId);
+    const customers = await customerBillingByContact(db, organisationId, contactIds);
+    const rules = await listRules(db, organisationId);
+    // The invoicing rules a job with no invoice waits on, for every view a
+    // draft can still come from.
+    const waitingFor = (o, v) => (o.invoiceId || !['in_work', 'ready', 'pending', 'held'].includes(v)
+      ? [] : ruleBlockers(o, effectiveSettings(settings, customers.get(o.contactId)), { rules }));
     res.json({
       ok: true,
       jobs: listed.map(({ obligation: { lineFingerprint: _fingerprint, organisationId: _org, ...o }, view: v, reasons }) => ({
@@ -347,6 +445,7 @@ export function createInvoicingRouter({ db, personAuth, log = console, liveCheck
         invoiceStatus: invoiceOf.get(o.invoiceId)?.status ?? null,
         view: v,
         reasons,
+        waitingFor: waitingFor(o, v),
       })),
       counts,
     });
@@ -355,15 +454,127 @@ export function createInvoicingRouter({ db, personAuth, log = console, liveCheck
   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.');
-    }
+    // With no accounting system connected, Flow's own records are the check.
+    const liveCheck = liveCheckFor(organisationId) ?? null;
     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) });
   }));
 
+  router.post('/jobs/:id/ready', ...signedIn, handle(log, async (req, res) => {
+    const obligationId = pathId(req.params.id, 'job');
+    const organisationId = await organisationOf(req);
+    const ready = req.body?.ready ?? true;
+    if (typeof ready !== 'boolean') throw invalid('ready must be true or false');
+    const job = await setReady(db, organisationId, obligationId, { ready, actor: `person:${req.person.id}` });
+    res.json({ ok: true, job: { id: job.id, readyAt: job.readyAt, readyBy: job.readyBy } });
+  }));
+
+  router.get('/automations', ...signedIn, handle(log, async (req, res) => {
+    const organisationId = await organisationOf(req);
+    const place = typeof req.query.place === 'string' ? req.query.place : null;
+    const list = await listAutomations(db, organisationId);
+    res.json({ ok: true, automations: place ? list.filter((a) => a.place === place) : list });
+  }));
+
+  router.get('/work-statuses', ...signedIn, handle(log, async (req, res) => {
+    const organisationId = await organisationOf(req);
+    res.json({ ok: true, statuses: await workStatuses(db, organisationId) });
+  }));
+
+  router.put('/automations/:key', ...manager, handle(log, async (req, res) => {
+    const organisationId = await organisationOf(req);
+    const { organisationId: _named, ...changes } = req.body ?? {};
+    const automation = await saveAutomation(db, organisationId, String(req.params.key), changes, { personId: req.person.id });
+    log.info?.(`[invoicing] organisation ${organisationId}: person ${req.person.id} changed automation ${automation.key}`);
+    res.json({ ok: true, automation });
+  }));
+
+  // The lab's invoice rules (docs/INVOICE_RULES.md).
+  router.get('/rules', ...signedIn, handle(log, async (req, res) => {
+    const organisationId = await organisationOf(req);
+    res.json({ ok: true, rules: await listRules(db, organisationId) });
+  }));
+
+  // What a rule can name, so people pick every value from a menu: the fields
+  // with their tests, and the values Flow already holds for each kind of menu.
+  router.get('/rule-fields', ...signedIn, handle(log, async (req, res) => {
+    const organisationId = await organisationOf(req);
+    const [statuses, customers, items] = await Promise.all([
+      workStatuses(db, organisationId),
+      db.select({ value: contacts.id, label: contacts.name }).from(contacts)
+        .where(and(eq(contacts.organisationId, organisationId), eq(contacts.kind, 'customer')))
+        .orderBy(asc(contacts.name)).limit(1000),
+      db.select({ value: priceItems.code, label: priceItems.name }).from(priceItems)
+        .where(and(eq(priceItems.organisationId, organisationId), isNull(priceItems.archivedAt)))
+        .orderBy(asc(priceItems.code)).limit(1000),
+    ]);
+    res.json({
+      ok: true,
+      fields: Object.entries(FIELDS).map(([key, f]) => ({ key, label: f.label, kind: f.kind, options: f.options ?? null, tests: TESTS[f.kind] })),
+      actions: ACTIONS,
+      options: {
+        statuses: statuses.map((s) => ({ value: s.value, label: s.label })),
+        customers,
+        items: items.map((i) => ({ value: i.value, label: `${i.value} · ${i.label}` })),
+      },
+    });
+  }));
+
+  router.post('/rules', ...manager, handle(log, async (req, res) => {
+    const organisationId = await organisationOf(req);
+    const { organisationId: _named, ...raw } = req.body ?? {};
+    const rule = await createRule(db, organisationId, raw, { personId: req.person.id });
+    log.info?.(`[invoicing] organisation ${organisationId}: person ${req.person.id} added invoice rule ${rule.id}`);
+    res.status(201).json({ ok: true, rule });
+  }));
+
+  router.put('/rules/:id', ...manager, handle(log, async (req, res) => {
+    const ruleId = pathId(req.params.id, 'rule');
+    const organisationId = await organisationOf(req);
+    const { organisationId: _named, ...changes } = req.body ?? {};
+    const rule = await updateRule(db, organisationId, ruleId, changes, { personId: req.person.id });
+    log.info?.(`[invoicing] organisation ${organisationId}: person ${req.person.id} changed invoice rule ${rule.id}`);
+    res.json({ ok: true, rule });
+  }));
+
+  router.delete('/rules/:id', ...manager, handle(log, async (req, res) => {
+    const ruleId = pathId(req.params.id, 'rule');
+    const organisationId = await organisationOf(req);
+    await deleteRule(db, organisationId, ruleId);
+    log.info?.(`[invoicing] organisation ${organisationId}: person ${req.person.id} deleted invoice rule ${ruleId}`);
+    res.json({ ok: true });
+  }));
+
+  router.get('/settings', ...signedIn, handle(log, async (req, res) => {
+    const organisationId = await organisationOf(req);
+    res.json({ ok: true, settings: await readInvoicingSettings(db, organisationId), defaults: INVOICING_DEFAULTS });
+  }));
+
+  router.put('/settings', ...manager, handle(log, async (req, res) => {
+    const organisationId = await organisationOf(req);
+    const { organisationId: _named, ...changes } = req.body ?? {};
+    const settings = await saveInvoicingSettings(db, organisationId, changes, { personId: req.person.id });
+    log.info?.(`[invoicing] organisation ${organisationId}: person ${req.person.id} changed invoicing settings ${Object.keys(changes).join(', ')}`);
+    res.json({ ok: true, settings, defaults: INVOICING_DEFAULTS });
+  }));
+
+  router.get('/contacts/:id/billing', ...signedIn, handle(log, async (req, res) => {
+    const contactId = pathId(req.params.id, 'customer');
+    const organisationId = await organisationOf(req);
+    const [billing, settings] = await Promise.all([readCustomerBilling(db, organisationId, contactId), readInvoicingSettings(db, organisationId)]);
+    res.json({ ok: true, billing, effective: effectiveSettings(settings, billing) });
+  }));
+
+  router.put('/contacts/:id/billing', ...manager, handle(log, async (req, res) => {
+    const contactId = pathId(req.params.id, 'customer');
+    const organisationId = await organisationOf(req);
+    const { organisationId: _named, ...changes } = req.body ?? {};
+    const billing = await saveCustomerBilling(db, organisationId, contactId, changes, { personId: req.person.id });
+    log.info?.(`[invoicing] organisation ${organisationId}: person ${req.person.id} changed billing settings of customer ${contactId}`);
+    res.json({ ok: true, billing, effective: effectiveSettings(await readInvoicingSettings(db, organisationId), billing) });
+  }));
+
   // 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.' });

package/server/app.js

@@ -25,7 +25,9 @@ import { createUiAssetsRouter } from './ui/routes.js';
 // `integrations` is the started registry (server/integrations/index.js); each
 // adapter's own routes are mounted under /api/<id>, and GET /health reports
 // each one (server/integrations/health.js). `defaultFamily` is the design
-// system every page starts on (FLOW_THEME, server/theme/themes.js).
+// system every page starts on (FLOW_THEME, server/theme/themes.js). `log`
+// is the console, or the monitored log (server/core/monitoring.js) that also
+// sends each error to the installation's error service.
 export function createApp({
   build = deployedBuildStatus(),
   database = null,
@@ -109,7 +111,21 @@ export function createApp({
       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 }));
+    // Send all ready (server/core/sending.js): the first enabled integration
+    // that sends invoices (Xero).
+    const accounting = () => integrations?.with('pushInvoices')[0] ?? null;
+    app.use('/api/invoicing', createInvoicingRouter({ db: database.db, personAuth: auth.personAuth, log, liveCheckFor, accounting }));
+  }
+  // What a signed-in browser needs to report its errors and problems to the
+  // installation's own error service (docs/SENTRY.md): the first integration
+  // that offers `browserMonitoring`, or `{ on: false }`.
+  if (auth?.personAuth) {
+    app.get('/api/monitoring', auth.personAuth.requireSession, (_req, res) => {
+      res.set('Cache-Control', 'no-store');
+      const [adapter] = integrations?.with('browserMonitoring') ?? [];
+      const settings = adapter?.capabilities.browserMonitoring() ?? null;
+      res.json(settings ? { ok: true, on: true, service: adapter.id, ...settings } : { ok: true, on: false });
+    });
   }
   for (const { path, handler } of integrations?.routes({ db: database?.db ?? null, personAuth: auth?.personAuth ?? null, log, messagePage: page }) ?? []) {
     app.use(path, handler);
@@ -125,5 +141,15 @@ export function createApp({
     log,
   }));
 
+  // An error no route answered. A server fault goes to `log` (and from there
+  // to the error service, when one is on) and the answer carries no detail;
+  // any other error keeps Express's own answer.
+  app.use((error, _req, res, next) => {
+    const status = error?.status ?? error?.statusCode ?? 500;
+    if (status < 500 || res.headersSent) return next(error);
+    log.error?.(`[http] ${error?.message ?? error}`, ...(error instanceof Error ? [error] : []));
+    return res.status(500).json({ ok: false, code: 'internal', error: 'Something went wrong.' });
+  });
+
   return app;
 }

package/server/core/automations.js

@@ -0,0 +1,140 @@
+import { and, eq, sql } from 'drizzle-orm';
+import { automations, billingObligations } from '../db/schema.js';
+import { FlowError, notFound } from './errors.js';
+import { autoDraftJobs } from './invoicing-rules.js';
+import { setReady } from './ledger.js';
+
+// Automations (docs/AUTOMATIONS.md): Flow's routines. Each one watches Flow's
+// own records and moves them on, and each is on or off with its own settings,
+// so no other system's status is baked into Flow's stages. `place` is the
+// screen that shows it: the integration whose data triggers it, or invoicing. The routines are
+// defined here; the `automations` table holds an organisation's choices. The
+// pipeline (pipeline.js) runs them after it reads the integrations' copies.
+//
+//   mark_ready_from_work_status: a job whose work system status is one of the
+//     chosen statuses becomes ready to invoice (Flow's stage). The statuses
+//     are picked from those the work system reported (workStatuses).
+//   draft_when_ready: a job that is ready to invoice and passes the invoicing
+//     rules (invoicing-rules.js) gets a draft invoice in Flow.
+
+const BATCH = 500;
+
+const norm = (value) => String(value ?? '').trim().replace(/\s+/g, ' ').toLowerCase();
+
+// A status matches when it is one of the chosen statuses, in any case.
+export function statusMatches(status, statuses) {
+  const have = norm(status);
+  return Boolean(have) && statuses.some((wanted) => norm(wanted) === have);
+}
+
+// The statuses the work system has reported for this organisation's jobs, with
+// the number of jobs at each, most jobs first. People pick the ready statuses
+// from this list, so it follows each lab's own work system.
+export async function workStatuses(db, organisationId) {
+  const rows = await db.select({ status: billingObligations.sourceStatus, jobs: sql`count(*)::int` })
+    .from(billingObligations)
+    .where(and(eq(billingObligations.organisationId, organisationId), sql`${billingObligations.sourceStatus} is not null`))
+    .groupBy(billingObligations.sourceStatus);
+  const byName = new Map();
+  for (const { status, jobs } of rows) {
+    const key = norm(status);
+    if (!key) continue;
+    const seen = byName.get(key);
+    if (seen) seen.jobs += jobs;
+    else byName.set(key, { value: key, label: status.trim(), jobs });
+  }
+  return [...byName.values()].sort((a, b) => b.jobs - a.jobs || a.label.localeCompare(b.label));
+}
+
+function readStatuses(value) {
+  if (!Array.isArray(value) || !value.length || value.length > 20) throw new FlowError('invalid', 'statuses must list 1 to 20 statuses');
+  const statuses = [...new Set(value.map((s) => (typeof s === 'string' ? norm(s) : '')).filter(Boolean))];
+  if (!statuses.length || statuses.some((s) => s.length > 100)) throw new FlowError('invalid', 'statuses must be short text');
+  return statuses;
+}
+
+export const AUTOMATIONS = Object.freeze([
+  {
+    key: 'mark_ready_from_work_status',
+    place: 'seazona',
+    name: 'Mark ready to invoice',
+    hint: 'When the job has one of the ready statuses.',
+    defaults: { enabled: true, config: { statuses: ['shipped', 'delivered'] } },
+    readConfig: (config) => ({ statuses: readStatuses(config.statuses) }),
+  },
+  {
+    key: 'draft_when_ready',
+    place: 'invoicing',
+    name: 'Draft when ready',
+    hint: 'Drafts each ready job that passes the checks.',
+    defaults: { enabled: true, config: {} },
+    readConfig: () => ({}),
+  },
+]);
+
+const byKey = new Map(AUTOMATIONS.map((a) => [a.key, a]));
+
+// Every routine with this organisation's choice, or its default.
+export async function listAutomations(db, organisationId) {
+  const rows = await db.select().from(automations).where(eq(automations.organisationId, organisationId));
+  const saved = new Map(rows.map((r) => [r.key, r]));
+  return AUTOMATIONS.map(({ key, place, name, hint, defaults }) => {
+    const row = saved.get(key);
+    return { key, place, name, hint, enabled: row?.enabled ?? defaults.enabled, config: { ...defaults.config, ...(row?.config ?? {}) } };
+  });
+}
+
+export async function saveAutomation(db, organisationId, key, changes, { personId = null } = {}) {
+  const automation = byKey.get(key);
+  if (!automation) throw notFound('automation');
+  if (!changes || typeof changes !== 'object' || Array.isArray(changes)) throw new FlowError('invalid', 'the change must be an object');
+  const unknown = Object.keys(changes).filter((k) => !['enabled', 'config'].includes(k));
+  if (unknown.length) throw new FlowError('invalid', `unknown field: ${unknown[0]}`);
+  const current = (await listAutomations(db, organisationId)).find((a) => a.key === key);
+  const enabled = changes.enabled ?? current.enabled;
+  if (typeof enabled !== 'boolean') throw new FlowError('invalid', 'enabled must be true or false');
+  const config = 'config' in changes ? automation.readConfig({ ...current.config, ...changes.config }) : current.config;
+  await db.insert(automations)
+    .values({ organisationId, key, enabled, config, updatedBy: personId })
+    .onConflictDoUpdate({ target: [automations.organisationId, automations.key], set: { enabled, config, updatedBy: personId, updatedAt: sql`now()` } });
+  return (await listAutomations(db, organisationId)).find((a) => a.key === key);
+}
+
+const actorOf = (key) => `automation:${key}`;
+
+// Marks ready each job in work whose work system status is one of the chosen
+// ones. A person who put a job back in work has decided: the routine leaves
+// that job to people from then on.
+async function markReadyFromWorkStatus(db, organisationId, { statuses }) {
+  const actor = actorOf('mark_ready_from_work_status');
+  const jobs = await db.select().from(billingObligations).where(and(
+    eq(billingObligations.organisationId, organisationId),
+    sql`${billingObligations.readyAt} is null`,
+    sql`${billingObligations.invoiceId} is null`,
+    sql`${billingObligations.sourceStatus} is not null`,
+    sql`not exists (select 1 from obligation_events e where e.obligation_id = ${billingObligations.id}
+      and e.kind = 'in_work' and e.actor not like 'automation:%')`,
+  )).limit(BATCH);
+  let marked = 0;
+  for (const job of jobs) {
+    if (!statusMatches(job.sourceStatus, statuses)) continue;
+    await setReady(db, organisationId, job.id, { ready: true, actor });
+    marked += 1;
+  }
+  return { marked };
+}
+
+// Runs every routine that is on. `accounting` is the integration whose copy
+// the draft routine checks; without one, Flow's own records are the check.
+export async function runAutomations(db, organisationId, { accounting = null, now = new Date() } = {}) {
+  const summary = {};
+  for (const automation of await listAutomations(db, organisationId)) {
+    if (!automation.enabled) continue;
+    if (automation.key === 'mark_ready_from_work_status') {
+      summary[automation.key] = await markReadyFromWorkStatus(db, organisationId, automation.config);
+    } else if (automation.key === 'draft_when_ready') {
+      summary[automation.key] = await autoDraftJobs(db, organisationId, { accounting, now, actor: actorOf(automation.key) });
+    }
+  }
+  return summary;
+}