@arcforgelabs/flow 2026.10.38 → 2026.10.40

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/integrations/xero/settings.js

@@ -27,7 +27,8 @@ export const XERO_ENDPOINTS = Object.freeze({
 });
 
 export const XERO_CALLBACK_PATH = '/api/xero/oauth/callback';
-export const DEFAULT_XERO_SCOPE = 'offline_access accounting.contacts accounting.invoices accounting.settings.read';
+// accounting.payments.read: Flow reads payments back (ledger.js, mirror.js).
+export const DEFAULT_XERO_SCOPE = 'offline_access accounting.contacts accounting.invoices accounting.payments.read accounting.settings.read';
 export const DEFAULT_XERO_DAY_LIMIT = 1000;
 export const DEFAULT_DUE_DAYS = 30;
 export const DEFAULT_MIRROR_PAGE_SIZE = 200;

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)),
 });
 
@@ -969,16 +1001,20 @@ function xeroConnection(organisations, canChange) {
       let hint;
       let control = null;
       let stopped = false;
+      let refused = false;
       try {
         const status = await flow(`/api/xero/status?organisationId=${organisation.id}`);
         if (status.connected && status.calls?.stopped) {
           // A refused connection stopped calls (the call guard): say so, and
           // make Connect again the main button, which starts them again.
           const at = status.calls.since ? ` at ${new Date(status.calls.since).toLocaleString('en-AU', { dateStyle: 'medium', timeStyle: 'short' })}` : '';
+          // One refused resource stops only that resource, and Flow tries it
+          // again by itself: a calm note, not a stop.
           hint = status.calls.all
             ? `Xero refused Flow${at}. Flow stopped all calls.`
-            : `Xero refused Flow for ${status.calls.resources.join(', ')}${at}. Flow stopped those calls.`;
-          stopped = true;
+            : `Connected. Xero refused Flow for ${status.calls.resources.join(', ')}${at}. Other calls still work. Flow tries again by itself.`;
+          stopped = status.calls.all;
+          refused = !status.calls.all;
         } else if (status.connected) {
           const mirror = await flow(`/api/xero/mirror?organisationId=${organisation.id}`).catch(() => null);
           hint = `Connected to ${status.connection?.tenantName ?? 'Xero'}.${mirror ? ` ${mirror.counts.invoices} invoices copied.` : ''}`;
@@ -986,7 +1022,7 @@ function xeroConnection(organisations, canChange) {
           hint = 'Not connected.';
         }
         if (canChange) {
-          control = h('button', { class: `fx-btn fx-btn--sm${status.connected && !stopped ? '' : ' fx-btn--primary'}`, type: 'button', onclick: async () => {
+          control = h('button', { class: `fx-btn fx-btn--sm${status.connected && !stopped && !refused ? '' : ' fx-btn--primary'}`, type: 'button', onclick: async () => {
             try {
               const { authorizeUrl } = await flow('/api/xero/connect', { method: 'POST', body: JSON.stringify({ organisationId: organisation.id }) });
               location.assign(authorizeUrl);