@arcforgelabs/flow 2026.10.46 → 2026.10.48

package/README.md

@@ -43,6 +43,7 @@ run a lab.
 | `docs/INVOICING_RULES.md` | The invoicing rules that draft a job's invoice, and the two ways an invoice goes to Xero |
 | `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` | The invoice tabs (Pending, Ready, Draft, Approved, Sent, Void), a changed job, and Send all ready to the accounting system |
+| `docs/CONTACTS.md` | Contacts: Flow's own customers and suppliers, and creating a missing Xero client from one |
 | `docs/RECONCILE.md` | The daily reconcile: counts and totals per day across the work system's copy, the ledger and the accounting copy |
 | `docs/ALERTS.md` | Quiet alerts: the slim line on a page when something there needs a person, and how a person dismisses it |
 | `docs/AUTOMATIONS.md` | Automations: Flow routines that mark jobs ready to invoice and draft them, each on or off |

package/VISION.md

@@ -54,16 +54,16 @@ column per stage, a card per job), with a list view of the same jobs. It
 shows every job from the case system and from Flow, with its practice, due
 date and department. Lab staff and the manager work from it.
 
-Two parts follow the board (#48):
-
-- **An intake reader.** A photo, a form or a note becomes a proposed job
-  action: update a job, create one, or add a note. A handwriting reader and a
-  low-cost decision model propose it; a person confirms it. Nothing changes
-  until a person accepts. The model steps are optional and cost money per
-  page, so the manager sees the month's cost.
-- **A practice portal.** Practice staff sign in to follow their own jobs,
-  on desktop first, with a simpler view on phones. The server limits each
-  person to their practice.
+Two parts follow the board:
+
+- **An intake reader** (#267). A photo, a form or a note becomes a proposed
+  job action: update a job, create one, or add a note. A handwriting reader
+  and a low-cost decision model propose it; a person confirms it. Nothing
+  changes until a person accepts. The model steps are optional and cost money
+  per page, so the manager sees the month's cost.
+- **A practice portal** (#268). Practice staff sign in to follow their own
+  jobs, on desktop first, with a simpler view on phones. The server limits
+  each person to their practice.
 
 Job management is a bundled module, built the same way as the integrations,
 and a lab can remove it. Where the case system cannot take a change through

package/npm-shrinkwrap.json

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

package/package.json

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

package/server/api/invoicing.js

@@ -1,10 +1,12 @@
 import { and, asc, desc, eq, ilike, inArray, isNull, or, sql } from 'drizzle-orm';
 import express from 'express';
-import { invoicePage, INVOICE_SORTS, normaliseInvoicesView } from '../ui/list-views.js';
+import { invoiceKindOf, invoicePage, INVOICE_SORTS, normaliseInvoicesView } from '../ui/list-views.js';
+import { fieldIdOf, filterRows } from '../ui/job-view.js';
+import { listFields, listJobFieldValues } from '../core/custom-fields.js';
 import { FlowError } from '../core/errors.js';
 import { createActionGuard } from '../integrations/call-guard.js';
 import {
-  createDraftInvoice, getInvoice, issueInvoice, listInvoiceVersions, reviseInvoice, updateDraftInvoice, voidInvoice,
+  createDraftInvoice, deleteDraft, getInvoice, issueInvoice, listInvoiceVersions, reviseInvoice, updateDraftInvoice, voidInvoice,
 } from '../core/invoices.js';
 import { listAutomations, saveAutomation, workStatuses } from '../core/automations.js';
 import {
@@ -31,6 +33,7 @@ import {
 import { isHistoryHeld } from '../core/history.js';
 import { invoicePdfDocument, pdfFields, pdfFilename, renderInvoicePdf } from '../core/invoice-pdf.js';
 import { invoiceView, invoiceViews, markNotReady, markReady, sendAgain, sendAllReady } from '../core/sending.js';
+import { createContact, getContact, listContacts, presentContact, updateContact } from '../core/contacts.js';
 import {
   billingObligations, contacts, invoices, INVOICE_STATUSES, organisations, priceItems, TAX_CODES,
 } from '../db/schema.js';
@@ -45,7 +48,9 @@ import {
 //   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, invoiceIds? (only these; one that fails
-//                                     a check now stays on Pending and counts as held) }
+//                                     a check now stays on Pending and counts as held; one id is all or
+//                                     nothing when its job cannot be confirmed, more than one id sends the
+//                                     rest and counts the unconfirmed in waiting) }
 //   POST  /invoices/send-again        owner or admin: queue failed sends again { invoiceIds? }
 //   GET   /invoices/:id               one invoice: lines, contact, job, issued versions, and where it sends
 //   GET   /invoices/:id/pdf?version=  the invoice as a PDF, drawn by Flow (server/core/invoice-pdf.js),
@@ -56,6 +61,8 @@ import {
 //   POST  /invoices/:id/issue         owner or admin: number it and keep the document as sent
 //   POST  /invoices/:id/revise        owner or admin: an issued invoice back to a draft
 //   POST  /invoices/:id/void          owner or admin
+//   DELETE /invoices/:id              owner or admin: a draft that was never issued.
+//                                     Frees its job, and the lab's rules then decide.
 //   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;
@@ -124,8 +131,9 @@ 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, conflict: 409,
-  accounting_not_connected: 409, accounting_writes_off: 409,
+  never_issued: 409, was_issued: 409, not_ready: 409, live_check_unavailable: 409, conflict: 409,
+  accounting_not_connected: 409, accounting_writes_off: 409, accounting_unavailable: 409, accounting_approved: 409,
+  conflict: 409,
 };
 
 function sendError(res, error, log) {
@@ -449,17 +457,43 @@ export function createInvoicingRouter({
       const pattern = containing(q);
       where.push(or(ilike(invoices.number, pattern), ilike(invoices.reference, pattern), ilike(contacts.name, pattern)));
     }
-    // First the few columns the filter and sort read, for every row; then
-    // the whole rows of the one page.
-    const light = (await db.select({
+    // First the columns the filter and sort read, for every row; then the
+    // whole rows of the one page. A job column and a custom field read the
+    // invoice's job, so those values are on every row before the page is cut.
+    const lightRows = await db.select({
       id: invoices.id, number: invoices.number, reference: invoices.reference, issueDate: invoices.issueDate,
-      createdAt: invoices.createdAt, totalCents: invoices.totalCents, contactName: contacts.name,
+      dueDate: invoices.dueDate, createdAt: invoices.createdAt, totalCents: invoices.totalCents, contactName: contacts.name,
     }).from(invoices)
       .leftJoin(contacts, eq(contacts.id, invoices.contactId))
       .where(and(...where))
-      .orderBy(desc(invoices.createdAt), desc(invoices.id)))
-      .map((row) => ({ ...row, problems: tabs.problems.get(row.id) ?? [] }));
-    const page = invoicePage(light, { view, sort, dir, offset, limit, today: day });
+      .orderBy(desc(invoices.createdAt), desc(invoices.id));
+    const jobs = await jobsByInvoice(db, organisationId, lightRows.map((r) => r.id));
+    const customOn = filterRows(view).some((f) => fieldIdOf(f.field));
+    const [fieldDefs, fieldValues] = customOn
+      ? await Promise.all([
+        listFields(db, organisationId),
+        listJobFieldValues(db, organisationId, { jobs: [...jobs.values()].filter(Boolean) }),
+      ])
+      : [[], []];
+    const valuesOf = new Map();
+    for (const v of fieldValues) {
+      const key = `${v.sourceSystem}\u0000${v.sourceJobRef}`;
+      const bag = valuesOf.get(key) ?? {};
+      bag[v.fieldId] = v.value;
+      valuesOf.set(key, bag);
+    }
+    const light = lightRows.map((row) => {
+      const job = jobs.get(row.id) ?? null;
+      return {
+        ...row,
+        problems: tabs.problems.get(row.id) ?? [],
+        tab: tabs.tabOf.get(row.id) ?? null,
+        sending: tabs.sending.has(row.id),
+        job,
+        fields: job ? valuesOf.get(`${job.sourceSystem}\u0000${job.sourceJobRef}`) ?? {} : {},
+      };
+    });
+    const page = invoicePage(light, { view, sort, dir, offset, limit, today: day, kindOf: invoiceKindOf(fieldDefs), me: req.person.id });
     const pageIds = page.rows.map((r) => r.id);
     const full = pageIds.length
       ? await db.select({ invoice: invoices, contactName: contacts.name }).from(invoices)
@@ -468,7 +502,6 @@ export function createInvoicingRouter({
       : [];
     const byId = new Map(full.map((r) => [r.invoice.id, r]));
     const rows = pageIds.map((id) => byId.get(id)).filter(Boolean);
-    const jobs = await jobsByInvoice(db, organisationId, rows.map((r) => r.invoice.id));
     const systems = work();
     res.json({
       ok: true,
@@ -486,8 +519,9 @@ export function createInvoicingRouter({
       limit,
       total: page.total,
       totalCents: page.totalCents,
-      // The Filter chip's Client choices: every client of the tab.
+      // The Filter chip's choices, from every row of the tab.
       clients: [...new Set(light.map((r) => r.contactName).filter(Boolean))].sort((a, b) => a.localeCompare(b)),
+      practitioners: [...new Set(light.map((r) => r.job?.practitioner).filter(Boolean))].sort((a, b) => a.localeCompare(b)),
       sendsTo: system?.name ?? null,
       sendMode: mode,
       // The Linked column: one icon for each connected system.
@@ -593,8 +627,8 @@ export function createInvoicingRouter({
     // the job at its source or adopt the change (ledger.js), as Move to
     // Ready and Send do.
     const { problems } = await invoiceView(db, organisationId, await getInvoice(db, organisationId, invoiceId));
-    // A lab's pending rule (invoice-rules.js) is a gate too: fix its cause
-    // or turn the rule off.
+    // A lab's pending rule, or a skip rule the job matches (invoice-rules.js),
+    // is a gate too: fix its cause, void the draft, or turn the rule off.
     const held = problems.find((p) => p.code === 'job_review' || p.code === 'rule');
     if (held) throw new FlowError('not_ready', `${held.message.replace(/\.?$/, '.')} Nothing was approved.`);
     const issued = await issueInvoice(db, organisationId, invoiceId, { issuedBy: `person:${req.person.id}`, issueDate });
@@ -618,16 +652,49 @@ export function createInvoicingRouter({
     res.json({ ok: true, invoice: await invoiceDetail(db, organisationId, invoiceId, accounting(), work()) });
   }));
 
+  router.delete('/invoices/:id', ...manager, handle(log, async (req, res) => {
+    const invoiceId = pathId(req.params.id, 'invoice');
+    const organisationId = await organisationOf(req);
+    const removed = await deleteDraft(db, organisationId, invoiceId, { actor: `person:${req.person.id}`, accounting: accounting() });
+    log.info?.(`[invoicing] organisation ${organisationId}: person ${req.person.id} ${removed.status === 'void' ? 'voided invoice' : 'deleted draft invoice'} ${invoiceId}`);
+    res.json({ ok: true });
+  }));
+
   router.get('/contacts', ...signedIn, handle(log, async (req, res) => {
     const organisationId = await organisationOf(req);
-    const q = text(req.query.q);
-    const where = [eq(contacts.organisationId, organisationId), eq(contacts.kind, 'customer')];
-    if (q) where.push(ilike(contacts.name, containing(q)));
-    const rows = await db.select({ id: contacts.id, name: contacts.name, email: contacts.email }).from(contacts)
-      .where(and(...where)).orderBy(asc(contacts.name), asc(contacts.id)).limit(limitOf(req.query.limit, 50, 500));
+    const kind = text(req.query.kind);
+    if (kind && !['customer', 'supplier', 'all'].includes(kind)) throw invalid('kind must be customer, supplier or all');
+    const active = text(req.query.active);
+    if (active && !['true', 'false', 'all'].includes(active)) throw invalid('active must be true, false or all');
+    const rows = await listContacts(db, organisationId, {
+      q: text(req.query.q),
+      kind: kind === 'all' ? null : (kind || 'customer'),
+      active: active === 'all' ? null : active === 'false' ? false : true,
+      limit: limitOf(req.query.limit, 50, 500),
+      offset: offsetOf(req.query.offset),
+    });
     res.json({ ok: true, contacts: rows });
   }));
 
+  router.post('/contacts', ...manager, handle(log, async (req, res) => {
+    const organisationId = await organisationOf(req);
+    const contact = presentContact(await createContact(db, organisationId, req.body ?? {}));
+    log.info?.(`[invoicing] organisation ${organisationId}: person ${req.person.id} created contact ${contact.id}`);
+    res.status(201).json({ ok: true, contact });
+  }));
+
+  router.get('/contacts/:id', ...signedIn, handle(log, async (req, res) => {
+    const organisationId = await organisationOf(req);
+    res.json({ ok: true, contact: presentContact(await getContact(db, organisationId, pathId(req.params.id, 'contact'))) });
+  }));
+
+  router.patch('/contacts/:id', ...manager, handle(log, async (req, res) => {
+    const organisationId = await organisationOf(req);
+    const contact = presentContact(await updateContact(db, organisationId, pathId(req.params.id, 'contact'), req.body ?? {}));
+    log.info?.(`[invoicing] organisation ${organisationId}: person ${req.person.id} updated contact ${contact.id}`);
+    res.json({ ok: true, contact });
+  }));
+
   router.get('/price-items', ...signedIn, handle(log, async (req, res) => {
     const organisationId = await organisationOf(req);
     const q = text(req.query.q);
@@ -842,7 +909,7 @@ export function createInvoicingRouter({
     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], draftOnly: Boolean(f.draftOnly),
+        key, label: f.label, kind: f.kind, options: f.options ?? null, tests: f.tests ?? TESTS[f.kind], draftOnly: Boolean(f.draftOnly),
       })),
       actions: ACTIONS,
       options: {

package/server/auth/people.js

@@ -4,6 +4,7 @@ import { FlowError } from '../core/errors.js';
 import { isThemeFamily, normalizeAccent } from '../theme/themes.js';
 import { invoiceColumnsView, normaliseJobsView, normaliseListView, PRICE_COLUMNS, RECONCILE_COLUMNS } from '../ui/job-view.js';
 import { normaliseSavedViews, SAVED_VIEW_PAGES } from '../ui/list-views.js';
+import { normaliseNavPins } from '../ui/nav-pins.js';
 import { isPlainEmail } from './settings.js';
 
 // The people who may sign in, and their roles. Only an owner changes this
@@ -61,10 +62,11 @@ function viewCheck(page) {
     case 'invoices': return invoiceColumnsView;
     case 'reconcile': return (view) => normaliseListView(view, RECONCILE_COLUMNS);
     case 'price-list': return (view) => normaliseListView(view, PRICE_COLUMNS);
+    case 'nav': return normaliseNavPins;
     default: return null;
   }
 }
-const VIEW_PAGE_NAMES = ['jobs', 'invoices', 'reconcile', 'price-list'];
+const VIEW_PAGE_NAMES = ['jobs', 'invoices', 'reconcile', 'price-list', 'nav'];
 
 // A person's saved views as Flow sends them: only the known pages, each
 // checked, so a view saved by an older Flow still loads.

package/server/auth/routes.js

@@ -19,6 +19,7 @@ import {
 } from './people.js';
 import { isPlainEmail } from './settings.js';
 import { APP_PATHS, appPage } from '../ui/app-page.js';
+import { navPinsFromViews } from '../ui/nav-pins.js';
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 const ERROR_STATUS = { invalid: 400, forbidden: 403, not_found: 404, conflict: 409 };
 
@@ -104,6 +105,8 @@ export function createSignInRouter({ settings, db, clerk, personAuth, defaultFam
     }
     body.appearance = req.person.appearance ? normaliseAppearance(req.person.appearance) : null;
     body.views = normaliseViews(req.person.views);
+    // No pins saved yet: today's sidebar. A saved choice is checked the same way.
+    body.views.nav = navPinsFromViews(req.person.views);
     res.json(body);
   });
 
@@ -118,7 +121,7 @@ export function createSignInRouter({ settings, db, clerk, personAuth, defaultFam
   });
 
   // Each person sets their own view of a page (how Jobs groups, sorts and
-  // filters); it follows their account.
+  // filters, and which pages are pinned: `nav`). It follows their account.
   router.put('/api/me/views/:page', requireSession, express.json({ limit: '8kb' }), async (req, res) => {
     try {
       const view = await setPersonView(db, { id: req.person.id, page: req.params.page, view: req.body });

package/server/core/contacts.js

@@ -0,0 +1,160 @@
+import { and, asc, eq, ilike, or, sql } from 'drizzle-orm';
+import { contacts, CONTACT_KINDS } from '../db/schema.js';
+import { FlowError, notFound } from './errors.js';
+
+// Flow's own contacts (docs/CONTACTS.md). A contact is a customer or a
+// supplier the lab bills or buys from. The fields are what Xero needs to
+// bill them and what Seazona keeps for the practice a job belongs to.
+// Practitioners are people at that practice. Flow stores no patient.
+
+const NAME_MAX = 255;
+const TEXT_MAX = 255;
+const SHORT_MAX = 50;
+const PRACTITIONERS_MAX = 30;
+const ADDRESS_KEYS = ['line1', 'line2', 'city', 'region', 'postalCode', 'country'];
+
+const invalid = (message) => new FlowError('invalid', message);
+
+function text(value, name, max) {
+  if (value == null || value === '') return null;
+  if (typeof value !== 'string') throw invalid(`${name} must be text`);
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+  if (trimmed.length > max) throw invalid(`${name} is too long (${max} characters at most)`);
+  return trimmed;
+}
+
+function readAddress(raw) {
+  if (raw == null) return null;
+  if (typeof raw !== 'object' || Array.isArray(raw)) throw invalid('address must be an object');
+  const out = {};
+  for (const key of ADDRESS_KEYS) {
+    const value = text(raw[key], `address.${key}`, TEXT_MAX);
+    if (value) out[key] = value;
+  }
+  return Object.keys(out).length ? out : null;
+}
+
+function readPractitioners(raw) {
+  if (raw == null) return [];
+  if (!Array.isArray(raw)) throw invalid('practitioners must be a list');
+  if (raw.length > PRACTITIONERS_MAX) throw invalid(`a contact has ${PRACTITIONERS_MAX} practitioners at most`);
+  return raw.map((item, index) => {
+    const at = `practitioner ${index + 1}`;
+    const source = typeof item === 'string' ? { name: item } : item;
+    if (!source || typeof source !== 'object' || Array.isArray(source)) throw invalid(`${at} must be a name`);
+    const name = text(source.name, `${at} name`, NAME_MAX);
+    if (!name) throw invalid(`${at} needs a name`);
+    const email = text(source.email, `${at} email`, TEXT_MAX);
+    return email ? { name, email } : { name };
+  });
+}
+
+// The fields a create or an update may set. `partial` is an update: only the
+// keys the caller sent are returned.
+export function readContact(input, { partial = false } = {}) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) throw invalid('contact must be an object');
+  const out = {};
+  const has = (key) => Object.prototype.hasOwnProperty.call(input, key);
+  if (!partial || has('kind')) {
+    if (!CONTACT_KINDS.includes(input.kind)) throw invalid(`kind must be ${CONTACT_KINDS.join(' or ')}`);
+    out.kind = input.kind;
+  }
+  if (!partial || has('name')) {
+    const name = text(input.name, 'name', NAME_MAX);
+    if (!name) throw invalid('contact name is required');
+    out.name = name;
+  }
+  if (!partial || has('firstName')) out.firstName = text(input.firstName, 'firstName', NAME_MAX);
+  if (!partial || has('lastName')) out.lastName = text(input.lastName, 'lastName', NAME_MAX);
+  if (!partial || has('email')) out.email = text(input.email, 'email', TEXT_MAX);
+  if (!partial || has('phone')) out.phone = text(input.phone, 'phone', SHORT_MAX);
+  if (!partial || has('mobile')) out.mobile = text(input.mobile, 'mobile', SHORT_MAX);
+  if (!partial || has('accountNumber')) out.accountNumber = text(input.accountNumber, 'accountNumber', SHORT_MAX);
+  if (!partial || has('taxNumber')) out.taxNumber = text(input.taxNumber, 'taxNumber', SHORT_MAX);
+  if (!partial || has('taxRate')) out.taxRate = text(input.taxRate, 'taxRate', SHORT_MAX);
+  if (!partial || has('address')) out.address = readAddress(input.address);
+  if (!partial || has('practitioners')) out.practitioners = readPractitioners(input.practitioners);
+  if (!partial || has('active')) {
+    if (input.active != null && typeof input.active !== 'boolean') throw invalid('active must be true or false');
+    out.active = input.active !== false;
+  }
+  return out;
+}
+
+function duplicate(error, kind) {
+  const code = error?.code ?? error?.cause?.code;
+  if (code === '23505') throw new FlowError('conflict', `A ${kind ?? 'contact'} with this name already exists.`);
+  throw error;
+}
+
+export function presentContact(row) {
+  return {
+    id: row.id,
+    kind: row.kind,
+    name: row.name,
+    firstName: row.firstName ?? null,
+    lastName: row.lastName ?? null,
+    email: row.email ?? null,
+    phone: row.phone ?? null,
+    mobile: row.mobile ?? null,
+    accountNumber: row.accountNumber ?? null,
+    taxNumber: row.taxNumber ?? null,
+    taxRate: row.taxRate ?? null,
+    address: row.address ?? null,
+    practitioners: row.practitioners ?? [],
+    active: row.active !== false,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+}
+
+export async function createContact(db, organisationId, input) {
+  const values = readContact(input);
+  try {
+    const [row] = await db.insert(contacts).values({ organisationId, ...values }).returning();
+    return row;
+  } catch (error) {
+    duplicate(error, values.kind);
+  }
+}
+
+export async function getContact(db, organisationId, id) {
+  const [row] = await db.select().from(contacts)
+    .where(and(eq(contacts.organisationId, organisationId), eq(contacts.id, id)));
+  if (!row) throw notFound('contact');
+  return row;
+}
+
+export async function updateContact(db, organisationId, id, input) {
+  const current = await getContact(db, organisationId, id);
+  const patch = readContact(input, { partial: true });
+  if (!Object.keys(patch).length) return current;
+  try {
+    const [row] = await db.update(contacts)
+      .set({ ...patch, updatedAt: sql`now()` })
+      .where(and(eq(contacts.organisationId, organisationId), eq(contacts.id, id)))
+      .returning();
+    return row;
+  } catch (error) {
+    duplicate(error, patch.kind ?? current.kind);
+  }
+}
+
+// `kind` null lists customers and suppliers. `active` null lists both.
+export async function listContacts(db, organisationId, { q = '', kind = 'customer', active = true, limit = 200, offset = 0 } = {}) {
+  const where = [eq(contacts.organisationId, organisationId)];
+  if (kind) where.push(eq(contacts.kind, kind));
+  if (active === true) where.push(eq(contacts.active, true));
+  if (active === false) where.push(eq(contacts.active, false));
+  const needle = String(q ?? '').trim().replace(/[\\%_]/g, (c) => `\\${c}`);
+  if (needle) {
+    const like = `%${needle}%`;
+    where.push(or(ilike(contacts.name, like), ilike(contacts.email, like), ilike(contacts.accountNumber, like)));
+  }
+  const rows = await db.select().from(contacts).where(and(...where))
+    .orderBy(asc(contacts.name), asc(contacts.id))
+    .limit(limit)
+    .offset(offset);
+  return rows.map(presentContact);
+}

package/server/core/directory.js

@@ -1,5 +1,6 @@
 import { and, eq, isNull } from 'drizzle-orm';
-import { contacts, organisations, priceItems, CONTACT_KINDS, TAX_CODES } from '../db/schema.js';
+import { organisations, priceItems, TAX_CODES } from '../db/schema.js';
+import { createContact as insertContact } from './contacts.js';
 import { FlowError } from './errors.js';
 
 // Organisations, contacts and the price list: the records invoices and bills
@@ -13,14 +14,8 @@ export async function createOrganisation(db, { name, invoicePrefix }) {
   return row;
 }
 
-export async function createContact(db, organisationId, { kind, name, email = null }) {
-  if (!CONTACT_KINDS.includes(kind)) throw new FlowError('invalid', `unknown contact kind: ${kind}`);
-  if (!name?.trim()) throw new FlowError('invalid', 'contact name is required');
-  const [row] = await db.insert(contacts)
-    .values({ organisationId, kind, name: name.trim(), email })
-    .returning();
-  return row;
-}
+// Contacts live in contacts.js. This name stays so existing callers keep working.
+export const createContact = insertContact;
 
 export async function createPriceItem(db, organisationId, { code, name, unitAmountCents, taxCode = 'GST' }) {
   if (!code?.trim() || !name?.trim()) throw new FlowError('invalid', 'price item code and name are required');

package/server/core/invoice-rules.js

@@ -47,7 +47,14 @@ export const FIELDS = Object.freeze({
   practitioner: { label: 'Practitioner', kind: 'text', options: 'practitioners', read: (j, { customer }) => j.practitioner || customer.defaultPractitioner || null },
   // Only a draft has a Reference, so only a pending rule may read it.
   reference: { label: 'Reference', kind: 'text', draftOnly: true, read: (j) => j.reference || null },
-  customer: { label: 'Customer', kind: 'choice', options: 'customers', read: (j) => j.contactId },
+  // Menu tests read the contact id. Contains and does not contain read the
+  // customer's name (matches): a lab can exclude every name that contains
+  // one marker, so a new branch needs no new rule.
+  customer: {
+    label: 'Customer', kind: 'choice', options: 'customers',
+    tests: ['is', 'is_not', 'is_one_of', 'contains', 'does_not_contain', 'is_empty'],
+    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 ?? []).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 ?? [] },
@@ -71,7 +78,8 @@ function readCondition(raw, index) {
   if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw invalid(`condition ${index + 1} must be an object`);
   const field = FIELDS[raw.field];
   if (!field) throw invalid(`condition ${index + 1}: unknown field ${raw.field}`);
-  if (!TESTS[field.kind].includes(raw.test)) throw invalid(`condition ${index + 1}: ${field.label} takes ${TESTS[field.kind].join(', ')}`);
+  const allowed = field.tests ?? TESTS[field.kind];
+  if (!allowed.includes(raw.test)) throw invalid(`condition ${index + 1}: ${field.label} takes ${allowed.join(', ')}`);
   const out = { field: raw.field, test: raw.test };
   if (NO_VALUE.has(raw.test)) return out;
   const { value } = raw;
@@ -125,9 +133,13 @@ function matches(condition, job, context) {
   const { test, value } = condition;
   if (test === 'is_empty') return have === null || have === '' || have === undefined;
   if (test === 'is_not_empty') return !(have === null || have === '' || have === undefined);
-  if (field.kind === 'text' && !['is', 'is_not', 'is_one_of'].includes(test)) {
+  // Customer contains reads the contact's name, in any case and with the
+  // spaces trimmed, the same way a practitioner's name is read. is, is not
+  // and is one of still compare the contact id. `customer.name` is that name.
+  const named = condition.field === 'customer' && (test === 'contains' || test === 'does_not_contain');
+  if ((field.kind === 'text' || named) && !['is', 'is_not', 'is_one_of'].includes(test)) {
     // An empty text matches no test that reads its words; is_empty finds it.
-    const left = norm(have);
+    const left = norm(named ? (context.customer?.name ?? job.customerName ?? null) : have);
     if (!left) return false;
     if (test === 'is_not_one_of') return !value.some((v) => norm(v) === left);
     if (test === 'has_number') return /\d/.test(left);
@@ -195,6 +207,24 @@ export function rulePending(rules, job, { customer = {}, now = new Date() } = {}
     .map((r) => ({ code: 'rule', message: r.action.note, short: r.name.slice(0, 40), rule: r.id ?? null, fields: [...new Set(r.conditions.map((c) => c.field))] }));
 }
 
+// Drafts an enabled skip rule matches stay on Pending at Send (sending.js).
+// A person drafted the job by hand, or the rule was made after the draft.
+// The list shows the rule's name. The note says to void the draft or change
+// the rule. A wait rule does not hold a draft: a person may still send one.
+export function ruleSkip(rules, job, { customer = {}, now = new Date() } = {}) {
+  const context = { customer, now };
+  return rules
+    .filter((r) => r.enabled && r.trigger === 'job_ready' && r.action.kind === 'skip')
+    .filter((r) => r.conditions.every((c) => matches(c, job, context)))
+    .map((r) => ({
+      code: 'rule',
+      message: `Rule "${r.name}": not invoiced. Void this draft or change the rule.`,
+      short: r.name.slice(0, 40),
+      rule: r.id ?? null,
+      fields: [...new Set(r.conditions.map((c) => c.field))],
+    }));
+}
+
 // The starter rules made from the earlier fixed settings.
 export function starterRules(settings) {
   const rules = [