@arcforgelabs/flow 2026.10.27 → 2026.10.29

package/README.md

@@ -38,6 +38,7 @@ run a lab.
 | `docs/INVOICE_RULES.md` | Invoice rules a lab builds (When, If, Then) that make a ready job wait or never draft |
 | `docs/INVOICE_SENDING.md` | Drafts, Problem and Ready invoices, Mark ready, and Send all ready to the accounting system |
 | `docs/AUTOMATIONS.md` | Automations: Flow routines that mark jobs ready to invoice and draft them, each on or off |
+| `docs/LINE_MAPPING.md` | Line mapping: how each work system line finds its price item, and Price codes in Settings |
 | `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.27",
+  "version": "2026.10.29",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@arcforgelabs/flow",
-      "version": "2026.10.27",
+      "version": "2026.10.29",
       "license": "MIT",
       "dependencies": {
         "@clerk/backend": "3.23.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcforgelabs/flow",
-  "version": "2026.10.27",
+  "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",

package/server/api/invoicing.js

@@ -9,10 +9,14 @@ import {
   ACTIONS, createRule, deleteRule, FIELDS, listRules, TESTS, updateRule,
 } from '../core/invoice-rules.js';
 import {
-  customerBillingByContact, effectiveSettings, INVOICING_DEFAULTS, readCustomerBilling, readInvoicingSettings, ruleBlockers,
+  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 { draftInvoiceForObligation, listObligations, setReady } from '../core/ledger.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,
@@ -38,20 +42,29 @@ import {
 //   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;
-//                                     a job with no invoice lists the invoicing rules it waits on
-//   GET   /settings                   the invoicing settings (server/core/invoicing-rules.js)
+//                                     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
 //
@@ -61,6 +74,7 @@ import {
 // 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}$/;
@@ -75,7 +89,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,
+  never_issued: 409, not_ready: 409, live_check_unavailable: 409, conflict: 409,
   accounting_not_connected: 409, accounting_writes_off: 409,
 };
 
@@ -225,7 +239,9 @@ async function invoiceDetail(db, organisationId, invoiceId, accounting = null) {
   };
 }
 
-export function createInvoicingRouter({ db, personAuth, log = console, liveCheckFor = () => null, accounting = () => null }) {
+export function createInvoicingRouter({
+  db, personAuth, log = console, liveCheckFor = () => null, accounting = () => null, work = () => [],
+}) {
   const router = express.Router();
   router.use(express.json({ limit: '64kb' }));
 
@@ -415,40 +431,17 @@ export function createInvoicingRouter({ db, personAuth, log = console, liveCheck
     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]));
-    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 }) => ({
-        ...o,
-        contactName: nameOf.get(o.contactId) ?? null,
-        invoiceNumber: invoiceOf.get(o.invoiceId)?.number ?? null,
-        invoiceStatus: invoiceOf.get(o.invoiceId)?.status ?? null,
-        view: v,
-        reasons,
-        waitingFor: waitingFor(o, v),
-      })),
-      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) => {
@@ -470,6 +463,20 @@ export function createInvoicingRouter({ db, personAuth, log = console, liveCheck
     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;
@@ -516,7 +523,11 @@ export function createInvoicingRouter({ db, personAuth, log = console, liveCheck
       options: {
         statuses: statuses.map((s) => ({ value: s.value, label: s.label })),
         customers,
-        items: items.map((i) => ({ value: i.value, label: `${i.value} · ${i.label}` })),
+        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}`}` })),
+        ],
       },
     });
   }));
@@ -546,6 +557,51 @@ export function createInvoicingRouter({ db, personAuth, log = console, liveCheck
     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 });

package/server/app.js

@@ -114,7 +114,9 @@ export function createApp({
     // 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 }));
+    // 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

package/server/core/automations.js

@@ -2,6 +2,7 @@ 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 { MAPPING_DEFAULTS, readMappingConfig, remapJobs } from './line-mapping.js';
 import { setReady } from './ledger.js';
 
 // Automations (docs/AUTOMATIONS.md): Flow's routines. Each one watches Flow's
@@ -54,6 +55,17 @@ function readStatuses(value) {
 }
 
 export const AUTOMATIONS = Object.freeze([
+  {
+    // Runs inside the pipeline's read of the work system (pipeline.js,
+    // ingestWork), so every job reaches the ledger already mapped.
+    key: 'map_lines',
+    place: 'seazona',
+    name: 'Map lines to price items',
+    hint: 'Each Seazona line finds its price item.',
+    defaults: { enabled: true, config: { ...MAPPING_DEFAULTS } },
+    readConfig: (config) => readMappingConfig(config),
+    remap: true,
+  },
   {
     key: 'mark_ready_from_work_status',
     place: 'seazona',
@@ -97,6 +109,8 @@ export async function saveAutomation(db, organisationId, key, changes, { personI
   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()` } });
+  // A routine that shapes jobs as they come in applies to the jobs already read.
+  if (automation.remap) await remapJobs(db, organisationId);
   return (await listAutomations(db, organisationId)).find((a) => a.key === key);
 }
 

package/server/core/invoice-rules.js

@@ -21,7 +21,9 @@ const invalid = (message) => new FlowError('invalid', message);
 
 const day = (date) => new Date(`${String(date).slice(0, 10)}T00:00:00Z`);
 const norm = (value) => String(value ?? '').trim().replace(/\s+/g, ' ').toLowerCase();
-const code = (line) => norm(line.itemCode);
+// A line's key: its price item code, else the label line mapping gave it (a
+// line booked to an account, such as a surcharge, has no code).
+const code = (line) => norm(line.itemCode || line.label);
 const cents = (lines) => lines.reduce((sum, l) => sum + (l.lineAmountCents ?? 0), 0);
 
 // The share of the item's lines in the job's other lines, as the charged and
@@ -41,7 +43,7 @@ export const FIELDS = Object.freeze({
   practitioner: { label: 'Practitioner', kind: 'text', read: (j, { customer }) => j.practitioner || customer.defaultPractitioner || null },
   customer: { label: 'Customer', kind: 'choice', options: 'customers', read: (j) => j.contactId },
   customer_billable: { label: 'Customer is billable', kind: 'boolean', read: (j, { customer }) => customer.billable !== false },
-  line_item: { label: 'Line item', kind: 'items', options: 'items', read: (j) => (j.lines ?? []).map(code) },
+  line_item: { label: 'Line item', kind: 'items', options: 'items', read: (j) => (j.lines ?? []).flatMap((l) => [norm(l.itemCode), norm(l.label)].filter(Boolean)) },
   line_share: { label: 'Line share of other lines (%)', kind: 'share', options: 'items', read: (j) => j.lines ?? [] },
 });
 

package/server/core/invoices.js

@@ -39,9 +39,11 @@ async function resolveLines(tx, organisationId, lines) {
     } catch (error) {
       throw new FlowError('invalid', `line ${index + 1}: ${error.message}`);
     }
+    const accountCode = line.priceItemId ? null : (typeof line.accountCode === 'string' && line.accountCode.trim() ? line.accountCode.trim().slice(0, 20) : null);
     resolved.push({
       position: index + 1,
       priceItemId: line.priceItemId ?? null,
+      accountCode,
       description: description.trim(),
       quantity,
       unitAmountCents,
@@ -141,8 +143,8 @@ export async function issueInvoice(db, organisationId, invoiceId, { issuedBy, is
       reference: invoice.reference,
       currency: invoice.currency,
       contact: { id: contact.id, name: contact.name, email: contact.email },
-      lines: lines.map(({ line: { position, description, quantity, unitAmountCents, taxCode, lineAmountCents, taxCents }, itemCode }) => (
-        { position, itemCode: itemCode ?? null, description, quantity, unitAmountCents, taxCode, lineAmountCents, taxCents }
+      lines: lines.map(({ line: { position, description, quantity, unitAmountCents, taxCode, lineAmountCents, taxCents, accountCode }, itemCode }) => (
+        { position, itemCode: itemCode ?? null, ...(accountCode ? { accountCode } : {}), description, quantity, unitAmountCents, taxCode, lineAmountCents, taxCents }
       )),
       subtotalCents: invoice.subtotalCents,
       taxCents: invoice.taxCents,

package/server/core/job-board.js

@@ -0,0 +1,130 @@
+import { and, eq, inArray, isNull } from 'drizzle-orm';
+import { contacts, invoices, priceItems } from '../db/schema.js';
+import { listRules } from './invoice-rules.js';
+import { customerBillingByContact, effectiveSettings, readInvoicingSettings, ruleBlockers } from './invoicing-rules.js';
+import { listObligations } from './ledger.js';
+import { invoiceViews } from './sending.js';
+
+// The Jobs board (/jobs, server/ui/jobs.js). Its columns are the work
+// system's own job statuses, one to one. Its jobs come from the work
+// system's copy in Flow (the port's listWork: Seazona's open orders and the
+// ones finished lately), so jobs still in the lab show. A job that has a
+// billing obligation (ledger.js) carries it, with the state of its invoice,
+// for the job's detail panel. With no work system that offers listWork, the
+// board shows the ledger's jobs by the status the work system last reported.
+
+// The ledger's jobs with what the Jobs page shows: the customer's name, the
+// invoice's number, status, Invoices page view (sending.js) and problems,
+// and the invoicing rules a job with no invoice waits on. `listed` is
+// listObligations output. `accounting` is the accounting adapter, or null.
+export async function describeObligations(db, organisationId, listed, { accounting = null } = {}) {
+  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, views] = 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)))
+      : [],
+    invoiceIds.length ? invoiceViews(db, organisationId, { accounting }) : null,
+  ]);
+  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);
+  const ready = new Set(views?.ready ?? []);
+  const toCheck = new Set(views?.toCheck ?? []);
+  const invoiceView = (id) => (!id || !views ? null
+    : views.problems.has(id) ? 'problem' : ready.has(id) ? 'ready' : toCheck.has(id) ? 'to_check'
+      : views.sending.has(id) ? 'sending' : null);
+  // 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 }));
+  return listed.map(({ obligation: { lineFingerprint: _fingerprint, organisationId: _org, ...o }, view, reasons }) => ({
+    ...o,
+    contactName: nameOf.get(o.contactId) ?? null,
+    invoiceNumber: invoiceOf.get(o.invoiceId)?.number ?? null,
+    invoiceStatus: invoiceOf.get(o.invoiceId)?.status ?? null,
+    invoiceView: invoiceView(o.invoiceId),
+    invoiceProblems: (o.invoiceId && views?.problems.get(o.invoiceId)) || [],
+    view,
+    reasons,
+    waitingFor: waitingFor(o, view),
+  }));
+}
+
+const keyOf = (system, ref) => `${system}\u0000${ref}`;
+
+// The ledger's lines as the board shows them: whether each maps to a price item.
+const ledgerLines = (lines) => (lines ?? []).map((l) => ({
+  code: l.itemCode ?? null, description: l.description, amountCents: l.lineAmountCents ?? null, mapped: Boolean(l.priceItemId),
+}));
+
+// Answers { jobs, statuses }. `work` is the adapters that offer listWork;
+// `live` says an accounting system checks the ledger (ledgerView).
+export async function boardJobs(db, organisationId, { work = [], accounting = null, live = false, log = console } = {}) {
+  const listed = await listObligations(db, organisationId, { accounting: live });
+  const obligations = await describeObligations(db, organisationId, listed, { accounting });
+  const byJob = new Map(obligations.map((o) => [keyOf(o.sourceSystem, o.sourceJobRef), o]));
+
+  const reports = [];
+  for (const adapter of work) {
+    try {
+      reports.push(await adapter.capabilities.listWork({ organisationId }));
+    } catch (error) {
+      // The board still shows the ledger's jobs when the copy cannot be read.
+      log.error?.(`[jobs] ${adapter.id} listWork: ${error.message}`);
+    }
+  }
+  if (!reports.length) {
+    const statuses = new Map();
+    const jobs = obligations.map((o) => {
+      const status = o.sourceStatus?.trim() || null;
+      if (status && !statuses.has(status)) statuses.set(status, { label: status, final: false, firstSeenAt: null });
+      return {
+        sourceSystem: o.sourceSystem, sourceJobRef: o.sourceJobRef, caseRef: o.caseRef, status,
+        clientName: o.contactName, workClientName: null, practitioner: o.practitioner, department: null,
+        orderedOn: null, dueOn: null, jobDate: o.jobDate, shippedOn: o.shippedOn,
+        totalCents: o.totalCents, lines: ledgerLines(o.lines), obligation: o,
+      };
+    });
+    return { jobs, statuses: [...statuses.values()] };
+  }
+
+  const codes = new Set((await db.select({ code: priceItems.code }).from(priceItems)
+    .where(and(eq(priceItems.organisationId, organisationId), isNull(priceItems.archivedAt)))).map((p) => p.code));
+  const jobs = [];
+  const statuses = [];
+  for (const report of reports) {
+    statuses.push(...(report.statuses ?? []));
+    for (const item of report.items ?? []) {
+      const o = byJob.get(keyOf(item.sourceSystem, item.sourceJobRef)) ?? null;
+      jobs.push({
+        sourceSystem: item.sourceSystem,
+        sourceJobRef: item.sourceJobRef,
+        caseRef: item.caseRef ?? o?.caseRef ?? null,
+        status: item.status ?? null,
+        // The Flow customer once the work system's client is linked to one;
+        // until then the work system's own name for the client.
+        clientName: o?.contactName ?? item.clientName ?? null,
+        workClientName: item.clientName ?? null,
+        practitioner: item.practitioner ?? o?.practitioner ?? null,
+        department: item.department ?? null,
+        orderedOn: item.orderedOn ?? null,
+        dueOn: item.dueOn ?? null,
+        jobDate: o?.jobDate ?? null,
+        shippedOn: o?.shippedOn ?? null,
+        totalCents: o?.totalCents ?? item.totalCents ?? null,
+        lines: o ? ledgerLines(o.lines)
+          : (item.lines ?? []).map((l) => ({ code: l.code ?? null, description: l.description, amountCents: l.amountCents ?? null, mapped: Boolean(l.code && codes.has(l.code)) })),
+        obligation: o,
+      });
+    }
+  }
+  return { jobs, statuses };
+}

package/server/core/ledger.js

@@ -85,14 +85,21 @@ async function normaliseLines(tx, organisationId, lines) {
     } catch (error) {
       throw new FlowError('invalid', `line ${index + 1}: ${error.message}`);
     }
-    normalised.push({ itemCode, priceItemId, description, quantity, unitAmountCents, taxCode, ...totals });
+    // A line mapped to an account (line-mapping.js) needs no price item.
+    const accountCode = priceItemId ? null : (line.accountCode?.trim() || null);
+    const extra = {
+      ...(accountCode ? { accountCode } : {}),
+      ...(line.label ? { label: line.label } : {}),
+      ...(line.mappedBy ? { mappedBy: line.mappedBy } : {}),
+    };
+    normalised.push({ itemCode, priceItemId, description, quantity, unitAmountCents, taxCode, ...extra, ...totals });
   }
   return normalised;
 }
 
 function fingerprint(lines) {
   const keys = lines
-    .map((l) => [l.itemCode ?? l.description.toLowerCase(), l.quantity, l.unitAmountCents, l.taxCode])
+    .map((l) => [l.itemCode ?? l.accountCode ?? l.description.toLowerCase(), l.quantity, l.unitAmountCents, l.taxCode])
     .sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b)));
   return createHash('sha256').update(JSON.stringify(keys)).digest('hex');
 }
@@ -117,7 +124,7 @@ export async function observeJob(db, organisationId, job) {
       lines,
       lineFingerprint: fingerprint(lines),
       ...invoiceTotals(lines),
-      mappingComplete: lines.every((l) => l.priceItemId),
+      mappingComplete: lines.every((l) => l.priceItemId || l.accountCode),
     };
     const [existing] = await tx.select().from(billingObligations)
       .where(and(
@@ -418,8 +425,8 @@ export async function draftInvoiceForObligation(db, organisationId, obligationId
       contactId: obligation.contactId,
       reference: obligation.caseRef ?? obligation.sourceJobRef,
       dueDate,
-      lines: obligation.lines.map(({ priceItemId, description, quantity, unitAmountCents, taxCode }) => (
-        { priceItemId, description, quantity, unitAmountCents, taxCode }
+      lines: obligation.lines.map(({ priceItemId, accountCode, description, quantity, unitAmountCents, taxCode }) => (
+        { priceItemId, accountCode, description, quantity, unitAmountCents, taxCode }
       )),
     });
     // Drafting the invoice says the job is ready, whoever asked.