@arcforgelabs/flow 2026.10.30 → 2026.10.32

package/server/app.js

@@ -1,7 +1,10 @@
 import express from 'express';
+import { createAlertsRouter } from './api/alerts.js';
 import { createConnectorApi } from './api/connector.js';
 import { createInvoicingRouter } from './api/invoicing.js';
 import { createSignInRouter } from './auth/routes.js';
+import { integrationAlertsSource, invoiceProblemsSource, priceDifferencesSource } from './core/alerts.js';
+import { appliedMigrationCounts } from './db/doctor.js';
 import { deployedBuildStatus } from './deployed-build.js';
 import { integrationsHealth } from './integrations/health.js';
 import { createSetupRouter } from './integrations/setup.js';
@@ -27,10 +30,14 @@ import { createUiAssetsRouter } from './ui/routes.js';
 // each one (server/integrations/health.js). `defaultFamily` is the design
 // 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.
+// sends each error to the installation's error service. `schemaJournals` are
+// the migration journals this build ships (server/db/doctor.js): GET /health
+// reports how many of each the database has applied, so the workspace's
+// doctor can tell what Replit's publish step will offer (docs/REPLIT.md).
 export function createApp({
   build = deployedBuildStatus(),
   database = null,
+  schemaJournals = null,
   auth = null,
   updates = null,
   integrations = null,
@@ -59,6 +66,11 @@ export function createApp({
     // records). An integration problem does not fail the health check: Flow's
     // core works with no integration connected (VISION.md).
     const body = { ok, service: 'flow', database: databaseOk, build };
+    // Counts only: no table names and no data.
+    if (databaseOk && schemaJournals) {
+      body.schema = await appliedMigrationCounts(database.pool, schemaJournals)
+        .then((migrations) => ({ migrations }), () => null);
+    }
     if (integrations) body.integrations = await integrationsHealth(integrations);
     res.status(ok ? 200 : 503).json(body);
   });
@@ -116,7 +128,22 @@ export function createApp({
     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 }));
+    // The price list: every enabled integration that keeps its own (Xero
+    // items, Seazona products).
+    const priceSystems = () => integrations?.with('listPriceItems') ?? [];
+    app.use('/api/invoicing', createInvoicingRouter({ db: database.db, personAuth: auth.personAuth, log, liveCheckFor, accounting, work, priceSystems }));
+    // Quiet alerts (server/core/alerts.js): what needs a person on each page.
+    // Integrations add their own through the `alerts` capability.
+    app.use('/api/alerts', createAlertsRouter({
+      db: database.db,
+      personAuth: auth.personAuth,
+      log,
+      sources: {
+        invoices: [invoiceProblemsSource(database.db, { accounting })],
+        'price-list': [priceDifferencesSource(database.db)],
+        integrations: [integrationAlertsSource(() => integrations?.with('alerts') ?? [])],
+      },
+    }));
   }
   // 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/alerts.js

@@ -0,0 +1,157 @@
+import { createHash } from 'node:crypto';
+import { and, eq, inArray, sql } from 'drizzle-orm';
+import { alertDismissals, invoices } from '../db/schema.js';
+import { FlowError } from './errors.js';
+import { listReview } from './review.js';
+import { invoiceViews } from './sending.js';
+
+// Quiet alerts (issue 117, docs/ALERTS.md). An alert says that something on
+// one page needs a person. Nothing shows when nothing does: there is no feed,
+// no "done" message, no email and no sound. An alert is worked out each time
+// a page asks, from Flow's own records (the review queue, the Invoices views,
+// each integration's call guard), so it goes away for everyone as soon as its
+// cause is fixed. Only a person's dismissal is stored: it hides the alert for
+// that person until something new joins it.
+//
+// An alert is { key, page, tone, title, action, moneyAtRiskCents, roles,
+// members }. `key` starts with its page. `members` are the things it is
+// about (an invoice id, a review item and its evidence, a stop and its time);
+// they never leave the server. `roles` are who may see it. `action`, when
+// there is one, is { label, href } or { label, tab } for a tab on the page.
+
+export const ALERT_PAGES = Object.freeze(['invoices', 'price-list', 'integrations']);
+const ALL_ROLES = Object.freeze(['owner', 'admin', 'staff']);
+const MANAGERS = Object.freeze(['owner', 'admin']);
+const TONES = new Set(['warn', 'danger']);
+// A dismissal keeps at most this many members. An alert about more things
+// than that comes back after a dismiss: it is too large to set aside.
+const MAX_MEMBERS = 500;
+
+const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;
+const digest = (value) => createHash('sha256').update(JSON.stringify(value ?? null)).digest('hex').slice(0, 16);
+
+function checkAlert(alert) {
+  if (!ALERT_PAGES.includes(alert.page) || !alert.key?.startsWith(`${alert.page}:`)) {
+    throw new TypeError(`alert ${alert.key} must start with its page`);
+  }
+  if (!TONES.has(alert.tone)) throw new TypeError(`alert ${alert.key} tone must be warn or danger`);
+  if (!Array.isArray(alert.members) || !alert.members.length) throw new TypeError(`alert ${alert.key} needs members`);
+  return { moneyAtRiskCents: 0, roles: ALL_ROLES, action: null, ...alert, members: alert.members.map(String) };
+}
+
+// ── Sources ────────────────────────────────────────────────────────────────
+
+// Invoices: drafts a check stopped and issued invoices the accounting system
+// refused (server/core/sending.js). One alert for all of them.
+export function invoiceProblemsSource(db, { accounting = () => null } = {}) {
+  return async (organisationId) => {
+    const { problems } = await invoiceViews(db, organisationId, { accounting: accounting() });
+    const ids = [...problems.keys()];
+    if (!ids.length) return [];
+    const [{ total }] = await db.select({ total: sql`coalesce(sum(${invoices.totalCents}), 0)` }).from(invoices)
+      .where(and(eq(invoices.organisationId, organisationId), inArray(invoices.id, ids)));
+    return [{
+      key: 'invoices:problems',
+      page: 'invoices',
+      tone: 'warn',
+      title: `${plural(ids.length, 'invoice has', 'invoices have')} a problem.`,
+      action: { label: 'Open Problem', tab: 'problem' },
+      moneyAtRiskCents: Number(total),
+      members: ids,
+    }];
+  };
+}
+
+// Price list: codes whose price, tax or name differs in a connected system
+// (server/core/price-list.js). A difference is an alert only: the person
+// fixes it at the source, or marks it resolved on the code.
+export function priceDifferencesSource(db) {
+  return async (organisationId) => {
+    const open = await listReview(db, organisationId, { kind: 'price_check', limit: MAX_MEMBERS });
+    if (!open.length) return [];
+    return [{
+      key: 'price-list:differences',
+      page: 'price-list',
+      tone: 'warn',
+      title: `${plural(open.length, 'code differs', 'codes differ')} from a connected system. Fix it at the source, or open the code and mark it resolved.`,
+      moneyAtRiskCents: open.reduce((sum, item) => sum + Number(item.moneyAtRiskCents ?? 0), 0),
+      members: open.map((item) => `${item.id}:${digest(item.evidence)}`),
+    }];
+  };
+}
+
+// Integrations: each enabled integration that offers `alerts` says what only
+// a person can clear (a refused sign-in, a stopped call). Owners and admins
+// see these; staff cannot change integrations.
+export function integrationAlertsSource(adapters = () => []) {
+  return async (organisationId) => {
+    const found = await Promise.all(adapters().map(async (adapter) => {
+      const items = await adapter.capabilities.alerts({ organisationId });
+      return (items ?? []).map((item) => ({
+        key: `integrations:${adapter.id}:${item.id}`,
+        page: 'integrations',
+        tone: item.tone ?? 'danger',
+        title: item.title,
+        action: { label: `Open ${adapter.name}`, href: `/integrations/${adapter.id}` },
+        roles: MANAGERS,
+        members: item.members,
+      }));
+    }));
+    return found.flat();
+  };
+}
+
+// ── Reading and dismissing ─────────────────────────────────────────────────
+
+async function collect(sources, page, organisationId) {
+  const list = await Promise.all((sources[page] ?? []).map((source) => source(organisationId)));
+  return list.flat().map(checkAlert);
+}
+
+// The alerts one person should see on one page, worst first: danger before
+// warn, then most money at risk. A dismissed alert stays hidden while every
+// member it has now was a member when it was dismissed.
+// `scope` narrows a page to one part of it: an integration's own page
+// (/integrations/xero) shows only the alerts whose key is integrations:xero:….
+// `withHidden` also answers the alerts this person dismissed, each marked
+// `hidden`, for a page that shows a state (a red status) whatever the line.
+export async function alertsFor(db, organisationId, person, { page, scope = null, sources, withHidden = false }) {
+  if (!ALERT_PAGES.includes(page)) throw new FlowError('invalid', `page must be one of ${ALERT_PAGES.join(', ')}`);
+  const prefix = scope ? `${page}:${scope}:` : null;
+  const alerts = (await collect(sources, page, organisationId))
+    .filter((a) => a.roles.includes(person.role) && (!prefix || a.key.startsWith(prefix)));
+  if (!alerts.length) return [];
+  const rows = await db.select().from(alertDismissals).where(and(
+    eq(alertDismissals.organisationId, organisationId),
+    eq(alertDismissals.personId, person.id),
+    inArray(alertDismissals.alertKey, alerts.map((a) => a.key)),
+  ));
+  const dismissed = new Map(rows.map((r) => [r.alertKey, new Set(r.members)]));
+  return alerts
+    .map((a) => ({ ...a, hidden: dismissed.has(a.key) && a.members.every((m) => dismissed.get(a.key).has(m)) }))
+    .filter((a) => withHidden || !a.hidden)
+    .sort((a, b) => (a.tone === b.tone ? 0 : a.tone === 'danger' ? -1 : 1) || b.moneyAtRiskCents - a.moneyAtRiskCents);
+}
+
+// What the browser gets: no members, only how many there are.
+export const alertForBrowser = ({ key, tone, title, action, moneyAtRiskCents, members }) => ({
+  key, tone, title, action, moneyAtRiskCents, count: members.length,
+});
+
+// Hides one alert for one person. The server works the alert out again, so
+// the stored members are what the person saw, not what a browser sent.
+// Dismissing an alert that is gone is not an error.
+export async function dismissAlert(db, organisationId, person, { key, sources }) {
+  const page = ALERT_PAGES.find((p) => String(key ?? '').startsWith(`${p}:`));
+  if (!page) throw new FlowError('invalid', 'key must name an alert');
+  const alert = (await collect(sources, page, organisationId)).find((a) => a.key === key && a.roles.includes(person.role));
+  if (!alert) return { dismissed: false };
+  const members = alert.members.slice(0, MAX_MEMBERS);
+  await db.insert(alertDismissals)
+    .values({ organisationId, personId: person.id, alertKey: key, members })
+    .onConflictDoUpdate({
+      target: [alertDismissals.organisationId, alertDismissals.personId, alertDismissals.alertKey],
+      set: { members, dismissedAt: sql`now()` },
+    });
+  return { dismissed: true };
+}

package/server/core/automations.js

@@ -1,9 +1,10 @@
 import { and, eq, sql } from 'drizzle-orm';
 import { automations, billingObligations, invoices } from '../db/schema.js';
 import { FlowError, notFound } from './errors.js';
-import { autoDraftJobs } from './invoicing-rules.js';
+import { autoDraftJobs, readInvoicingSettings } from './invoicing-rules.js';
 import { MAPPING_DEFAULTS, readMappingConfig, remapJobs } from './line-mapping.js';
 import { setReady } from './ledger.js';
+import { refreshReferences } from './references.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,
@@ -19,6 +20,8 @@ import { setReady } from './ledger.js';
 //     rules (invoicing-rules.js) gets a draft invoice in Flow.
 //   ready_when_drafted: a draft the draft routine made goes straight to Ready
 //     on the Invoices page, until a person changes it or moves it back.
+//   reference_from_rule: a draft made from a job keeps the Reference the
+//     lab's Reference rule gives (references.js), as the job's fields arrive.
 
 const BATCH = 500;
 
@@ -92,6 +95,14 @@ export const AUTOMATIONS = Object.freeze([
     defaults: { enabled: true, config: {} },
     readConfig: () => ({}),
   },
+  {
+    key: 'reference_from_rule',
+    place: 'invoicing',
+    name: 'Reference from the rule',
+    hint: 'A draft made from a job gets its Reference from the Reference rule. A Reference a person typed stays.',
+    defaults: { enabled: true, config: {} },
+    readConfig: () => ({}),
+  },
 ]);
 
 const byKey = new Map(AUTOMATIONS.map((a) => [a.key, a]));
@@ -169,16 +180,19 @@ async function readyWhenDrafted(db, organisationId) {
 
 // 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() } = {}) {
+export async function runAutomations(db, organisationId, { accounting = null, work = 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) });
+      summary[automation.key] = await autoDraftJobs(db, organisationId, { accounting, work, now, actor: actorOf(automation.key) });
     } else if (automation.key === 'ready_when_drafted') {
       summary[automation.key] = await readyWhenDrafted(db, organisationId);
+    } else if (automation.key === 'reference_from_rule') {
+      const { referenceTemplate: template } = await readInvoicingSettings(db, organisationId);
+      summary[automation.key] = await refreshReferences(db, organisationId, { template, work });
     }
   }
   return summary;

package/server/core/history.js

@@ -0,0 +1,65 @@
+import { and, asc, eq, sql } from 'drizzle-orm';
+import { billingObligations } from '../db/schema.js';
+import { FlowError, notFound } from './errors.js';
+import { setHold } from './ledger.js';
+
+// Past jobs from a work system's history import (docs/SEAZONA.md, "History
+// import"). The pipeline holds each new one (pipeline.js, ingestHistory), so
+// it never drafts. The matcher still sets its accounting state. Only a
+// person's release moves one into drafting.
+
+export const HISTORY_HOLD_REASON = 'history_import';
+export const HISTORY_ACTOR = 'import:seazona_history';
+
+export const isHistoryHeld = (obligation) => obligation?.holdState === 'held' && obligation?.holdReason === HISTORY_HOLD_REASON;
+
+// Accounting states that need a person: no invoice found, or more than one fits.
+export const HISTORY_NEEDS_PERSON = ['not_found', 'ambiguous', 'conflict'];
+
+const historyHeld = (organisationId) => and(
+  eq(billingObligations.organisationId, organisationId),
+  eq(billingObligations.holdState, 'held'),
+  eq(billingObligations.holdReason, HISTORY_HOLD_REASON),
+);
+
+// Held history jobs by accounting state: counts, and one page of jobs
+// (`state` one accounting state, or `needs_person`).
+export async function listHistoryJobs(db, organisationId, { state = null, limit = 100, offset = 0 } = {}) {
+  const counts = Object.fromEntries((await db.select({ state: billingObligations.accountingState, n: sql`count(*)::int` })
+    .from(billingObligations).where(historyHeld(organisationId)).groupBy(billingObligations.accountingState))
+    .map((r) => [r.state, r.n]));
+  const filters = [historyHeld(organisationId)];
+  if (state === 'needs_person') filters.push(sql`${billingObligations.accountingState} in ('not_found', 'ambiguous', 'conflict')`);
+  else if (state) filters.push(eq(billingObligations.accountingState, state));
+  const jobs = await db.select().from(billingObligations).where(and(...filters))
+    .orderBy(asc(billingObligations.jobDate), asc(billingObligations.sourceJobRef))
+    .limit(Math.max(1, Math.min(500, Number(limit) || 100))).offset(Math.max(0, Number(offset) || 0));
+  const needsPerson = HISTORY_NEEDS_PERSON.reduce((sum, s) => sum + (counts[s] ?? 0), 0);
+  return {
+    counts: { ...counts, total: Object.values(counts).reduce((a, b) => a + b, 0), needsPerson },
+    jobs: jobs.map((o) => ({
+      id: o.id,
+      sourceJobRef: o.sourceJobRef,
+      sourceInvoiceRef: o.sourceInvoiceRef,
+      jobDate: o.jobDate,
+      contactId: o.contactId,
+      practitioner: o.practitioner,
+      totalCents: o.totalCents,
+      accountingState: o.accountingState,
+      accountingRef: o.accountingRef,
+      accountingMatchedBy: o.accountingMatchedBy,
+    })),
+  };
+}
+
+// A person moves one held history job into drafting.
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+export async function releaseHistoryJob(db, organisationId, obligationId, { actor }) {
+  if (!UUID.test(String(obligationId))) throw Object.assign(new FlowError('invalid', 'the job id must be a Flow id'), { status: 400 });
+  const [row] = await db.select().from(billingObligations)
+    .where(and(eq(billingObligations.organisationId, organisationId), eq(billingObligations.id, obligationId)));
+  if (!row) throw Object.assign(notFound('job'), { status: 404 });
+  if (!isHistoryHeld(row)) throw Object.assign(new FlowError('conflict', 'the job is not a held history job'), { status: 409 });
+  return setHold(db, organisationId, obligationId, { holdState: 'none', actor });
+}

package/server/core/invoice-pdf.js

@@ -0,0 +1,266 @@
+import { and, asc, eq } from 'drizzle-orm';
+import PDFDocument from 'pdfkit';
+import { contacts, invoiceLines, invoiceVersions, organisations, priceItems } from '../db/schema.js';
+import { FlowError, notFound } from './errors.js';
+import { getInvoice } from './invoices.js';
+
+// An invoice as a PDF, drawn from Flow's own data: it makes no calls to an
+// accounting system. A draft is drawn from its lines as they are now. An
+// issued or void invoice is drawn from the version Flow stored when it was
+// issued, so the PDF shows what was sent. Every page carries an EXAMPLE mark:
+// the customer's copy is the one the accounting system sends.
+//
+// Nothing on the PDF is made up. Once the accounting system holds the
+// version, its number, reference and dates come from Flow's copy of that
+// system (the adapter's documentFacts, no calls). A value nobody knows yet is
+// drawn as a grey note that says so, never as a sample value.
+
+// The document for one invoice: the stored version for an issued or void
+// invoice (or the version asked for), else the draft's lines now.
+// `accounting` is the accounting adapter, or null.
+export async function invoicePdfDocument(db, organisationId, invoiceId, { version = null, accounting = null } = {}) {
+  const source = await flowDocument(db, organisationId, invoiceId, { version });
+  const ask = accounting?.capabilities?.documentFacts;
+  const facts = ask ? await ask({ organisationId, invoiceId, version: source.document.version ?? null }) : null;
+  return { ...source, facts };
+}
+
+async function flowDocument(db, organisationId, invoiceId, { version }) {
+  const invoice = await getInvoice(db, organisationId, invoiceId);
+  const [organisation] = await db.select({ name: organisations.name }).from(organisations)
+    .where(eq(organisations.id, organisationId));
+  if (version !== null || (invoice.issuedVersion > 0 && invoice.status !== 'draft')) {
+    const wanted = version ?? invoice.issuedVersion;
+    const [row] = await db.select().from(invoiceVersions)
+      .where(and(eq(invoiceVersions.organisationId, organisationId), eq(invoiceVersions.invoiceId, invoiceId), eq(invoiceVersions.version, wanted)));
+    if (!row) throw notFound('invoice version');
+    return { seller: organisation?.name ?? null, document: row.document };
+  }
+  const [contact] = await db.select({ id: contacts.id, name: contacts.name, email: contacts.email }).from(contacts)
+    .where(eq(contacts.id, invoice.contactId));
+  const lines = await db.select({ line: invoiceLines, itemCode: priceItems.code }).from(invoiceLines)
+    .leftJoin(priceItems, eq(priceItems.id, invoiceLines.priceItemId))
+    .where(eq(invoiceLines.invoiceId, invoice.id)).orderBy(asc(invoiceLines.position));
+  return {
+    seller: organisation?.name ?? null,
+    document: {
+      number: invoice.number,
+      version: null,
+      issueDate: invoice.issueDate,
+      dueDate: invoice.dueDate,
+      reference: invoice.reference,
+      currency: invoice.currency,
+      contact: contact ?? null,
+      lines: lines.map(({ line, itemCode }) => ({
+        position: line.position,
+        itemCode: itemCode ?? null,
+        description: line.description,
+        quantity: line.quantity,
+        unitAmountCents: line.unitAmountCents,
+        taxCode: line.taxCode,
+        lineAmountCents: line.lineAmountCents,
+        taxCents: line.taxCents,
+      })),
+      subtotalCents: invoice.subtotalCents,
+      taxCents: invoice.taxCents,
+      totalCents: invoice.totalCents,
+    },
+  };
+}
+
+// The reference the accounting system gets: the invoice's own reference, else
+// its number (the same rule as server/integrations/xero/drafts.js).
+export function pdfReference(document) {
+  return document.reference || document.number || null;
+}
+
+function addDays(date, days) {
+  const at = new Date(`${date}T00:00:00Z`);
+  at.setUTCDate(at.getUTCDate() + days);
+  return at.toISOString().slice(0, 10);
+}
+
+// The number, reference and dates the PDF shows. Each is { value } when it is
+// known, or { missing } with a short note on why it is not.
+export function pdfFields({ document: doc, facts = null }) {
+  const known = (value) => ({ value });
+  const missing = (note) => ({ missing: note });
+  if (facts?.sent) {
+    const fromCopy = (value) => (value ? known(value) : missing(`Not in Flow's copy of ${facts.system}`));
+    return {
+      number: fromCopy(facts.number),
+      reference: fromCopy(facts.reference),
+      issueDate: fromCopy(facts.issueDate),
+      dueDate: fromCopy(facts.dueDate),
+    };
+  }
+  const notIssued = missing('Set when issued');
+  const issueDate = doc.issueDate ? known(doc.issueDate) : notIssued;
+  let dueDate = doc.dueDate ? known(doc.dueDate) : notIssued;
+  // The accounting system sets the due date from the invoice date when Flow
+  // sends none (Xero: XERO_DEFAULT_DUE_DAYS).
+  if (!doc.dueDate && doc.issueDate && facts?.defaultDueDays) dueDate = known(addDays(doc.issueDate, facts.defaultDueDays));
+  const reference = pdfReference(doc);
+  return {
+    number: facts?.numberedBy === 'xero'
+      ? missing(`${facts.system} sets it when sent`)
+      : doc.number ? known(doc.number) : notIssued,
+    reference: reference ? known(reference) : notIssued,
+    issueDate,
+    dueDate,
+  };
+}
+
+export function pdfFilename(fields) {
+  const name = String(fields.number.value || 'invoice').replace(/[^A-Za-z0-9._-]+/g, '-');
+  return `${name}.pdf`;
+}
+
+const C = { ink: '#000000', body: '#333333', muted: '#666666', rule: '#bbbbbb', mark: '#e6e6e6' };
+
+function money(cents) {
+  return new Intl.NumberFormat('en-AU', { minimumFractionDigits: 2, maximumFractionDigits: 2 }).format(cents / 100);
+}
+
+function showDate(value) {
+  const [y, m, d] = String(value).slice(0, 10).split('-').map(Number);
+  return new Date(Date.UTC(y, m - 1, d)).toLocaleDateString('en-AU', { day: 'numeric', month: 'short', year: 'numeric', timeZone: 'UTC' });
+}
+
+// A4 PDF bytes for a document from invoicePdfDocument(). The layout follows
+// the accounting system's standard invoice (Xero's standard branding theme),
+// so the customer's copy looks much the same: title and customer on the
+// left, dates and numbers in the middle, the seller on the right, then the
+// lines, the totals and the due date. The payment advice slip is left out.
+export function renderInvoicePdf({ seller, document: doc, facts = null }) {
+  if (!doc || !Array.isArray(doc.lines)) throw new FlowError('invalid', 'nothing to draw');
+  const fields = pdfFields({ document: doc, facts });
+  return new Promise((resolve, reject) => {
+    const pdf = new PDFDocument({
+      size: 'A4',
+      margins: { top: 50, bottom: 50, left: 56, right: 56 },
+      info: { Title: fields.number.value ? `Invoice ${fields.number.value}` : 'Invoice', Producer: 'Flow', Creator: 'Flow' },
+    });
+    const chunks = [];
+    pdf.on('data', (chunk) => chunks.push(chunk));
+    pdf.on('end', () => resolve(Buffer.concat(chunks)));
+    pdf.on('error', reject);
+
+    const left = pdf.page.margins.left;
+    const width = pdf.page.width - left - pdf.page.margins.right;
+    const bottom = pdf.page.height - pdf.page.margins.bottom;
+    const currency = doc.currency || 'AUD';
+    const regular = 'Helvetica';
+    const bold = 'Helvetica-Bold';
+    const italic = 'Helvetica-Oblique';
+
+    const drawMark = () => {
+      pdf.save();
+      pdf.rotate(-30, { origin: [pdf.page.width / 2, pdf.page.height / 2] });
+      pdf.font(bold).fontSize(96).fillColor(C.mark)
+        .text('EXAMPLE', 0, pdf.page.height / 2 - 60, { width: pdf.page.width, align: 'center', lineBreak: false });
+      pdf.restore();
+    };
+    drawMark();
+
+    // Title, top left.
+    pdf.font(regular).fontSize(26).fillColor(C.ink).text('TAX INVOICE', left, 56);
+
+    // Three columns: customer, invoice facts, seller.
+    const top = 110;
+    const colW = width / 3;
+    pdf.font(regular).fontSize(9).fillColor(C.ink).text(doc.contact?.name ?? '', left, top, { width: colW - 12 });
+    if (doc.contact?.email) pdf.fillColor(C.body).text(doc.contact.email, { width: colW - 12 });
+    const customerEnd = pdf.y;
+
+    // A value nobody knows yet is a grey italic note, never a sample value.
+    const field = (f, show = (v) => v) => (f.value ? { text: show(f.value), font: regular, color: C.body } : { text: f.missing, font: italic, color: C.muted });
+    const rows = [
+      ['Invoice Date', field(fields.issueDate, showDate)],
+      ['Invoice Number', field(fields.number)],
+      ['Reference', field(fields.reference)],
+    ];
+    let fy = top;
+    for (const [label, shown] of rows) {
+      pdf.font(bold).fontSize(9).fillColor(C.ink).text(label, left + colW, fy, { width: colW - 12 });
+      pdf.font(shown.font).fillColor(shown.color).text(shown.text, left + colW, pdf.y, { width: colW - 12 });
+      fy = pdf.y + 8;
+    }
+    pdf.font(regular).fontSize(9).fillColor(C.ink).text(seller ?? '', left + colW * 2, top, { width: colW });
+
+    // Lines.
+    const cols = [
+      { key: 'description', label: 'Description', width: width - 300, align: 'left' },
+      { key: 'quantity', label: 'Quantity', width: 60, align: 'right' },
+      { key: 'unit', label: 'Unit Price', width: 80, align: 'right' },
+      { key: 'tax', label: 'GST', width: 70, align: 'right' },
+      { key: 'amount', label: `Amount ${currency}`, width: 90, align: 'right' },
+    ];
+    const gap = 10;
+    const tableHead = (y) => {
+      let x = left;
+      pdf.font(bold).fontSize(9).fillColor(C.ink);
+      for (const col of cols) {
+        pdf.text(col.label, x, y, { width: col.width, align: col.align });
+        x += col.width;
+      }
+      pdf.moveTo(left, y + 14).lineTo(left + width, y + 14).lineWidth(0.75).strokeColor(C.ink).stroke();
+      return y + 22;
+    };
+    let y = tableHead(Math.max(customerEnd, fy, pdf.y) + 36);
+    for (const line of doc.lines) {
+      const cells = {
+        description: line.description,
+        quantity: Number(line.quantity).toFixed(2),
+        unit: money(line.unitAmountCents),
+        tax: line.taxCode === 'GST' ? '10%' : 'GST Free',
+        amount: money(line.lineAmountCents),
+      };
+      pdf.font(regular).fontSize(9);
+      const height = Math.max(12, pdf.heightOfString(cells.description, { width: cols[0].width - gap }));
+      if (y + height > bottom - 110) {
+        pdf.addPage();
+        drawMark();
+        y = tableHead(pdf.page.margins.top);
+      }
+      let x = left;
+      for (const col of cols) {
+        pdf.font(regular).fontSize(9).fillColor(C.ink)
+          .text(cells[col.key], x, y, { width: col.key === 'description' ? col.width - gap : col.width, align: col.align });
+        x += col.width;
+      }
+      y += height + 6;
+      pdf.moveTo(left, y - 2).lineTo(left + width, y - 2).lineWidth(0.5).strokeColor(C.rule).stroke();
+      y += 4;
+    }
+
+    // Totals, right aligned under the Amount column.
+    if (y > bottom - 110) {
+      pdf.addPage();
+      drawMark();
+      y = pdf.page.margins.top;
+    }
+    y += 4;
+    const totalsX = left + width - 240;
+    const totals = [['Subtotal', doc.subtotalCents], ['TOTAL GST 10%', doc.taxCents], [`TOTAL ${currency}`, doc.totalCents]];
+    for (const [index, [label, cents]] of totals.entries()) {
+      const grand = index === totals.length - 1;
+      if (grand) {
+        pdf.moveTo(totalsX, y - 3).lineTo(left + width, y - 3).lineWidth(0.75).strokeColor(C.ink).stroke();
+        y += 3;
+      }
+      pdf.font(grand ? bold : regular).fontSize(9).fillColor(C.ink)
+        .text(label, totalsX, y, { width: 150, align: 'right' })
+        .text(money(cents), totalsX + 150, y, { width: 90, align: 'right' });
+      y += 16;
+    }
+
+    // Due date.
+    y += 24;
+    pdf.font(bold).fontSize(11).fillColor(C.ink).text('Due Date: ', left, y, { continued: true });
+    if (fields.dueDate.value) pdf.text(showDate(fields.dueDate.value));
+    else pdf.font(italic).fillColor(C.muted).text(fields.dueDate.missing);
+
+    pdf.end();
+  });
+}

package/server/core/invoices.js

@@ -98,8 +98,8 @@ export async function updateDraftInvoice(db, organisationId, invoiceId, changes)
     }
     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 });
+    // A saved change keeps the draft where it is. Flow's checks still run on
+    // it, so a change that breaks one puts the draft in Problem.
     let row = invoice;
     if (Object.keys(fields).length) {
       [row] = await tx.update(invoices).set({ ...fields, updatedAt: sql`now()` })