@arcforgelabs/flow 2026.10.38 → 2026.10.40

package/server/db/migrations/meta/_journal.json

@@ -141,6 +141,13 @@
       "when": 1792474607940,
       "tag": "0019_people_views",
       "breakpoints": true
+    },
+    {
+      "idx": 20,
+      "version": "7",
+      "when": 1792507133665,
+      "tag": "0020_custom_field_colours",
+      "breakpoints": true
     }
   ]
 }

package/server/db/schema.js

@@ -784,6 +784,8 @@ export const jobFields = pgTable('job_fields', {
   name: text('name').notNull(),
   type: text('type').notNull(),
   options: jsonb('options').notNull().default(sql`'[]'::jsonb`),
+  // The field's colour, one of the option colours; null is its type's colour.
+  color: text('color'),
   position: integer('position').notNull(),
   archivedAt: timestamp('archived_at', { withTimezone: true }),
   createdBy: uuid('created_by').references(() => people.id, { onDelete: 'set null' }),
@@ -794,8 +796,20 @@ export const jobFields = pgTable('job_fields', {
   unique('job_fields_org_id').on(t.organisationId, t.id),
   check('job_fields_type_valid', sql`${t.type} in ('dropdown', 'person', 'checkbox', 'date', 'number', 'text')`),
   check('job_fields_name_valid', sql`length(${t.name}) between 1 and 60`),
+  check('job_fields_color_valid', sql`${t.color} is null or ${t.color} in ('gray', 'blue', 'teal', 'green', 'amber', 'red', 'purple', 'pink')`),
 ]);
 
+// One row per organisation for Settings, Custom fields: each type group's
+// colour ({ dropdown: 'red' }; a type not named keeps its own colour), and
+// when Flow made the Assignee, so a lab that deletes it does not get it back.
+export const jobFieldSettings = pgTable('job_field_settings', {
+  organisationId: uuid('organisation_id').primaryKey().references(() => organisations.id),
+  groupColors: jsonb('group_colors').notNull().default(sql`'{}'::jsonb`),
+  assigneeMadeAt: timestamp('assignee_made_at', { withTimezone: true }),
+  updatedBy: uuid('updated_by').references(() => people.id, { onDelete: 'set null' }),
+  updatedAt: updatedAt(),
+});
+
 // A job's value for one custom field. A job is the work system's job
 // (source_system, source_job_ref), the same key the Jobs board uses, so a
 // value needs no Flow copy of the job. `value` is JSON: an option id, a person

package/server/integrations/call-guard.js

@@ -9,7 +9,10 @@ import { sql } from 'drizzle-orm';
 //   - a refused credential halts every call until a person acts (saves the
 //     settings or connects again, which calls resume());
 //   - a 401 or 403 on one resource, when the adapter's auth failures stop a
-//     resource only, stops that resource until a person acts;
+//     resource only, stops that resource; after `resourceRetryMs` one probe
+//     call may go, and a refused probe stops it again for twice as long, to
+//     at most `maxResourceRetryMs`. A good call, or a person connecting
+//     again, starts it again;
 //   - `circuitFailures` failed calls inside `circuitWindowMs` open the
 //     circuit: no call for `circuitPauseMs`, then a probe; a failed probe opens
 //     it again for twice as long, to at most `maxCircuitPauseMs`, and a
@@ -34,6 +37,8 @@ export const CALL_GUARD_POLICY = Object.freeze({
   // 'all': a 401 or 403 halts every call. 'resource': it stops only the
   // resource it came from; halt() still stops everything.
   authStops: 'all',
+  resourceRetryMs: 6 * 60 * 60_000,
+  maxResourceRetryMs: 24 * 60 * 60_000,
   telemetryRetentionMs: 35 * 24 * 60 * 60_000,
 });
 
@@ -68,12 +73,31 @@ export function circuitPauseMs(opens, policy = CALL_GUARD_POLICY) {
   return Math.min(policy.maxCircuitPauseMs, policy.circuitPauseMs * 2 ** Math.min(Math.max(0, opens), 10));
 }
 
+// The wait before the next probe of a stopped resource, after `probes`
+// refused probes.
+export function resourceRetryMs(probes, policy = CALL_GUARD_POLICY) {
+  return Math.min(policy.maxResourceRetryMs, policy.resourceRetryMs * 2 ** Math.min(Math.max(0, probes), 10));
+}
+
+// When a stopped resource may be probed again (ms). An entry written before
+// probes existed has no `retryAt`: it is due `resourceRetryMs` after `at`.
+export function resourceRetryAt(entry, policy = CALL_GUARD_POLICY) {
+  const due = entry?.retryAt ? new Date(entry.retryAt).getTime() : NaN;
+  if (Number.isFinite(due)) return due;
+  const at = entry?.at ? new Date(entry.at).getTime() : NaN;
+  return Number.isFinite(at) ? at + resourceRetryMs(0, policy) : Infinity;
+}
+
 // Why no call may go now, or null. `state` is the guard row
 // ({ haltedReason, circuitOpenUntil, stoppedResources }); `failedToday`
 // counts failed calls since the start of the UTC day.
 export function stoppedReason(state, { nowMs, failedToday, resource = null }, policy = CALL_GUARD_POLICY) {
   if (state?.haltedReason) return { reason: 'halted', retryAfterMs: null };
-  if (resource && state?.stoppedResources?.[resource]) return { reason: 'resource_stopped', retryAfterMs: null, resource };
+  const entry = resource ? state?.stoppedResources?.[resource] : null;
+  if (entry) {
+    const due = resourceRetryAt(entry, policy);
+    if (due > nowMs) return { reason: 'resource_stopped', retryAfterMs: due - nowMs, resource };
+  }
   const openUntil = state?.circuitOpenUntil ? new Date(state.circuitOpenUntil).getTime() : 0;
   if (openUntil > nowMs) return { reason: 'circuit_open', retryAfterMs: openUntil - nowMs };
   const dayStart = startOfUtcDay(nowMs);
@@ -95,7 +119,7 @@ export function circuitAfterFailure(state, { nowMs, recentFailures }, policy = C
 
 const STOP_TEXT = {
   halted: (name) => `${name} calls are stopped until a person checks the connection (it was refused)`,
-  resource_stopped: (name, resource) => `${name} calls to ${resource} are stopped until a person checks the connection (they were refused)`,
+  resource_stopped: (name, resource) => `${name} calls to ${resource} are stopped (they were refused); Flow tries again later by itself`,
   circuit_open: (name) => `${name} calls are paused after repeated failures`,
   budget_spent: (name) => `${name} calls are stopped for today: the day's failed calls are spent`,
 };
@@ -138,12 +162,14 @@ export function guardAlerts(name, status, { fix = 'Check the connection, then co
       members: [`halted:${status.haltedAt ?? ''}`],
     });
   }
+  // One refused resource is a warning, not a stop: every other call still
+  // goes, and Flow probes the resource again by itself.
   const resources = status?.stoppedResources ?? [];
   if (resources.length) {
     alerts.push({
       id: 'resources-stopped',
-      tone: 'danger',
-      title: `${name} refused Flow for ${resources.map((r) => r.resource).join(', ')}. Flow stopped those calls. ${fix}`,
+      tone: 'warn',
+      title: `${name} refused Flow for ${resources.map((r) => r.resource).join(', ')}. Other ${name} calls still work. Flow tries again by itself. To fix it now, connect again.`,
       members: resources.map((r) => `${r.resource}:${r.at ?? ''}`),
     });
   }
@@ -233,7 +259,8 @@ export function createCallGuard({
   }
 
   // Records how one call ended, and what that does to the guard. Answers
-  // what this call stopped ({ halted, resourceStopped, opened, budgetSpent }),
+  // what this call changed ({ halted, resourceStopped, resourceStillStopped,
+  // resourceResumed, opened, closed, budgetSpent }),
   // each of which was just reported once. `callId` names a call row the
   // adapter wrote when it admitted the call: that row is updated, not added.
   async function record(rawKey, { callId = null, resource = null, path = null, statusCode = null, failureKind = null, durationMs = null } = {}) {
@@ -256,22 +283,35 @@ export function createCallGuard({
       }
       const state = await readState(tx, key);
       if (!countsAsFailure({ statusCode: status, failureKind })) {
+        const result = {};
+        // A good probe: the resource is allowed again.
+        if (where && state.stoppedResources[where] && status !== null && status < 400) {
+          await tx.execute(sql`update ${T.state} set stopped_resources = stopped_resources - ${where}, updated_at = ${nowAt} where ${C.key} = ${key}`);
+          result.resourceResumed = where;
+        }
         if (state.circuitOpens > 0) {
           await tx.execute(sql`update ${T.state} set circuit_opens = 0, updated_at = ${nowAt} where ${C.key} = ${key}`);
-          return { closed: true };
+          result.closed = true;
         }
-        return {};
+        return result;
       }
       const result = {};
       const dayStart = startOfUtcDay(nowMs);
       if (await failuresSince(tx, key, dayStart) === policy.dailyFailureBudget) result.budgetSpent = { until: new Date(dayStart + DAY_MS).toISOString() };
       if (isAuthRefusal(status)) {
         if (policy.authStops === 'resource' && where) {
-          if (!state.stoppedResources[where]) {
-            await tx.execute(sql`update ${T.state} set stopped_resources = stopped_resources || ${JSON.stringify({ [where]: { statusCode: status, at: nowAt.toISOString() } })}::jsonb,
-              updated_at = ${nowAt} where ${C.key} = ${key}`);
-            result.resourceStopped = where;
-          }
+          const before = state.stoppedResources[where];
+          const probes = before ? (Number(before.probes) || 0) + 1 : 0;
+          const entry = {
+            statusCode: status,
+            at: before?.at ?? nowAt.toISOString(),
+            probes,
+            retryAt: new Date(nowMs + resourceRetryMs(probes, policy)).toISOString(),
+          };
+          await tx.execute(sql`update ${T.state} set stopped_resources = stopped_resources || ${JSON.stringify({ [where]: entry })}::jsonb,
+            updated_at = ${nowAt} where ${C.key} = ${key}`);
+          if (before) result.resourceStillStopped = { resource: where, retryAt: entry.retryAt };
+          else result.resourceStopped = where;
           return result;
         }
         if (!state.haltedReason) {
@@ -301,7 +341,9 @@ export function createCallGuard({
     if (!reports) return;
     const cause = status ? `HTTP ${status}` : failureKind;
     if (outcome.halted) log.error?.(`${tag} ${name} refused the connection (${cause}). Calls are stopped until a person checks the ${name} settings or connects again.`);
-    if (outcome.resourceStopped) log.error?.(`${tag} ${name} refused calls to ${where} (${cause}). Calls to ${where} are stopped until a person checks the connection.`);
+    if (outcome.resourceStopped) log.error?.(`${tag} ${name} refused calls to ${where} (${cause}). Calls to ${where} are stopped; Flow tries again by itself, or a person connects again.`);
+    if (outcome.resourceStillStopped) log.warn?.(`${tag} ${name} still refuses calls to ${where} (${cause}). Flow tries again at ${outcome.resourceStillStopped.retryAt}.`);
+    if (outcome.resourceResumed) log.info?.(`${tag} ${name} allows calls to ${outcome.resourceResumed} again.`);
     if (outcome.opened) {
       const line = `${tag} ${name} calls failed repeatedly (last: ${cause}${where ? ` on ${where}` : ''}). Calls pause until ${outcome.opened.until}.`;
       if (outcome.opened.opens === 1) log.error?.(line);
@@ -352,7 +394,7 @@ export function createCallGuard({
       circuitOpenUntil: openUntil > nowMs ? iso(openUntil) : null,
       haltedReason: state.haltedReason,
       haltedAt: iso(state.haltedAt),
-      stoppedResources: Object.entries(state.stoppedResources).map(([resource, entry]) => ({ resource, ...entry })),
+      stoppedResources: Object.entries(state.stoppedResources).map(([resource, entry]) => ({ resource, ...entry, retryAt: Number.isFinite(resourceRetryAt(entry, policy)) ? iso(resourceRetryAt(entry, policy)) : null })),
       failedToday: await failuresSince(db, key, startOfUtcDay(nowMs)),
       dailyFailureBudget: policy.dailyFailureBudget,
     };
@@ -360,3 +402,151 @@ export function createCallGuard({
 
   return { integration, policy, check, stoppedNow, record, halt, resume, status };
 }
+
+// ── Button presses ─────────────────────────────────────────────────────────
+//
+// The action guard: a person's button press that calls an outside system (a
+// copy, a recheck, a send) is one action. Pressed again and again, it spends
+// the provider's rate limit and can trip the call guard above. So each
+// guarded route:
+//
+//   - runs once at a time per key: a second press while it runs waits
+//     (429, `action_running`);
+//   - after a run, waits `cooldownMs` before it runs again for that key
+//     (429, `action_cooldown`);
+//   - after a failed run (a 5xx, a 429 or a stopped call), waits twice as
+//     long each time, to at most `maxCooldownMs`; a good run resets it;
+//   - shares one budget per integration: at most `budget` runs in `budgetMs`
+//     for all its actions together (429, `action_budget`). An action with
+//     `budget: false` (a send a person makes one invoice at a time) is
+//     outside it; the provider's rate limit still paces its calls.
+//
+// A 429 carries Retry-After and `retryAfterMs`, so the page shows the wait.
+// A good run says its cooldown in the `Flow-Cooldown-Ms` header. A refused
+// request (another 4xx) costs nothing: no call went. The state is in memory:
+// one Flow process serves one lab (server/rate-limit.js), and the call guard
+// above still protects every process.
+
+export const ACTION_GUARD_POLICY = Object.freeze({
+  cooldownMs: 30_000,
+  maxCooldownMs: 15 * 60_000,
+  budget: 30,
+  budgetMs: 10 * 60_000,
+});
+
+const ACTION_TEXT = {
+  action_running: () => 'This is already running. Wait for it to finish.',
+  action_cooldown: (seconds) => `Flow just did this. Try again in ${seconds} seconds.`,
+  action_budget: (seconds) => `Too many requests to this system. Try again in ${seconds} seconds.`,
+};
+
+// The wait after `failures` failed runs in a row.
+export function actionCooldownMs(failures, { cooldownMs, maxCooldownMs }) {
+  if (failures <= 0) return cooldownMs;
+  return Math.min(maxCooldownMs, Math.max(cooldownMs, 5_000) * 2 ** Math.min(failures, 10));
+}
+
+// How a response ends a run: 'ok', 'failed' (the system or the call guard
+// said no) or 'refused' (Flow refused the request; nothing was called).
+export function actionOutcome(statusCode) {
+  if (statusCode >= 500 || statusCode === 429) return 'failed';
+  if (statusCode >= 400) return 'refused';
+  return 'ok';
+}
+
+const cleanPart = (value) => String(value ?? '').replace(/[^A-Za-z0-9_.:-]+/g, '').slice(0, 80);
+
+// `integration` names the budget; `actions` maps each action name to its
+// policy ({ cooldownMs, maxCooldownMs, budget }). `route(name, { key })` answers the
+// Express middleware for one route; `key(req)` names what the cooldown
+// covers inside the organisation (an invoice id, say), or null for all of it.
+// `off: true` lets every press through (tests that press one route often).
+export function createActionGuard({ integration, actions = {}, policy: overrides = {}, off = false, now = Date.now } = {}) {
+  if (!/^[a-z][a-z0-9-]{1,31}$/.test(integration ?? '')) throw new TypeError('createActionGuard: integration must be an adapter id');
+  const policy = { ...ACTION_GUARD_POLICY, ...overrides };
+  const runs = new Map(); // key -> { running, failures, readyAt }
+  const started = []; // start times inside the budget window
+  const policyOf = (name) => ({ cooldownMs: policy.cooldownMs, maxCooldownMs: policy.maxCooldownMs, ...(actions[name] ?? {}) });
+
+  const runOf = (key) => {
+    let run = runs.get(key);
+    if (!run) runs.set(key, (run = { running: false, failures: 0, readyAt: 0 }));
+    return run;
+  };
+
+  // Why `name` may not run for `key` now, or null.
+  function waitFor(name, key) {
+    const nowMs = Number(now());
+    const run = runs.get(key);
+    if (run?.running) return { code: 'action_running', retryAfterMs: 5_000 };
+    if (run && run.readyAt > nowMs) return { code: 'action_cooldown', retryAfterMs: run.readyAt - nowMs };
+    if (policyOf(name).budget === false) return null;
+    while (started.length && started[0] <= nowMs - policy.budgetMs) started.shift();
+    if (started.length >= policy.budget) return { code: 'action_budget', retryAfterMs: started[0] + policy.budgetMs - nowMs };
+    return null;
+  }
+
+  function begin(name, key) {
+    const wait = waitFor(name, key);
+    if (wait) return wait;
+    runOf(key).running = true;
+    if (policyOf(name).budget !== false) started.push(Number(now()));
+    return null;
+  }
+
+  // `retryAfterMs`: a wait the system or the call guard asked for.
+  function end(name, key, outcome, { retryAfterMs = 0 } = {}) {
+    const run = runOf(key);
+    const rule = policyOf(name);
+    run.running = false;
+    if (outcome === 'refused') {
+      if (rule.budget !== false) started.pop();
+      return 0;
+    }
+    run.failures = outcome === 'failed' ? run.failures + 1 : 0;
+    const waitMs = Math.max(actionCooldownMs(run.failures, rule), retryAfterMs || 0);
+    run.readyAt = Number(now()) + waitMs;
+    return waitMs;
+  }
+
+  function route(name, { key = () => null } = {}) {
+    if (!actions[name]) throw new TypeError(`createActionGuard: ${name} is not a declared action`);
+    if (off) return (_req, _res, next) => next();
+    return (req, res, next) => {
+      const organisation = cleanPart(req.body?.organisationId ?? req.query?.organisationId) || 'sole';
+      const sub = key(req);
+      const runKey = [name, organisation, sub === null || sub === undefined ? '' : cleanPart(sub)].join('|');
+      const wait = begin(name, runKey);
+      if (wait) {
+        const seconds = Math.max(1, Math.ceil(wait.retryAfterMs / 1000));
+        res.set('Retry-After', String(seconds));
+        return res.status(429).json({ ok: false, code: wait.code, error: ACTION_TEXT[wait.code](seconds), retryAfterMs: wait.retryAfterMs });
+      }
+      let ended = false;
+      const finish = (statusCode) => {
+        if (ended) return 0;
+        ended = true;
+        const asked = Number(res.getHeader('Retry-After')) * 1000;
+        return end(name, runKey, actionOutcome(statusCode), { retryAfterMs: Number.isFinite(asked) ? asked : 0 });
+      };
+      // The cooldown is set as the answer is written, so a press right after
+      // it already waits, and the page learns the wait from the header.
+      const writeHead = res.writeHead;
+      res.writeHead = function writeHeadWithCooldown(statusCode, ...rest) {
+        const waitMs = finish(statusCode);
+        if (waitMs && actionOutcome(statusCode) === 'ok' && !res.headersSent) res.setHeader('Flow-Cooldown-Ms', String(waitMs));
+        return writeHead.call(this, statusCode, ...rest);
+      };
+      res.on('close', () => finish(res.headersSent ? res.statusCode : 500));
+      return next();
+    };
+  }
+
+  // Forget every run: for tests, and when a person connects again.
+  const reset = () => {
+    runs.clear();
+    started.length = 0;
+  };
+
+  return { integration, policy, actions, route, waitFor, reset };
+}

package/server/integrations/port.js

@@ -16,6 +16,7 @@ export const CAPABILITIES = Object.freeze([
   'pushInvoice', // send an issued invoice; the Flow record id is the idempotency key
   'pushInvoices', // send several issued invoices in one pass (Send all ready, server/core/sending.js)
   'checkDrafts', // the accounting system's problems with Flow drafts, from its copy; null while not connected
+  'invoiceStages', // { organisationId, invoiceIds? }: Map(invoiceId -> draft | approved | sent | void | pending) for issued invoices, from its copy
   'documentFacts', // what the customer's copy of a sent invoice says (number, reference, dates), from the system's copy in Flow; never a live call
   'sendStatus', // { connected, writesAllowed }: may Flow send invoices now?
   'pushBill', // send an approved bill; the Flow record id is the idempotency key
@@ -150,7 +151,7 @@ export function defineAdapter(adapter) {
     // integration id, its two tables, and its policy. An adapter that calls
     // an outside system declares it (docs/INTEGRATIONS.md, "Outbound calls").
     callGuard: callGuard ? Object.freeze({ ...callGuard }) : null,
-    // Optional HTTP routes: routes({ db, personAuth, log, messagePage }) returns a router
+    // Optional HTTP routes: routes({ db, personAuth, log, messagePage, buttonCooldowns }) returns a router
     // mounted at /api/<id> (registry.routes).
     routes: routes ?? null,
     // Optional: the settings an owner may enter in Settings, Integrations
@@ -317,7 +318,7 @@ export function createRegistry({ log = console, env = process.env } = {}) {
         .filter((a) => ready(a) && typeof a.capabilities[capability] === 'function');
     },
     // The adapters' own HTTP routes, each under /api/<id>. `context` is
-    // { db, personAuth, log, messagePage }. An enabled, ready adapter's router is built
+    // { db, personAuth, log, messagePage, buttonCooldowns }. An enabled, ready adapter's router is built
     // once, here; a request to an adapter that is off gets its turned-off
     // answer (503), so a turned-off adapter never reads its settings or
     // tables.

package/server/integrations/schema.js

@@ -1,5 +1,6 @@
 import { sql } from 'drizzle-orm';
 import { migrate } from 'drizzle-orm/node-postgres/migrator';
+import { withMigrationLock } from '../db/index.js';
 
 // An adapter's tables: created from its own migrations while it is enabled,
 // never dropped by turning it off. Each adapter keeps its own migration
@@ -24,12 +25,15 @@ export async function missingAdapterTables(db, adapter) {
 
 // Runs the adapter's pending migrations, then checks they created every table
 // it declares, so the declaration stays true.
+// It holds Flow's migration lock (server/db/index.js) while it does.
 export async function migrateAdapterSchema(db, adapter) {
-  await migrate(db, { migrationsFolder: adapter.schema.migrationsFolder, migrationsTable: migrationsTable(adapter) });
-  const missing = await missingAdapterTables(db, adapter);
-  if (missing.length) {
-    throw new Error(`Adapter ${adapter.id} migrations did not create ${missing.join(', ')}`);
-  }
+  await withMigrationLock(db, async (locked) => {
+    await migrate(locked, { migrationsFolder: adapter.schema.migrationsFolder, migrationsTable: migrationsTable(adapter) });
+    const missing = await missingAdapterTables(locked, adapter);
+    if (missing.length) {
+      throw new Error(`Adapter ${adapter.id} migrations did not create ${missing.join(', ')}`);
+    }
+  });
 }
 
 export function isMissingTable(error) {

package/server/integrations/seazona/settings.js

@@ -77,15 +77,19 @@ export function orderUrlTemplate(value) {
 }
 
 // The link to one order for "Open in Seazona": the order's own page when the
-// installation set SEAZONA_ORDER_URL, else the home page of the lab's
-// Seazona web app when the API address names it (https://{lab}.seazonaapi.net),
-// else null. `exact` is true only for the order's own page.
+// installation set SEAZONA_ORDER_URL; else, when the API address names the
+// lab (https://{lab}.seazonaapi.net), its order page
+// (https://{lab}.seazona.net/OrderEdit.aspx?id={order id}), or its home page
+// with no order id; else null. `exact` is true only for the order's own page.
 export function orderLink(settings, { sourceJobRef } = {}) {
   const template = settings?.orderUrlTemplate ?? null;
   if (template && sourceJobRef) return { url: template.replaceAll('{ref}', encodeURIComponent(sourceJobRef)), exact: true };
   const host = settings?.baseUrl ? new URL(settings.baseUrl).hostname : '';
   const lab = /^([a-z0-9-]+)\.seazonaapi\.net$/i.exec(host)?.[1];
-  return lab ? { url: `https://${lab}.seazona.net/`, exact: false } : null;
+  if (!lab) return null;
+  // Seazona's own order screen takes the order id (a GUID) Flow syncs.
+  if (new RegExp(`^${ORDER_ID.source}$`, 'i').test(sourceJobRef ?? '')) return { url: `https://${lab}.seazona.net/OrderEdit.aspx?id=${encodeURIComponent(sourceJobRef)}`, exact: true };
+  return { url: `https://${lab}.seazona.net/`, exact: false };
 }
 
 // Returns the resolved settings, or throws SeazonaSettingsError. `mode` is

package/server/integrations/xero/drafts.js

@@ -131,7 +131,7 @@ export function buildDraft(document, { settings, contact, items, sendMode = 'acc
     };
     if (line.itemCode) {
       if (items.has(line.itemCode)) out.ItemCode = line.itemCode;
-      else problems.push(problem('xero_item_missing', `Line ${line.position}: item ${line.itemCode} is not in Xero. Add it in Xero, then sync.`, { itemCode: line.itemCode }));
+      else problems.push(problem('xero_item_missing', `Line ${line.position}: item ${line.itemCode} is not in Xero. Add it in Xero, then sync.`, { itemCode: line.itemCode, short: `${line.itemCode} not in Xero` }));
     } else if (line.accountCode) {
       // A line with no item books to its own account, such as a surcharge.
       out.AccountCode = line.accountCode;
@@ -289,8 +289,8 @@ async function previewOne(db, runtime, organisationId, invoiceId) {
   if (invoice.status === 'void') problems.push(problem('invoice_void', 'This invoice is void. Flow does not send it to Xero.'));
   if (invoice.status === 'draft') problems.push(problem('invoice_not_issued', 'This invoice is a draft. Issue it, then send it to Xero.'));
   const match = await matchContact(db, organisationId, document.contact.name);
-  if (match.state === 'missing') problems.push(problem('xero_contact_missing', `No Xero contact is named "${document.contact.name}". Add it in Xero (Flow never creates Xero contacts), then sync.`));
-  if (match.state === 'ambiguous') problems.push(problem('xero_contact_ambiguous', `More than one Xero contact is named "${document.contact.name}". Merge or rename them in Xero, then sync.`));
+  if (match.state === 'missing') problems.push(problem('xero_contact_missing', `No Xero contact is named "${document.contact.name}". Add it in Xero (Flow never creates Xero contacts), then sync.`, { short: 'Client not in Xero' }));
+  if (match.state === 'ambiguous') problems.push(problem('xero_contact_ambiguous', `More than one Xero contact is named "${document.contact.name}". Merge or rename them in Xero, then sync.`, { short: 'Client twice in Xero' }));
   const items = await itemsByCode(db, organisationId, document.lines.map((l) => l.itemCode));
   const sendMode = await sendModeFor(db, organisationId, invoice.contactId);
   const { draft, problems: lineProblems } = buildDraft(document, { settings: runtime.settings, contact: match.contact, items, sendMode });
@@ -389,7 +389,7 @@ export async function checkDrafts(db, runtime, { organisationId, invoiceIds }) {
     for (const preview of invoices) {
       found.set(preview.invoiceId, preview.problems
         .filter((p) => p.blocking !== false && p.code !== 'invoice_not_issued')
-        .map(({ code, message }) => ({ code, message })));
+        .map(({ code, message, short }) => ({ code, message, ...(short ? { short } : {}) })));
     }
   }
   return found;

package/server/integrations/xero/index.js

@@ -6,6 +6,7 @@ import { readConnection } from './connections.js';
 import { createImportWorker } from './import.js';
 import { readPayments, xeroLiveCheck } from './ledger.js';
 import { findInvoices, listCustomers, listPriceItems, mirrorState } from './lookup.js';
+import { invoiceStages } from './reconcile.js';
 import { createXeroRouter } from './routes.js';
 import { createXeroRuntime, requireXeroSettings, XERO_CALL_GUARD } from './runtime.js';
 import { writesAllowed } from './settings.js';
@@ -116,6 +117,9 @@ export function createXeroAdapter({ runtime: given = null } = {}) {
       pushInvoice: ({ organisationId, invoiceId, pushedBy = null }) => pushInvoice(database, current(), { organisationId, invoiceId, pushedBy }),
       // Several issued invoices, in batches of MAX_BATCH (drafts.js).
       pushInvoices: ({ organisationId, invoiceIds, pushedBy = null }) => pushInvoices(database, current(), { organisationId, invoiceIds, pushedBy }),
+      // The Invoices page tab of each issued invoice (reconcile.js), from
+      // Flow's copy of Xero: draft, approved, sent, void or pending.
+      invoiceStages: ({ organisationId, invoiceIds = null }) => invoiceStages(database, current(), organisationId, invoiceIds),
       // What would stop each Flow draft in Xero, from Flow's copy (no calls).
       checkDrafts: ({ organisationId, invoiceIds }) => checkDrafts(database, current(), { organisationId, invoiceIds }),
       sendStatus: async ({ organisationId }) => {
@@ -142,7 +146,7 @@ export function createXeroAdapter({ runtime: given = null } = {}) {
       // Xero items, from Flow's copy, for the price list (lookup.js).
       listPriceItems: ({ organisationId }) => listPriceItems(database, organisationId, { taxTypes: current().settings.taxTypes }),
     },
-    routes: ({ db, personAuth, log, messagePage }) => createXeroRouter({ db, personAuth, runtime: current(), log, messagePage }),
+    routes: ({ db, personAuth, log, messagePage, buttonCooldowns }) => createXeroRouter({ db, personAuth, runtime: current(), log, messagePage, buttonCooldowns }),
   };
 }
 

package/server/integrations/xero/migrations/0009_xero_sent_to_contact.sql

@@ -0,0 +1,3 @@
+-- Whether Xero sent the invoice to the customer (Xero's SentToContact), for
+-- the Invoices page Sent tab. Null until the copy reads the invoice again.
+ALTER TABLE "xero_invoices" ADD COLUMN IF NOT EXISTS "sent_to_contact" boolean;

package/server/integrations/xero/migrations/meta/_journal.json

@@ -64,6 +64,13 @@
       "when": 1792510000000,
       "tag": "0008_xero_invoice_links",
       "breakpoints": true
+    },
+    {
+      "idx": 9,
+      "version": "7",
+      "when": 1792520000000,
+      "tag": "0009_xero_sent_to_contact",
+      "breakpoints": true
     }
   ]
 }

package/server/integrations/xero/mirror.js

@@ -77,6 +77,7 @@ export function mapInvoice(invoice, { keepReference = false } = {}) {
     amountDueCents: toCents(invoice.AmountDue),
     amountPaidCents: toCents(invoice.AmountPaid),
     amountCreditedCents: toCents(invoice.AmountCredited),
+    sentToContact: typeof invoice.SentToContact === 'boolean' ? invoice.SentToContact : null,
     lines: mapLines(invoice.LineItems, keepReference),
     xeroUpdatedAt: parseXeroDate(invoice.UpdatedDateUTC),
   };
@@ -135,17 +136,17 @@ const UPSERT = {
   invoices: (org, r, hash) => sql`
     insert into xero_invoices (organisation_id, xero_invoice_id, type, invoice_number, reference, xero_contact_id, status,
       issued_on, due_on, fully_paid_on, currency, subtotal_cents, tax_cents, total_cents, amount_due_cents,
-      amount_paid_cents, amount_credited_cents, lines, xero_updated_at, record_hash)
+      amount_paid_cents, amount_credited_cents, sent_to_contact, lines, xero_updated_at, record_hash)
     values (${org}, ${r.xeroInvoiceId}, ${r.type}, ${r.invoiceNumber}, ${r.reference}, ${r.xeroContactId}, ${r.status},
       ${r.issuedOn}, ${r.dueOn}, ${r.fullyPaidOn}, ${r.currency}, ${r.subtotalCents}, ${r.taxCents}, ${r.totalCents},
-      ${r.amountDueCents}, ${r.amountPaidCents}, ${r.amountCreditedCents}, ${json(r.lines)}::jsonb, ${r.xeroUpdatedAt}, ${hash})
+      ${r.amountDueCents}, ${r.amountPaidCents}, ${r.amountCreditedCents}, ${r.sentToContact ?? null}, ${json(r.lines)}::jsonb, ${r.xeroUpdatedAt}, ${hash})
     on conflict (organisation_id, xero_invoice_id) do update set
       type = excluded.type, invoice_number = excluded.invoice_number, reference = excluded.reference,
       xero_contact_id = excluded.xero_contact_id, status = excluded.status, issued_on = excluded.issued_on,
       due_on = excluded.due_on, fully_paid_on = excluded.fully_paid_on, currency = excluded.currency,
       subtotal_cents = excluded.subtotal_cents, tax_cents = excluded.tax_cents, total_cents = excluded.total_cents,
       amount_due_cents = excluded.amount_due_cents, amount_paid_cents = excluded.amount_paid_cents,
-      amount_credited_cents = excluded.amount_credited_cents, lines = excluded.lines,
+      amount_credited_cents = excluded.amount_credited_cents, sent_to_contact = excluded.sent_to_contact, lines = excluded.lines,
       xero_updated_at = excluded.xero_updated_at, record_hash = excluded.record_hash, last_changed_at = now()
     where xero_invoices.record_hash is distinct from excluded.record_hash
     returning (xmax = 0) as inserted`,

package/server/integrations/xero/reconcile.js

@@ -96,7 +96,7 @@ export async function accountingStatus(db, runtime, organisationId, invoiceIds =
       p.version as sent_version, p.state as push_state, p.request_body, p.xero_invoice_id, p.xero_invoice_number,
       v.document, l.xero_invoice_id as linked_xero_id, l.matched_by as linked_by,
       x.status as x_status, x.invoice_number as x_number, x.xero_contact_id, x.subtotal_cents, x.tax_cents,
-      x.total_cents as x_total_cents, x.amount_paid_cents, x.amount_due_cents, x.lines, x.issued_on
+      x.total_cents as x_total_cents, x.amount_paid_cents, x.amount_due_cents, x.sent_to_contact, x.lines, x.issued_on
     from invoices i
     left join lateral (
       select * from xero_invoice_pushes
@@ -131,6 +131,7 @@ export async function accountingStatus(db, runtime, organisationId, invoiceIds =
       status: r.x_status,
       totalCents: num(r.x_total_cents),
       amountDueCents: num(r.amount_due_cents),
+      sentToContact: r.sent_to_contact ?? null,
       url: `${web}/AccountsReceivable/View.aspx?InvoiceID=${encodeURIComponent(xeroInvoiceId)}`,
     } : null;
     const status = {
@@ -153,6 +154,29 @@ export async function accountingStatus(db, runtime, organisationId, invoiceIds =
   return out;
 }
 
+// The Invoices page tab of each issued Flow invoice, from Flow's copy of
+// Xero (no calls): draft (on its way, or a Xero DRAFT), approved (AUTHORISED,
+// not sent to the customer yet), sent (Xero sent it, or it is part or fully
+// paid), void (voided or deleted in Xero), or pending (out of sync: a person
+// looks). Answers Map(invoiceId -> stage).
+export async function invoiceStages(db, runtime, organisationId, invoiceIds = null) {
+  const statuses = await accountingStatus(db, runtime, organisationId, invoiceIds);
+  const out = new Map();
+  for (const status of statuses.values()) {
+    if (status.flowStatus !== 'issued') continue;
+    out.set(status.invoiceId, stageOf(status));
+  }
+  return out;
+}
+
+export function stageOf(status) {
+  if (status.finding) return 'pending';
+  if (['part_paid', 'paid'].includes(status.state)) return 'sent';
+  if (status.state === 'approved') return status.xero?.sentToContact ? 'sent' : 'approved';
+  if (['voided', 'deleted'].includes(status.state)) return 'void';
+  return 'draft';
+}
+
 // Opens or refreshes one review item for each finding, and closes the item of
 // an invoice whose finding went away. Answers counts.
 export async function checkSentInvoices(db, runtime, organisationId, { invoiceIds = null } = {}) {