@arcforgelabs/flow 2026.10.26 → 2026.10.29

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcforgelabs/flow",
-  "version": "2026.10.26",
+  "version": "2026.10.29",
   "description": "Invoicing, bill entry and a financial dashboard for labs, with Seazona and Xero integrations.",
   "license": "MIT",
   "repository": {
@@ -32,7 +32,7 @@
     "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"
+    "db:generate": "drizzle-kit generate && node scripts/db-guard-migrations.js"
   },
   "dependencies": {
     "@clerk/backend": "3.23.2",
@@ -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,20 @@ 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 {
+  createMapping, deleteMapping, listMappings, STEP_LABELS, STEPS, updateMapping,
+} from '../core/line-mapping.js';
+import {
+  effectiveSettings, INVOICING_DEFAULTS, readCustomerBilling, readInvoicingSettings,
+  saveCustomerBilling, saveInvoicingSettings,
+} from '../core/invoicing-rules.js';
+import { boardJobs, describeObligations } from '../core/job-board.js';
+import { draftInvoiceForObligation, explainObligation, 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 +26,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 +41,30 @@ 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;
+//                                     a job with an invoice has its Invoices page view and problems
+//   GET   /board                      the Jobs board: the work system's jobs by its own statuses,
+//                                     each with its billing obligation (server/core/job-board.js)
+//   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   /line-mappings              the lab's line mappings and the mapping steps (server/core/line-mapping.js)
+//   GET   /line-labels                the line labels on jobs, with counts and how each mapped
+//   POST  /line-mappings              owner or admin: a new mapping
+//   PUT   /line-mappings/:id          owner or admin: change some of a mapping
+//   DELETE /line-mappings/: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
+//   GET   /jobs/:id/activity          what happened to a job, newest first
 //   POST  /jobs/:id/draft             owner or admin: a job's draft invoice, after a live
 //                                     check that the accounting system holds none
 //
@@ -31,10 +73,13 @@ 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.
+// `work()` is the work system adapters that offer listWork (the Jobs board).
 
 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
@@ -44,7 +89,8 @@ 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,
+  never_issued: 409, not_ready: 409, live_check_unavailable: 409, conflict: 409,
+  accounting_not_connected: 409, accounting_writes_off: 409,
 };
 
 function sendError(res, error, log) {
@@ -176,7 +222,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 +232,16 @@ 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, work = () => [],
+}) {
   const router = express.Router();
   router.use(express.json({ limit: '64kb' }));
 
@@ -210,11 +259,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 +285,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 +359,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 +373,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 +382,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 +390,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 +398,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,50 +427,210 @@ 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);
-    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,
+    res.json({ ok: true, jobs: await describeObligations(db, organisationId, listed, { accounting: accounting() }), counts });
+  }));
+
+  // The Jobs board: the work system's jobs, by its own statuses, each with
+  // its billing obligation when it has one (server/core/job-board.js).
+  router.get('/board', ...signedIn, handle(log, async (req, res) => {
+    const organisationId = await organisationOf(req);
+    const { jobs, statuses } = await boardJobs(db, organisationId, {
+      work: work(), accounting: accounting(), live: Boolean(liveCheckFor(organisationId)), log,
     });
+    res.json({ ok: true, jobs, statuses, accountingName: accounting()?.name ?? null });
   }));
 
   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 } });
+  }));
+
+  // A job's activity for its detail panel: what happened to it, newest
+  // first, without the evidence each event keeps.
+  router.get('/jobs/:id/activity', ...signedIn, handle(log, async (req, res) => {
+    const obligationId = pathId(req.params.id, 'job');
+    const organisationId = await organisationOf(req);
+    const { events } = await explainObligation(db, organisationId, obligationId);
+    res.json({
+      ok: true,
+      events: events.slice(-50).reverse().map(({ kind, actor, createdAt }) => ({
+        kind, by: actor.startsWith('person:') ? 'person' : actor.startsWith('automation:') ? 'automation' : actor.replace(/^system:/, ''), createdAt,
+      })),
+    });
+  }));
+
+  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}` })),
+          ...(await listMappings(db, organisationId)).filter((m) => m.kind === 'account')
+            .map((m) => ({ value: m.label, label: `${m.label} · ${m.description ?? `account ${m.accountCode}`}` })),
+        ],
+      },
+    });
+  }));
+
+  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('/line-mappings', ...signedIn, handle(log, async (req, res) => {
+    const organisationId = await organisationOf(req);
+    res.json({ ok: true, mappings: await listMappings(db, organisationId), steps: STEPS.map((key) => ({ key, label: STEP_LABELS[key] })) });
+  }));
+
+  // Each label the line mapping saw on jobs, how many lines carry it, a
+  // sample of the work system's text and price, and whether it mapped.
+  router.get('/line-labels', ...signedIn, handle(log, async (req, res) => {
+    const organisationId = await organisationOf(req);
+    const rows = (await db.execute(sql`
+      select l->>'label' as label, count(*)::int as lines,
+        count(*) filter (where l->>'priceItemId' is null and l->>'accountCode' is null)::int as unmapped,
+        min(l->>'description') as sample, min((l->>'unitAmountCents')::int) as "unitAmountCents",
+        min(l->>'mappedBy') as "mappedBy", min(l->>'itemCode') as "itemCode"
+      from billing_obligations o, jsonb_array_elements(o.lines) l
+      where o.organisation_id = ${organisationId} and l->>'label' is not null
+      group by 1 order by 3 desc, 2 desc, 1 limit 1000`)).rows ?? [];
+    res.json({ ok: true, labels: rows });
+  }));
+
+  router.post('/line-mappings', ...manager, handle(log, async (req, res) => {
+    const organisationId = await organisationOf(req);
+    const { organisationId: _named, ...raw } = req.body ?? {};
+    const mapping = await createMapping(db, organisationId, raw, { personId: req.person.id });
+    log.info?.(`[invoicing] organisation ${organisationId}: person ${req.person.id} added line mapping ${mapping.id}`);
+    res.status(201).json({ ok: true, mapping });
+  }));
+
+  router.put('/line-mappings/:id', ...manager, handle(log, async (req, res) => {
+    const mappingId = pathId(req.params.id, 'mapping');
+    const organisationId = await organisationOf(req);
+    const { organisationId: _named, ...changes } = req.body ?? {};
+    const mapping = await updateMapping(db, organisationId, mappingId, changes, { personId: req.person.id });
+    log.info?.(`[invoicing] organisation ${organisationId}: person ${req.person.id} changed line mapping ${mapping.id}`);
+    res.json({ ok: true, mapping });
+  }));
+
+  router.delete('/line-mappings/:id', ...manager, handle(log, async (req, res) => {
+    const mappingId = pathId(req.params.id, 'mapping');
+    const organisationId = await organisationOf(req);
+    await deleteMapping(db, organisationId, mappingId);
+    log.info?.(`[invoicing] organisation ${organisationId}: person ${req.person.id} deleted line mapping ${mappingId}`);
+    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,23 @@ 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;
+    // The Jobs board: every enabled integration that lists its jobs (Seazona).
+    const work = () => integrations?.with('listWork') ?? [];
+    app.use('/api/invoicing', createInvoicingRouter({ db: database.db, personAuth: auth.personAuth, log, liveCheckFor, accounting, work }));
+  }
+  // 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 +143,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;
 }