@arcforgelabs/flow 2026.10.38 → 2026.10.39

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

@@ -360,3 +360,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 } = {}) {

package/server/integrations/xero/routes.js

@@ -1,6 +1,7 @@
 import { and, eq } from 'drizzle-orm';
 import express from 'express';
 import { FlowError } from '../../core/errors.js';
+import { createActionGuard } from '../call-guard.js';
 import { billingObligations, organisations } from '../../db/schema.js';
 import { lastSync, listContacts, listItems, syncCatalogue } from './catalogue.js';
 import { createXeroClient } from './client.js';
@@ -43,10 +44,25 @@ import { messagePage as themedMessagePage } from '../../ui/page.js';
 //   POST /webhooks                 Xero: change events, signed with the
 //                                  webhook key (XERO_WEBHOOK_KEY); no session
 //
+// Each POST that calls Xero waits between presses (XERO_ACTIONS, the action
+// guard): a press too soon answers 429 with the wait.
+//
 // Only an owner, with a verified owner sign-in, can connect or disconnect.
 // The callback carries no Flow session: the one-use state from /connect,
 // issued to that owner for that organisation, is what admits it.
 
+// The buttons that call Xero, and how long each waits before it runs again
+// (the action guard, call-guard.js). A send is one invoice at a time, so it
+// only runs once at a time and backs off after a failure.
+export const XERO_ACTIONS = Object.freeze({
+  sync: { cooldownMs: 5 * 60_000 },
+  recheck: { cooldownMs: 30_000 },
+  push: { cooldownMs: 0, budget: false },
+  obligationCheck: { cooldownMs: 30_000 },
+  paymentsSync: { cooldownMs: 5 * 60_000 },
+  mirror: { cooldownMs: 2 * 60_000 },
+});
+
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
 
@@ -93,10 +109,11 @@ export function callsState(status) {
   return { stopped: Boolean(status.haltedReason) || resources.length > 0, all: Boolean(status.haltedReason), resources, since };
 }
 
-export function createXeroRouter({ db, personAuth, runtime, log = console, messagePage = (options) => themedMessagePage({ ...options, defaultFamily: DEFAULT_FAMILY }) }) {
+export function createXeroRouter({ db, personAuth, runtime, log = console, buttonCooldowns = true, actions = createActionGuard({ integration: 'xero', actions: XERO_ACTIONS, off: !buttonCooldowns }), messagePage = (options) => themedMessagePage({ ...options, defaultFamily: DEFAULT_FAMILY }) }) {
   const page = (title, text, tone) => messagePage({ title, text, tone });
   const { settings } = runtime;
   const router = express.Router();
+  const act = (name, key) => actions.route(name, { key });
 
   // Xero's webhooks (webhooks.js), before the JSON parser: the signature
   // covers the raw body. Xero wants 200 with no body within 5 seconds, and
@@ -220,7 +237,7 @@ export function createXeroRouter({ db, personAuth, runtime, log = console, messa
     return res.json({ ok: true, disconnected: true, revoked });
   }));
 
-  router.post('/sync', ...manager, handle(log, async (req, res) => {
+  router.post('/sync', ...manager, act('sync'), handle(log, async (req, res) => {
     const organisationId = await requireOrganisation(db, req.body?.organisationId);
     const run = await syncCatalogue(db, runtime, organisationId, { startedBy: req.person.id });
     res.json({ ok: true, sync: run });
@@ -252,7 +269,7 @@ export function createXeroRouter({ db, personAuth, runtime, log = console, messa
   // Mark resolved: read Xero's changes (a few calls, through the call guard),
   // then check this one invoice again. The item closes only when the
   // difference is gone; otherwise it stays open with the new evidence.
-  router.post('/invoices/:invoiceId/recheck', ...manager, handle(log, async (req, res) => {
+  router.post('/invoices/:invoiceId/recheck', ...manager, act('recheck', (req) => req.params.invoiceId), handle(log, async (req, res) => {
     const organisationId = await requireOrganisation(db, req.body?.organisationId);
     const [invoiceId] = requireInvoiceIds([req.params.invoiceId], 'invoiceId');
     await mirrorXero(db, runtime, organisationId, { resources: ['invoices'] });
@@ -261,7 +278,7 @@ export function createXeroRouter({ db, personAuth, runtime, log = console, messa
     res.json({ ok: true, resolved: !status?.finding, closed: result.closed, status });
   }));
 
-  router.post('/invoices/push', ...manager, handle(log, async (req, res) => {
+  router.post('/invoices/push', ...manager, act('push'), handle(log, async (req, res) => {
     const organisationId = await requireOrganisation(db, req.body?.organisationId);
     const invoiceIds = requireInvoiceIds(req.body?.invoiceIds);
     const allowExistingReference = req.body?.allowExistingReference === undefined ? [] : requireInvoiceIds(req.body.allowExistingReference, 'allowExistingReference');
@@ -276,7 +293,7 @@ export function createXeroRouter({ db, personAuth, runtime, log = console, messa
     res.json({ ok: true, pushes: (await listPushes(db, organisationId, invoiceId)).map(describePush) });
   }));
 
-  router.post('/obligations/:obligationId/check', ...manager, handle(log, async (req, res) => {
+  router.post('/obligations/:obligationId/check', ...manager, act('obligationCheck', (req) => req.params.obligationId), handle(log, async (req, res) => {
     const organisationId = await requireOrganisation(db, req.body?.organisationId);
     const [obligationId] = requireInvoiceIds([req.params.obligationId], 'obligationId');
     const [obligation] = await db.select().from(billingObligations)
@@ -286,13 +303,13 @@ export function createXeroRouter({ db, personAuth, runtime, log = console, messa
     res.json({ ok: true, obligation: row });
   }));
 
-  router.post('/payments/sync', ...manager, handle(log, async (req, res) => {
+  router.post('/payments/sync', ...manager, act('paymentsSync'), handle(log, async (req, res) => {
     const organisationId = await requireOrganisation(db, req.body?.organisationId);
     const result = await recordXeroPayments(db, runtime, organisationId, { actor: `person:${req.person.id}` });
     res.json({ ok: true, ...result });
   }));
 
-  router.post('/mirror', ...manager, handle(log, async (req, res) => {
+  router.post('/mirror', ...manager, act('mirror'), handle(log, async (req, res) => {
     const organisationId = await requireOrganisation(db, req.body?.organisationId);
     const resources = req.body?.resources ?? MIRROR_RESOURCES;
     if (!Array.isArray(resources) || !resources.length || !resources.every((r) => MIRROR_RESOURCES.includes(r))) {

package/server/ui/app.js

@@ -13,6 +13,7 @@ import { renderInvoice, renderInvoiceList } from '/assets/ui/invoicing.js';
 import { automationSection } from '/assets/ui/automations.js';
 import { renderInvoicingSettings, sendModeSection } from '/assets/ui/invoicing-settings.js';
 import { renderPriceList } from '/assets/ui/price-list.js';
+import { renderPriceReconcile } from '/assets/ui/price-reconcile.js';
 import { lucide, renderCustomFields } from '/assets/ui/custom-fields.js';
 import { renderJobs } from '/assets/ui/jobs.js';
 import { renderReconcile } from '/assets/ui/reconcile.js';
@@ -126,10 +127,41 @@ async function flow(path, options = {}) {
     headers: { Authorization: `Bearer ${token}`, ...(options.body ? { 'Content-Type': 'application/json' } : {}) },
   });
   const body = await res.json().catch(() => ({ ok: false, error: `HTTP ${res.status}` }));
-  if (!res.ok) throw Object.assign(new Error(body.error || `HTTP ${res.status}`), { status: res.status, code: body.code, details: body.details });
+  // A button that calls Xero or Seazona waits between presses (the action
+  // guard): a press too soon says how long (retryAfterMs), and a good run
+  // says its own wait (Flow-Cooldown-Ms). holdButton shows the wait.
+  if (!res.ok) throw Object.assign(new Error(body.error || `HTTP ${res.status}`), { status: res.status, code: body.code, details: body.details, retryAfterMs: body.retryAfterMs });
+  const cooldownMs = Number(res.headers.get('Flow-Cooldown-Ms'));
+  if (cooldownMs > 0 && body && typeof body === 'object') body.cooldownMs = cooldownMs;
   return body;
 }
 
+// Keeps a button off for `ms`, with the time left on it, then puts it back.
+function holdButton(button, ms) {
+  if (!button || !(ms > 0)) return;
+  clearInterval(button.fxHold);
+  const label = button.dataset.label ?? button.textContent;
+  button.dataset.label = label;
+  const until = Date.now() + ms;
+  const draw = () => {
+    const left = Math.ceil((until - Date.now()) / 1000);
+    if (left <= 0) {
+      clearInterval(button.fxHold);
+      button.textContent = label;
+      delete button.dataset.label;
+      button.removeAttribute('title');
+      button.disabled = false;
+      return;
+    }
+    const time = left < 60 ? `${left}s` : `${Math.floor(left / 60)}:${String(left % 60).padStart(2, '0')}`;
+    button.disabled = true;
+    button.textContent = `${label} · ${time}`;
+    button.title = `Flow waits before it asks again, to protect the connected system's limits. Ready in ${time}.`;
+  };
+  draw();
+  button.fxHold = setInterval(draw, 1000);
+}
+
 // ── Shared pieces ──────────────────────────────────────────────────────────
 
 function pageHeader(title, { subtitle, actions = [] } = {}) {
@@ -204,7 +236,7 @@ const VIEWS = {
   invoices: { label: 'Invoices', icon: 'invoices', group: 'Work', render: (main, id) => (id ? renderInvoice(main, ui(), id) : renderInvoiceList(main, ui())) },
   reconcile: { label: 'Reconcile', icon: 'reconcile', group: 'Work', render: (main, id) => renderReconcile(main, ui(), id) },
   'invoicing-settings': { label: 'Invoice rules', icon: 'invoices', group: 'Settings', render: (main) => renderInvoicingSettings(main, ui()) },
-  'price-list': { label: 'Price list', icon: 'tag', group: 'Settings', render: (main) => renderPriceList(main, ui()) },
+  'price-list': { label: 'Price list', icon: 'tag', group: 'Settings', render: (main, id) => (id === 'reconcile' ? renderPriceReconcile(main, ui()) : renderPriceList(main, ui())) },
   'custom-fields': { label: 'Custom fields', icon: 'fields', group: 'Settings', render: (main) => renderCustomFields(main, ui()) },
   people: { label: 'People', icon: 'people', group: 'Settings', ownerOnly: true, render: renderPeople },
   integrations: { label: 'Integrations', icon: 'plug', group: 'Settings', ownerOnly: true, render: (main, id) => (id ? renderIntegration(main, id) : renderIntegrations(main)) },
@@ -371,7 +403,7 @@ function navigate(event) {
 // The shared pieces a view module (invoicing.js) builds with. Its `go`
 // takes a path, or a link's click event.
 const ui = () => ({
-  h, flow, toast, notice, pageHeader, dialog, me,
+  h, flow, toast, notice, pageHeader, dialog, me, holdButton,
   go: (target, options) => (typeof target === 'string' ? go(target, options) : navigate(target)),
 });