@arcforgelabs/flow 2026.10.25 → 2026.10.27

package/server/app.js

@@ -1,5 +1,6 @@
 import express from 'express';
 import { createConnectorApi } from './api/connector.js';
+import { createInvoicingRouter } from './api/invoicing.js';
 import { createSignInRouter } from './auth/routes.js';
 import { deployedBuildStatus } from './deployed-build.js';
 import { integrationsHealth } from './integrations/health.js';
@@ -24,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,
@@ -100,6 +103,30 @@ export function createApp({
   if (integrations && database && auth?.personAuth) {
     app.use('/api/integrations', createSetupRouter({ db: database.db, registry: integrations, personAuth: auth.personAuth, secrets, log }));
   }
+  // Invoicing for signed-in people (server/api/invoicing.js). A job's draft
+  // invoice needs a live check in the accounting system: the first enabled
+  // integration that offers `checkInvoice` (Xero) answers it.
+  if (database && auth?.personAuth) {
+    const liveCheckFor = (organisationId) => {
+      const [adapter] = integrations?.with('checkInvoice') ?? [];
+      return adapter ? (obligation) => adapter.capabilities.checkInvoice({ organisationId, obligation }) : null;
+    };
+    // Send all ready (server/core/sending.js): the first enabled integration
+    // that sends invoices (Xero).
+    const accounting = () => integrations?.with('pushInvoices')[0] ?? null;
+    app.use('/api/invoicing', createInvoicingRouter({ db: database.db, personAuth: auth.personAuth, log, liveCheckFor, accounting }));
+  }
+  // What a signed-in browser needs to report its errors and problems to the
+  // installation's own error service (docs/SENTRY.md): the first integration
+  // that offers `browserMonitoring`, or `{ on: false }`.
+  if (auth?.personAuth) {
+    app.get('/api/monitoring', auth.personAuth.requireSession, (_req, res) => {
+      res.set('Cache-Control', 'no-store');
+      const [adapter] = integrations?.with('browserMonitoring') ?? [];
+      const settings = adapter?.capabilities.browserMonitoring() ?? null;
+      res.json(settings ? { ok: true, on: true, service: adapter.id, ...settings } : { ok: true, on: false });
+    });
+  }
   for (const { path, handler } of integrations?.routes({ db: database?.db ?? null, personAuth: auth?.personAuth ?? null, log, messagePage: page }) ?? []) {
     app.use(path, handler);
   }
@@ -114,5 +141,15 @@ export function createApp({
     log,
   }));
 
+  // An error no route answered. A server fault goes to `log` (and from there
+  // to the error service, when one is on) and the answer carries no detail;
+  // any other error keeps Express's own answer.
+  app.use((error, _req, res, next) => {
+    const status = error?.status ?? error?.statusCode ?? 500;
+    if (status < 500 || res.headersSent) return next(error);
+    log.error?.(`[http] ${error?.message ?? error}`, ...(error instanceof Error ? [error] : []));
+    return res.status(500).json({ ok: false, code: 'internal', error: 'Something went wrong.' });
+  });
+
   return app;
 }

package/server/auth/people.js

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

package/server/auth/routes.js

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

package/server/core/automations.js

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

package/server/core/invoice-rules.js

@@ -0,0 +1,224 @@
+import { and, asc, eq, sql } from 'drizzle-orm';
+import { invoiceRules, invoicingSettings } from '../db/schema.js';
+import { FlowError, notFound } from './errors.js';
+
+// Invoice rules (docs/INVOICE_RULES.md): a lab's own checks on a job before
+// Flow drafts its invoice. Each rule is When, If and Then, and a lab owner
+// builds it from menus, so no lab's checks are fixed in Flow's code.
+//
+//   When  job_ready: the job is ready to invoice and has no invoice yet.
+//   If    every condition matches: a field of the job, its customer or its
+//         lines, a test, and a value.
+//   Then  wait: the job waits for a person; skip: rules never draft it.
+//
+// The rules read only Flow's own records, so they work with or without an
+// accounting integration. The earlier fixed settings (old job limit, required
+// practitioner, rush share) become starter rules, once per organisation.
+
+const MAX_RULES = 100;
+const MAX_CONDITIONS = 10;
+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);
+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
+// the expected cents for `percent`.
+function share(lines, item, percent) {
+  const own = lines.filter((l) => code(l) === norm(item));
+  if (!own.length) return null;
+  const others = cents(lines.filter((l) => code(l) !== norm(item)));
+  return { charged: cents(own), others, expected: Math.round((others * percent) / 100) };
+}
+
+// Each field: what it reads from a job, its kind, and the tests it allows.
+export const FIELDS = Object.freeze({
+  job_age_days: { label: 'Job age (days)', kind: 'number', read: (j, { now }) => (j.jobDate ? Math.floor((now - day(j.jobDate)) / 86_400_000) : null) },
+  job_total: { label: 'Job total', kind: 'money', read: (j) => (j.totalCents ?? 0) / 100 },
+  job_status: { label: 'Job status', kind: 'choice', options: 'statuses', read: (j) => norm(j.sourceStatus) || null },
+  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_share: { label: 'Line share of other lines (%)', kind: 'share', options: 'items', read: (j) => j.lines ?? [] },
+});
+
+export const TESTS = Object.freeze({
+  number: ['more_than', 'at_most', 'is', 'is_not', 'is_empty'],
+  money: ['more_than', 'at_most', 'is', 'is_not'],
+  choice: ['is', 'is_not', 'is_one_of', 'is_empty'],
+  text: ['is', 'is_not', 'is_empty', 'is_not_empty'],
+  boolean: ['is'],
+  items: ['has', 'has_not'],
+  share: ['is', 'is_not'],
+});
+
+export const ACTIONS = Object.freeze(['wait', 'skip']);
+
+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 out = { field: raw.field, test: raw.test };
+  if (['is_empty', 'is_not_empty'].includes(raw.test)) return out;
+  const { value } = raw;
+  if (field.kind === 'boolean') {
+    if (typeof value !== 'boolean') throw invalid(`condition ${index + 1}: the value must be true or false`);
+  } else if (['number', 'money', 'share'].includes(field.kind)) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value < 0 || value > 1e9) throw invalid(`condition ${index + 1}: the value must be a number`);
+  } else if (raw.test === 'is_one_of') {
+    if (!Array.isArray(value) || !value.length || value.length > 50 || value.some((v) => typeof v !== 'string' || !v.trim() || v.length > 200)) {
+      throw invalid(`condition ${index + 1}: pick 1 to 50 values`);
+    }
+  } else if (typeof value !== 'string' || !value.trim() || value.length > 200) {
+    throw invalid(`condition ${index + 1}: the value must be short text`);
+  }
+  out.value = typeof value === 'string' ? value.trim() : value;
+  if (field.kind === 'share') {
+    if (typeof raw.item !== 'string' || !raw.item.trim() || raw.item.length > 100) throw invalid(`condition ${index + 1}: pick the line item`);
+    out.item = raw.item.trim();
+  }
+  return out;
+}
+
+export function readRule(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw invalid('the rule must be an object');
+  const unknown = Object.keys(raw).filter((k) => !['name', 'enabled', 'conditions', 'action'].includes(k));
+  if (unknown.length) throw invalid(`unknown field: ${unknown[0]}`);
+  const name = typeof raw.name === 'string' ? raw.name.trim() : '';
+  if (!name || name.length > 120) throw invalid('the rule needs a name of 120 characters at most');
+  const enabled = raw.enabled ?? true;
+  if (typeof enabled !== 'boolean') throw invalid('enabled must be true or false');
+  if (!Array.isArray(raw.conditions) || !raw.conditions.length || raw.conditions.length > MAX_CONDITIONS) {
+    throw invalid(`the rule needs 1 to ${MAX_CONDITIONS} conditions`);
+  }
+  if (!ACTIONS.includes(raw.action?.kind)) throw invalid(`the action must be one of ${ACTIONS.join(', ')}`);
+  return { name, enabled, conditions: raw.conditions.map(readCondition), action: { kind: raw.action.kind } };
+}
+
+function matches(condition, job, context) {
+  const field = FIELDS[condition.field];
+  const have = field.read(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);
+  switch (field.kind) {
+    case 'items': {
+      const found = have.includes(norm(value));
+      return test === 'has' ? found : !found;
+    }
+    case 'share': {
+      const s = share(have, condition.item, value);
+      if (!s) return false;
+      const right = Math.abs(s.charged - s.expected) <= 1;
+      return test === 'is' ? right : !right;
+    }
+    case 'number':
+    case 'money':
+      if (have === null) return false;
+      if (test === 'more_than') return have > value;
+      if (test === 'at_most') return have <= value;
+      if (test === 'is') return have === value;
+      return have !== value;
+    case 'boolean':
+      return have === value;
+    default: {
+      const left = norm(have);
+      if (test === 'is_one_of') return value.some((v) => norm(v) === left);
+      return test === 'is' ? left === norm(value) : left !== norm(value);
+    }
+  }
+}
+
+// The reasons the enabled rules give for one job, in rule order. An empty list
+// means no rule stops its draft. `customer` is the customer's own billing
+// settings (invoicing-rules.js).
+export function ruleReasons(rules, job, { customer = {}, now = new Date() } = {}) {
+  const context = { customer, now };
+  const reasons = [];
+  for (const rule of rules) {
+    if (!rule.enabled || rule.trigger !== 'job_ready') continue;
+    if (!rule.conditions.every((c) => matches(c, job, context))) continue;
+    reasons.push(rule.action.kind === 'skip' ? `rule "${rule.name}": not drafted by rule` : `rule "${rule.name}": waits for a person`);
+  }
+  return reasons;
+}
+
+// The starter rules made from the earlier fixed settings.
+export function starterRules(settings) {
+  const rules = [
+    { starterKey: 'not_billable', name: 'Customer not billable', enabled: true, conditions: [{ field: 'customer_billable', test: 'is', value: false }], action: { kind: 'skip' } },
+    { starterKey: 'zero_total', name: 'No amount', enabled: true, conditions: [{ field: 'job_total', test: 'at_most', value: 0 }], action: { kind: 'wait' } },
+    { starterKey: 'old_job', name: 'Old job', enabled: true, conditions: [{ field: 'job_age_days', test: 'more_than', value: settings.staleDays ?? 90 }], action: { kind: 'wait' } },
+    { starterKey: 'practitioner', name: 'Practitioner required', enabled: Boolean(settings.requirePractitioner), conditions: [{ field: 'practitioner', test: 'is_empty' }], action: { kind: 'wait' } },
+  ];
+  if (settings.rushItemCode) {
+    rules.push({
+      starterKey: 'rush_share', name: 'Rush charge share', enabled: true,
+      conditions: [{ field: 'line_share', item: settings.rushItemCode, test: 'is_not', value: settings.rushPercent ?? 20 }],
+      action: { kind: 'wait' },
+    });
+  }
+  return rules.map((r) => ({ trigger: 'job_ready', ...r }));
+}
+
+// Makes this organisation's starter rules once, from its fixed settings.
+async function seed(db, organisationId) {
+  await db.transaction(async (tx) => {
+    await tx.insert(invoicingSettings).values({ organisationId }).onConflictDoNothing();
+    const [settings] = await tx.select().from(invoicingSettings).where(eq(invoicingSettings.organisationId, organisationId)).for('update');
+    if (settings.rulesSeeded) return;
+    const rules = starterRules(settings);
+    await tx.insert(invoiceRules).values(rules.map((r, position) => ({ organisationId, position, ...r }))).onConflictDoNothing();
+    await tx.update(invoicingSettings).set({ rulesSeeded: true }).where(eq(invoicingSettings.organisationId, organisationId));
+  });
+}
+
+const shape = (r) => ({
+  id: r.id, name: r.name, position: r.position, enabled: r.enabled, trigger: r.trigger,
+  conditions: r.conditions, action: r.action, starter: Boolean(r.starterKey), updatedAt: r.updatedAt,
+});
+
+// The organisation's rules, in order. The first read makes the starter rules.
+export async function listRules(db, organisationId) {
+  const [settings] = await db.select({ seeded: invoicingSettings.rulesSeeded }).from(invoicingSettings)
+    .where(eq(invoicingSettings.organisationId, organisationId));
+  if (!settings?.seeded) await seed(db, organisationId);
+  const rows = await db.select().from(invoiceRules).where(eq(invoiceRules.organisationId, organisationId))
+    .orderBy(asc(invoiceRules.position), asc(invoiceRules.createdAt));
+  return rows.map(shape);
+}
+
+export async function createRule(db, organisationId, raw, { personId = null } = {}) {
+  const rule = readRule(raw);
+  const existing = await listRules(db, organisationId);
+  if (existing.length >= MAX_RULES) throw invalid(`an organisation can have ${MAX_RULES} rules at most`);
+  const position = existing.length ? Math.max(...existing.map((r) => r.position)) + 1 : 0;
+  const [row] = await db.insert(invoiceRules).values({ organisationId, position, ...rule, updatedBy: personId }).returning();
+  return shape(row);
+}
+
+async function loadRule(db, organisationId, ruleId) {
+  const [row] = await db.select().from(invoiceRules).where(and(eq(invoiceRules.organisationId, organisationId), eq(invoiceRules.id, ruleId)));
+  if (!row) throw notFound('rule');
+  return row;
+}
+
+// Changes a rule. `changes` holds any of name, enabled, conditions, action;
+// the result must be a whole valid rule.
+export async function updateRule(db, organisationId, ruleId, changes, { personId = null } = {}) {
+  const row = await loadRule(db, organisationId, ruleId);
+  if (!changes || typeof changes !== 'object' || Array.isArray(changes)) throw invalid('the change must be an object');
+  const rule = readRule({ name: row.name, enabled: row.enabled, conditions: row.conditions, action: row.action, ...changes });
+  const [saved] = await db.update(invoiceRules).set({ ...rule, updatedBy: personId, updatedAt: sql`now()` })
+    .where(eq(invoiceRules.id, row.id)).returning();
+  return shape(saved);
+}
+
+export async function deleteRule(db, organisationId, ruleId) {
+  const row = await loadRule(db, organisationId, ruleId);
+  await db.delete(invoiceRules).where(eq(invoiceRules.id, row.id));
+}

package/server/core/invoices.js

@@ -87,8 +87,17 @@ export async function updateDraftInvoice(db, organisationId, invoiceId, changes)
     const invoice = await loadInvoice(tx, organisationId, invoiceId, { lock: true });
     if (invoice.status !== 'draft') throw new FlowError('not_draft', 'only a draft invoice can change; revise it first');
     const fields = {};
+    if ('contactId' in changes && changes.contactId !== invoice.contactId) {
+      const [contact] = await tx.select().from(contacts)
+        .where(and(eq(contacts.organisationId, organisationId), eq(contacts.id, changes.contactId)));
+      if (!contact) throw new FlowError('invalid', 'contact not found');
+      if (contact.kind !== 'customer') throw new FlowError('invalid', 'an invoice goes to a customer contact');
+      fields.contactId = changes.contactId;
+    }
     if ('reference' in changes) fields.reference = changes.reference;
     if ('dueDate' in changes) fields.dueDate = changes.dueDate;
+    // A changed draft needs a person to check it again.
+    if (Object.keys(fields).length || 'lines' in changes) Object.assign(fields, { readyAt: null, readyBy: null });
     let row = invoice;
     if (Object.keys(fields).length) {
       [row] = await tx.update(invoices).set({ ...fields, updatedAt: sql`now()` })
@@ -153,7 +162,8 @@ export async function reviseInvoice(db, organisationId, invoiceId) {
   return db.transaction(async (tx) => {
     const invoice = await loadInvoice(tx, organisationId, invoiceId, { lock: true });
     if (invoice.status !== 'issued') throw new FlowError('not_issued', 'only an issued invoice can be revised');
-    const [row] = await tx.update(invoices).set({ status: 'draft', updatedAt: sql`now()` })
+    // A revision is a new version: what happened to the last send no longer applies.
+    const [row] = await tx.update(invoices).set({ status: 'draft', readyAt: null, readyBy: null, sendState: null, sendError: null, updatedAt: sql`now()` })
       .where(eq(invoices.id, invoice.id)).returning();
     return row;
   });