@arcforgelabs/flow 2026.10.45 → 2026.10.46

package/server/ui/page.js

@@ -71,20 +71,125 @@ ${body}
 `;
 }
 
-/** A one-message page, such as the end of connecting Xero. */
-export function messagePage({ title, text, defaultFamily, tone = 'info' }) {
+// Mode labels on the connected callback card (issue #211). Sandbox is the
+// Demo Company; replay is for development and CI.
+const MODE_LABELS = Object.freeze({ live: 'Live', sandbox: 'Demo', replay: 'Replay' });
+
+function modeLabel(mode) {
+  if (mode == null || mode === '') return '';
+  const key = String(mode).toLowerCase();
+  return MODE_LABELS[key] ?? String(mode).replace(/^./, (c) => c.toUpperCase());
+}
+
+function lucideIcon(name) {
+  return `<span class="fx-lucide" style="--icon: url(/assets/icons/${escapeHtml(name)}.svg)" aria-hidden="true"></span>`;
+}
+
+/**
+ * A one-message page, such as the end of connecting an integration.
+ *
+ * Optional `integration` ({ name, logo }) shows Flow's mark beside the
+ * maker's logo. Optional `organisation` and `mode` become a status line.
+ * On success, `autoReturnSeconds` (default 5 when tone is success and an
+ * integration is named) starts a polite countdown and returns to Flow; set
+ * it to 0 or false to keep the person on the page. Failure never auto-returns.
+ */
+export function messagePage({
+  title,
+  text,
+  defaultFamily,
+  tone = 'info',
+  integration = null,
+  organisation = null,
+  mode = null,
+  autoReturnSeconds,
+  href = '/',
+}) {
+  const safeHref = typeof href === 'string' && href.startsWith('/') && !href.startsWith('//') ? href : '/';
+  const logo = integration?.logo && /^[a-z0-9][a-z0-9._-]*\.svg$/i.test(integration.logo) ? integration.logo : null;
+  const integrationName = integration?.name ? String(integration.name) : '';
+  const showMarks = Boolean(logo || integrationName);
+  const resultIcon = tone === 'success' ? 'check-circle' : tone === 'danger' ? 'x-circle' : null;
+  const org = organisation != null && String(organisation).trim() ? String(organisation).trim() : '';
+  const modeText = modeLabel(mode);
+  const statusParts = [org, modeText].filter(Boolean);
+  const returnSeconds = autoReturnSeconds === false || autoReturnSeconds === 0
+    ? 0
+    : tone === 'success' && showMarks
+      ? Math.max(1, Math.min(30, Number(autoReturnSeconds) || 5))
+      : 0;
+
+  const marks = showMarks
+    ? `<div class="fx-message__marks" aria-hidden="true">
+      <span class="fx-logo fx-logo--lg fx-message__flow">${FLOW_MARK}</span>
+      <span class="fx-message__plus">+</span>
+      <span class="fx-logo fx-logo--lg">${logo
+        ? `<img src="/assets/ui/logos/${escapeHtml(logo)}" alt="">`
+        : lucideIcon('plug')}</span>
+      ${resultIcon ? `<span class="fx-message__result" data-tone="${escapeHtml(tone)}">${lucideIcon(resultIcon)}</span>` : ''}
+    </div>`
+    : resultIcon
+      ? `<div class="fx-message__marks fx-message__marks--solo" aria-hidden="true">
+      <span class="fx-message__result" data-tone="${escapeHtml(tone)}">${lucideIcon(resultIcon)}</span>
+    </div>`
+      : '';
+
+  const status = statusParts.length
+    ? `<p class="fx-message__status"><span class="fx-status" data-tone="${escapeHtml(tone === 'danger' ? 'danger' : 'success')}">${escapeHtml(statusParts.join(' · '))}</span></p>`
+    : '';
+
+  const returnLine = returnSeconds
+    ? `<p class="fx-message__return" hidden aria-live="polite" data-return-after="${returnSeconds}" data-return-href="${escapeHtml(safeHref)}"></p>`
+    : '';
+
+  // Clean the OAuth query from the address. On success only, count down and
+  // return to Flow. Without JavaScript the Back button is enough.
+  const cleanScript = showMarks || returnSeconds
+    ? `<script>try{history.replaceState(null,'',location.pathname)}catch(e){}</script>`
+    : '';
+  const returnScript = returnSeconds
+    ? `<script>
+(function () {
+  var el = document.querySelector('[data-return-after]');
+  if (!el) return;
+  var left = Number(el.getAttribute('data-return-after')) || 0;
+  var href = el.getAttribute('data-return-href') || '/';
+  if (left < 1) return;
+  el.hidden = false;
+  function say(n) {
+    el.textContent = n === 1 ? 'Going back to Flow in 1 second' : 'Going back to Flow in ' + n + ' seconds';
+  }
+  say(left);
+  var timer = setInterval(function () {
+    left -= 1;
+    if (left <= 0) {
+      clearInterval(timer);
+      location.assign(href);
+      return;
+    }
+    say(left);
+  }, 1000);
+})();
+</script>`
+    : '';
+
   return renderPage({
     title,
     defaultFamily,
     bodyClass: 'fx-centre',
     scripts: ['/assets/ui/appearance.js'],
     body: `<main class="fx-message">
-  <a class="fx-brand" href="/">${FLOW_MARK}<span>Flow</span></a>
+  <a class="fx-brand" href="${escapeHtml(safeHref)}">${FLOW_MARK}<span>Flow</span></a>
   <section class="fx-card fx-message__card" data-tone="${escapeHtml(tone)}">
+    ${marks}
     <h1 class="fx-title">${escapeHtml(title)}</h1>
+    ${status}
     <p>${escapeHtml(text)}</p>
-    <a class="fx-btn" href="/">Back to Flow</a>
+    ${returnLine}
+    <a class="fx-btn" href="${escapeHtml(safeHref)}">Back to Flow</a>
   </section>
-</main>`,
+</main>
+${cleanScript}
+${returnScript}`,
   });
 }

package/server/ui/reconcile.js

@@ -204,7 +204,7 @@ async function renderList(main, ui) {
   const host = h('div', { class: 'fx-rec' }, h('div', { class: 'fx-skeleton' }));
   const bulk = bulkBar(ui, { label: 'Ticked jobs' });
   const frame = listFrame(main, host);
-  main.append(...listHead('Reconcile', { views: views.element, start: controls, end: find.element }).nodes, frame.element, bulk.element);
+  main.append(...listHead('Reconcile', { views: views.element, controls, end: find.element }).nodes, frame.element, bulk.element);
 
   // The Filter chip: the same panel as on Jobs (view-bar.js). Job rows also
   // have the lab's custom fields.

package/server/ui/routes.js

@@ -21,7 +21,7 @@ const themeDir = join(here, '..', 'theme');
 const logoDir = join(here, 'logos');
 const LOGO_FILES = new Set(['xero.svg', 'seazona.svg', 'sentry.svg']);
 const THEME_FILES = new Set(['themes.js', 'color-contrast.js', 'openclaw-palettes.js', 'font-families.js']);
-export const UI_FILES = new Set(['flow.css', 'appearance.js', 'clerk-appearance.js', 'app.js', 'invoicing.js', 'invoice-notes.js', 'job-change.js', 'sidecar.js', 'invoicing-settings.js', 'automations.js', 'invoice-rules.js', 'line-mappings.js', 'price-list.js', 'price-match.js', 'price-reconcile.js', 'custom-fields.js', 'jobs.js', 'job-board.js', 'reconcile.js', 'xero-import.js', 'job-view.js', 'list-views.js', 'saved-views.js', 'monitoring.js', 'search.js', 'alerts.js', 'bulk-bar.js', 'view-bar.js', 'tip.js', 'kit.js', 'columns.js', 'person.js', 'pager.js', 'flow-mark.svg']);
+export const UI_FILES = new Set(['flow.css', 'appearance.js', 'clerk-appearance.js', 'app.js', 'invoicing.js', 'invoice-notes.js', 'job-change.js', 'sidecar.js', 'invoicing-settings.js', 'automations.js', 'invoice-rules.js', 'line-mappings.js', 'price-list.js', 'price-match.js', 'price-reconcile.js', 'custom-fields.js', 'jobs.js', 'job-board.js', 'reconcile.js', 'xero-import.js', 'xero-usage.js', 'xero-usage-model.js', 'job-view.js', 'list-views.js', 'saved-views.js', 'monitoring.js', 'search.js', 'alerts.js', 'bulk-bar.js', 'view-bar.js', 'tip.js', 'kit.js', 'columns.js', 'person.js', 'pager.js', 'flow-mark.svg']);
 const iconDir = join(dirname(require.resolve('lucide-static/package.json')), 'icons');
 const ICON_FILE = /^[a-z0-9]+(?:-[a-z0-9]+)*\.svg$/;
 const MAX_AGE = '1h';

package/server/ui/saved-views.js

@@ -1,5 +1,5 @@
-// Saved views: the row of named view tabs over a list (Jobs, Invoices,
-// Reconcile), as ClickUp's. A view keeps the page's Group, Sort, Filter and
+// Saved views: the named view tabs of a list (Jobs, Invoices, Reconcile),
+// as ClickUp's, in the toolbar beside Group, Sort and Filter (listHead). A view keeps the page's Group, Sort, Filter and
 // Columns under a name. A tab shows it; "Save" and "Revert" show when the
 // page no longer matches the chosen tab; "+ View" saves the page as a new
 // view. Each tab's ⋯ menu has "Set as my default" (the view that opens
@@ -7,7 +7,7 @@
 // the person's account (PUT /api/me/saved-views/:page, list-views.js).
 //
 //   const views = savedViews(ui, { page, current, apply });
-//   views.element   the tab row, for the page to place
+//   views.element   the tabs, for listHead's `views`
 //   views.opening() the view to open on, or null: the default view on the
 //                   first visit in this browser tab, else the page's own
 //   views.draw()    call after any change to the page's view
@@ -117,7 +117,7 @@ export function savedViews(ui, { page, current, apply }) {
     });
     element.replaceChildren(...[
       ...tabs,
-      saved.list.length < MAX_SAVED_VIEWS ? h('button', { type: 'button', class: 'fx-views__add', onclick: addView }, lucide(h, 'plus'), 'View') : null,
+      saved.list.length < MAX_SAVED_VIEWS ? h('button', { type: 'button', class: 'fx-views__add', title: 'Save as a view', onclick: addView }, lucide(h, 'plus'), 'View') : null,
       changed ? h('span', { class: 'fx-views__end' },
         h('button', { type: 'button', class: 'fx-btn fx-btn--ghost fx-btn--sm', onclick: () => { apply(view.view); draw(); } }, 'Revert'),
         h('button', { type: 'button', class: 'fx-btn fx-btn--primary fx-btn--sm', onclick: () => store({ ...saved, list: saved.list.map((v) => (v.id === view.id ? { ...v, view: current() } : v)) }) }, 'Save')) : null,

package/server/ui/xero-usage-model.js

@@ -0,0 +1,106 @@
+// Pure numbers for the Xero usage card. No DOM and no database: the server
+// fills it from counters Flow already keeps, and the card draws it.
+
+export const USAGE_LANES = Object.freeze(['writes', 'sync', 'reads', 'other']);
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+export function startOfUtcDay(ms) {
+  const date = new Date(ms);
+  return Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate());
+}
+
+// 1,000 a day is Xero's Starter plan; 5,000 is Core and above (docs/XERO.md).
+export function appTier(dayLimit) {
+  if (!Number.isFinite(dayLimit) || dayLimit <= 0) return null;
+  return dayLimit >= 5000 ? 'Core' : 'Starter';
+}
+
+// How old a time is, as a short chip: "2 min", "3 h", "4 d".
+export function formatAge(at, now) {
+  if (!at) return null;
+  const ms = Math.max(0, now - new Date(at).getTime());
+  const minutes = Math.round(ms / 60_000);
+  if (minutes < 1) return 'now';
+  if (minutes < 60) return `${minutes} min`;
+  const hours = Math.round(ms / 3_600_000);
+  if (hours < 24) return `${hours} h`;
+  return `${Math.round(ms / DAY_MS)} d`;
+}
+
+export function formatWhen(at) {
+  if (!at) return null;
+  return new Date(at).toLocaleString('en-AU', { day: 'numeric', month: 'short', hour: '2-digit', minute: '2-digit' });
+}
+
+function emptyLanes() {
+  return { writes: 0, sync: 0, reads: 0, other: 0 };
+}
+
+function addLane(target, lane, n) {
+  if (USAGE_LANES.includes(lane)) target[lane] += n;
+}
+
+// `hourRows` are { hour, lane, n } for today. `dayRows` are { day, n } over
+// the last 7 UTC days. `limitRows` are 429s { at, problem, lane, task }.
+export function assembleUsage({
+  hourRows = [],
+  dayRows = [],
+  taskRows = [],
+  limitRows = [],
+  governor,
+  warningFraction,
+  now = Date.now(),
+}) {
+  const dayStart = startOfUtcDay(now);
+  const hours = Array.from({ length: 24 }, (_, index) => ({
+    hour: new Date(dayStart + index * 3_600_000).toISOString(),
+    ...emptyLanes(),
+  }));
+  const lanes = emptyLanes();
+  for (const row of hourRows) {
+    const index = Math.round((Date.parse(row.hour) - dayStart) / 3_600_000);
+    const n = Number(row.n) || 0;
+    if (index >= 0 && index < 24) addLane(hours[index], row.lane, n);
+    addLane(lanes, row.lane, n);
+  }
+  const logged = USAGE_LANES.reduce((sum, lane) => sum + lanes[lane], 0);
+  const dayLimit = Number(governor?.dayLimit) || 0;
+  const used = Math.max(Number(governor?.dayCount) || 0, logged);
+  const observed = governor?.observedDayRemaining;
+  const left = Number.isFinite(observed) ? observed : Math.max(0, dayLimit - used);
+  const fraction = Number.isFinite(warningFraction) ? warningFraction : 0.7;
+  const line = dayLimit * fraction;
+
+  const byDay = new Map(dayRows.map((row) => [String(row.day).slice(0, 10), Number(row.n) || 0]));
+  const weekStart = dayStart - 6 * DAY_MS;
+  let warnedDays = 0;
+  const days = Array.from({ length: 7 }, (_, index) => {
+    const day = new Date(weekStart + index * DAY_MS).toISOString().slice(0, 10);
+    const total = byDay.get(day) ?? 0;
+    const warning = dayLimit > 0 && total >= line;
+    if (warning) warnedDays += 1;
+    return { day, total, warning, over: dayLimit > 0 && total >= dayLimit };
+  });
+
+  return {
+    used,
+    dayLimit,
+    left,
+    dayLimitSource: governor?.dayLimitSource ?? 'setting',
+    warningFraction: fraction,
+    warning: dayLimit > 0 && used >= line,
+    tier: appTier(dayLimit),
+    lanes,
+    hours,
+    days,
+    warnedDays,
+    suggestTier: warnedDays >= 2,
+    tasks: taskRows.map((row) => ({ task: row.task, calls: Number(row.n) || 0 })),
+    limited: limitRows.map((row) => ({
+      at: row.at ? new Date(row.at).toISOString() : null,
+      problem: row.problem || null,
+      lane: USAGE_LANES.includes(row.lane) ? row.lane : null,
+      task: row.task || null,
+    })),
+  };
+}

package/server/ui/xero-usage.js

@@ -0,0 +1,133 @@
+// The Xero card's usage picture (Integrations › Xero). Three levels: the ring
+// and chips always, today open, the week closed. Numbers come from
+// GET /api/xero/status. No sentence is needed to read the first level.
+import { h, notice } from '/assets/ui/kit.js';
+import { svg } from '/assets/ui/view-bar.js';
+import { USAGE_LANES, formatAge, formatWhen } from '/assets/ui/xero-usage-model.js';
+
+const LANE_LABEL = { writes: 'Writes', sync: 'Sync', reads: 'Reads', other: 'Other' };
+const num = new Intl.NumberFormat('en-AU');
+const HOUR = 60 * 60 * 1000;
+
+function lanePart(count, whole) {
+  if (!whole) return '0%';
+  return `${(count / whole) * 100}%`;
+}
+
+function ring(usage) {
+  const pct = usage.dayLimit > 0 ? Math.min(100, Math.round((usage.used / usage.dayLimit) * 1000) / 10) : 0;
+  const label = `${num.format(usage.used)} of ${num.format(usage.dayLimit)}`;
+  return h('div', { class: 'fx-xu-ring', role: 'img', 'aria-label': label },
+    svg(`<svg viewBox="0 0 36 36" aria-hidden="true"><circle class="fx-xu-ring__track" cx="18" cy="18" r="15.5" pathLength="100"/><circle class="fx-xu-ring__used" cx="18" cy="18" r="15.5" pathLength="100" stroke-dasharray="${pct} 100"/></svg>`),
+    h('div', { class: 'fx-xu-ring__label' },
+      h('span', { class: 'fx-xu-ring__num' }, num.format(usage.used)),
+      h('span', { class: 'fx-xu-ring__of' }, num.format(usage.dayLimit))));
+}
+
+function chips(status, now) {
+  const stopped = status.calls?.stopped;
+  const connection = !status.connected
+    ? ['mute', 'Off']
+    : stopped && status.calls.all
+      ? ['danger', 'Stopped']
+      : stopped
+        ? ['warn', 'Limited']
+        : ['success', 'Connected'];
+  const age = formatAge(status.freshness?.copyAt, now);
+  return h('div', { class: 'fx-xu__chips' },
+    h('span', { class: 'fx-status', 'data-tone': connection[0] }, connection[1]),
+    status.usage.tier ? h('span', { class: 'fx-chip fx-chip--static' }, status.usage.tier) : null,
+    h('span', { class: 'fx-chip fx-chip--static', title: 'Copy', 'aria-label': age ? `Copy ${age}` : 'Copy' }, age ?? '—'));
+}
+
+function legend() {
+  return h('div', { class: 'fx-xu-legend' }, USAGE_LANES.map((lane) => h('span', {},
+    h('i', { class: 'fx-xu-lane', 'data-lane': lane, 'aria-hidden': 'true' }),
+    LANE_LABEL[lane])));
+}
+
+function hourChart(usage) {
+  const peak = Math.max(1, ...usage.hours.map((hour) => USAGE_LANES.reduce((sum, lane) => sum + hour[lane], 0)));
+  return h('div', { class: 'fx-xu-hours', role: 'img', 'aria-label': 'Calls by hour' }, usage.hours.map((hour) => {
+    const total = USAGE_LANES.reduce((sum, lane) => sum + hour[lane], 0);
+    const stack = h('span', { class: 'fx-xu-hour__stack', style: { '--h': `${(total / peak) * 100}%` } },
+      USAGE_LANES.map((lane) => (hour[lane]
+        ? h('i', { class: 'fx-xu-lane', 'data-lane': lane, style: { '--part': lanePart(hour[lane], total) } })
+        : null)));
+    const when = new Date(hour.hour);
+    stack.title = `${when.getUTCHours()}:00 · ${total}`;
+    return h('span', { class: 'fx-xu-hour' }, stack);
+  }));
+}
+
+function budgetBar(usage) {
+  return h('div', { class: 'fx-xu-budget', role: 'img', 'aria-label': 'Budget by lane' },
+    USAGE_LANES.map((lane) => h('i', {
+      class: 'fx-xu-lane',
+      'data-lane': lane,
+      style: { '--part': lanePart(usage.lanes[lane], usage.dayLimit) },
+      title: `${LANE_LABEL[lane]} ${num.format(usage.lanes[lane])}`,
+    })));
+}
+
+function dot(label, tone, title) {
+  return h('span', { class: 'fx-xu-dot', 'data-tone': tone, title: title || label }, label);
+}
+
+function freshnessDots(freshness, limited, now) {
+  const tone = (at, freshFor) => {
+    if (!at) return 'mute';
+    return now - new Date(at).getTime() <= freshFor ? 'success' : 'warn';
+  };
+  const recentLimit = limited.some((row) => row.at && now - new Date(row.at).getTime() <= 24 * HOUR);
+  return h('div', { class: 'fx-xu-dots' },
+    dot('Webhook', tone(freshness?.webhookAt, 24 * HOUR), formatWhen(freshness?.webhookAt) ?? 'Webhook'),
+    dot('Poll', tone(freshness?.pollAt, 2 * HOUR), formatWhen(freshness?.pollAt) ?? 'Poll'),
+    dot('Nightly', tone(freshness?.nightlyAt, 26 * HOUR), formatWhen(freshness?.nightlyAt) ?? 'Nightly'),
+    dot('429', recentLimit ? 'danger' : 'success', recentLimit ? `${limited.length}` : '429'));
+}
+
+function dayChart(usage) {
+  return h('div', { class: 'fx-xu-days', style: { '--warn': String(usage.warningFraction) }, role: 'img', 'aria-label': 'Calls over 7 days' },
+    h('span', { class: 'fx-xu-days__line', title: 'Warning' }),
+    usage.days.map((day) => {
+      const height = usage.dayLimit > 0 ? Math.min(100, (day.total / usage.dayLimit) * 100) : 0;
+      return h('span', { class: 'fx-xu-day', 'data-warning': String(day.warning), 'data-over': String(day.over), title: `${day.day} · ${num.format(day.total)}` },
+        h('span', { class: 'fx-xu-day__bar' }, h('b', { style: { '--h': `${height}%` } })),
+        h('span', {}, day.day.slice(8)));
+    }));
+}
+
+function rows(items, empty) {
+  if (!items.length) return h('p', { class: 'fx-dim' }, empty);
+  return h('div', { class: 'fx-xu-rows' }, items.map((item) => h('div', { class: 'fx-xu-row' },
+    h('span', {}, item.label),
+    h('b', {}, item.value))));
+}
+
+// The picture for one connected organisation. `status` is GET /api/xero/status.
+export function xeroUsage(status, now = Date.now()) {
+  const usage = status?.usage;
+  if (!usage) return null;
+  const tone = usage.used >= usage.dayLimit && usage.dayLimit > 0 ? 'danger' : usage.warning ? 'warn' : 'ok';
+  return h('section', { class: 'fx-xu', 'data-tone': tone, 'aria-label': 'Usage' },
+    h('div', { class: 'fx-xu__top' }, ring(usage), chips(status, now)),
+    h('details', { class: 'fx-xu__fold', open: true },
+      h('summary', {}, 'Today'),
+      legend(),
+      hourChart(usage),
+      budgetBar(usage),
+      freshnessDots(status.freshness, usage.limited, now)),
+    h('details', { class: 'fx-xu__fold' },
+      h('summary', {}, 'Detail'),
+      dayChart(usage),
+      rows(usage.tasks.map((task) => ({ label: task.task, value: num.format(task.calls) })), '—'),
+      rows(usage.limited.map((row) => ({
+        label: row.problem || '429',
+        value: formatWhen(row.at) ?? '—',
+      })), '—'),
+      h('div', { class: 'fx-xu-row' },
+        h('span', {}, 'Token'),
+        h('b', {}, formatWhen(status.freshness?.tokenRefreshedAt) ?? '—')),
+      usage.suggestTier ? notice(`Calls passed the warning on ${usage.warnedDays} days. A higher Xero tier raises the day's limit.`, 'warn', 'Tier') : null));
+}