@arcforgelabs/flow 2026.10.49 → 2026.10.50

package/VISION.md

@@ -62,8 +62,9 @@ Two parts follow the board:
   changes until a person accepts. The model steps are optional and cost money
   per page, so the manager sees the month's cost.
 - **A practice portal** (#268). Practice staff sign in to follow their own
-  jobs, on desktop first, with a simpler view on phones. The server limits
-  each person to their practice.
+  jobs, send requests, scans and case notes, chat with the lab and manage
+  their own team. It works on a phone first and on a desktop. The server
+  limits each person to their practice.
 
 Job management is a bundled module, built the same way as the integrations,
 and a lab can remove it. Where the case system cannot take a change through
@@ -110,13 +111,20 @@ record in Flow with who, when and what they saw.
 What a customer was sent is a commercial commitment. A change makes a new
 version; the sent one stays as it was, attributed to whoever sent it.
 
-### Why does Flow keep as little patient data as it can?
+### Why does Flow treat all its data as health data?
 
-Dental cases carry health information, which Australian privacy law treats as
-sensitive. Flow keeps the case number and the practice. It keeps a patient
-reference only when a practice needs one printed on its invoice, and it keeps
-no clinical notes or images. A form photo the intake reader reads is not kept
-after its job is updated.
+Dental work carries health information, which Australian privacy law treats as
+sensitive. A lab or a practice decides what it puts into Flow: case notes,
+scans, photos and patient names can all arrive. So Flow treats every record
+and every file as sensitive health data:
+
+- The server limits each person to what their role and practice allow.
+- Files are encrypted at rest. A download uses a short-lived signed link.
+- Flow records each read and change of practice data in an audit log.
+- Each installation sets how long files and notes are kept. Flow deletes them
+  after that time.
+- Each installation picks its hosting region. Flow documents what a host needs
+  for health data.
 
 ### Why does Flow keep its records in PostgreSQL only?
 
@@ -137,7 +145,8 @@ its own data, configuration and secrets.
 - Replacing the case system, for now. The case system owns the case record.
   Flow's job board shows and updates the work, and does not do clinical
   case management or production scheduling.
-- Patient records, clinical notes, scans and images.
+- Clinical decisions. Flow keeps the notes and files that practices send; it
+  does not diagnose or plan treatment.
 - Acting as the general ledger. Accounting software owns the ledger and the
   bank feed.
 - Browser automation of another product. Integrations use published APIs.

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@arcforgelabs/flow",
-  "version": "2026.10.49",
+  "version": "2026.10.50",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@arcforgelabs/flow",
-      "version": "2026.10.49",
+      "version": "2026.10.50",
       "license": "MIT",
       "dependencies": {
         "@clerk/backend": "3.25.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcforgelabs/flow",
-  "version": "2026.10.49",
+  "version": "2026.10.50",
   "description": "Invoicing, bill entry and a financial dashboard for labs, with Seazona and Xero integrations.",
   "license": "MIT",
   "repository": {

package/server/api/invoicing.js

@@ -43,7 +43,7 @@ import {
 //
 //   GET   /context                    the organisations, and whether this person may issue
 //   GET   /invoices?organisationId=&status=&q=&limit=   newest first, with counts by tab;
-//                                     status is a tab: pending, ready, draft, approved, sent or void (TABS)
+//                                     status is a tab: pending, ready, draft, approved, sent, non_chargeable or void (TABS)
 //   POST  /invoices/mark-ready        { invoiceIds }: a person checked these drafts; one with a problem stays
 //   POST  /invoices/mark-not-ready    { invoiceIds }: back to To check
 //   POST  /invoices/send-ready        owner or admin: issue every ready draft and queue it for the
@@ -118,7 +118,7 @@ const DATE = /^\d{4}-\d{2}-\d{2}$/;
 // issued invoice, by its stage in the accounting system (its invoiceStages;
 // Draft while it is on its way); with no accounting system, an issued invoice
 // is Approved. Void: void in Flow or in the accounting system.
-const TABS = ['pending', 'ready', 'draft', 'approved', 'sent', 'void'];
+const TABS = ['pending', 'ready', 'draft', 'approved', 'sent', 'non_chargeable', 'void'];
 // Earlier names a saved link may still use.
 const OLD_TABS = { problem: 'pending', to_check: 'ready', issued: 'approved' };
 const VIEWS = ['in_work', 'ready', 'pending', 'drafted', 'invoiced', 'paid', 'held', 'review_required'];
@@ -332,6 +332,7 @@ async function invoiceTabs(db, organisationId, system) {
   for (const { id } of issued) tabOf.set(id, issuedTab(id, { views, stages, system }));
   for (const { id } of voided) tabOf.set(id, 'void');
   for (const id of views.problems.keys()) tabOf.set(id, 'pending');
+  for (const id of views.nonChargeable.keys()) tabOf.set(id, 'non_chargeable');
   const ids = Object.fromEntries(TABS.map((t) => [t, []]));
   for (const [id, tab] of tabOf) ids[tab].push(id);
   return { tabOf, ids, problems: views.problems, sending: views.sending };
@@ -348,6 +349,7 @@ function issuedTab(id, { views, stages, system }) {
 async function tabOfInvoice(db, organisationId, invoice, view, accounting) {
   if (invoice.status === 'void') return 'void';
   if (view === 'problem') return 'pending';
+  if (view === 'non_chargeable') return 'non_chargeable';
   if (invoice.status === 'draft') return 'ready';
   if (!accounting) return 'approved';
   if (view === 'sending') return 'draft';
@@ -626,7 +628,9 @@ export function createInvoicingRouter({
     // A draft whose job changed after it was made waits for a person to fix
     // the job at its source or adopt the change (ledger.js), as Move to
     // Ready and Send do.
-    const { problems } = await invoiceView(db, organisationId, await getInvoice(db, organisationId, invoiceId));
+    const { problems, nonChargeable } = await invoiceView(db, organisationId, await getInvoice(db, organisationId, invoiceId));
+    // A non-chargeable draft is never billed (invoice-rules.js).
+    if (nonChargeable?.length) throw new FlowError('not_ready', `${nonChargeable[0].message} Nothing was approved.`);
     // A lab's pending rule, or a skip rule the job matches (invoice-rules.js),
     // is a gate too: fix its cause, void the draft, or turn the rule off.
     const held = problems.find((p) => p.code === 'job_review' || p.code === 'rule');

package/server/core/invoice-rules.js

@@ -12,7 +12,10 @@ import { FlowError, notFound } from './errors.js';
 //   Then  wait: the job waits for a person; skip: rules never draft it;
 //         pending: Flow drafts it, and the draft is Pending with the rule's
 //         note, which says what to fix (for example a Reference with no
-//         real practitioner).
+//         real practitioner); non_chargeable: Flow drafts it and keeps it on
+//         the Non-chargeable tab. The work is done but never billed (Xero's
+//         word for such work), so the draft is never sent. Its value stays
+//         in Flow, for the lab's output.
 //
 // The rules read only Flow's own records, so they work with or without an
 // accounting integration. The earlier fixed settings (old job limit, required
@@ -70,7 +73,7 @@ export const TESTS = Object.freeze({
   share: ['is', 'is_not'],
 });
 
-export const ACTIONS = Object.freeze(['wait', 'skip', 'pending']);
+export const ACTIONS = Object.freeze(['wait', 'skip', 'pending', 'non_chargeable']);
 // Tests that take no value.
 const NO_VALUE = new Set(['is_empty', 'is_not_empty', 'has_number', 'number_in_words', 'one_word']);
 
@@ -187,7 +190,7 @@ export function ruleReasons(rules, job, { customer = {}, now = new Date() } = {}
   const context = { customer, now };
   const reasons = [];
   for (const rule of rules) {
-    if (!rule.enabled || rule.trigger !== 'job_ready' || rule.action.kind === 'pending') continue;
+    if (!rule.enabled || rule.trigger !== 'job_ready' || ['pending', 'non_chargeable'].includes(rule.action.kind)) continue;
     if (!rule.conditions.every((c) => matches(c, job, context))) continue;
     reasons.push(rule.action.kind === 'skip' ? `rule "${rule.name}": not drafted by rule` : `rule "${rule.name}": waits for a person`);
   }
@@ -225,6 +228,17 @@ export function ruleSkip(rules, job, { customer = {}, now = new Date() } = {}) {
     }));
 }
 
+// The enabled non-chargeable rules that match one draft's job (sending.js):
+// the draft is on the Non-chargeable tab, never on Pending or Ready, and
+// Send never sends it.
+export function ruleNonChargeable(rules, job, { customer = {}, now = new Date() } = {}) {
+  const context = { customer, now };
+  return rules
+    .filter((r) => r.enabled && r.trigger === 'job_ready' && r.action.kind === 'non_chargeable')
+    .filter((r) => r.conditions.every((c) => matches(c, job, context)))
+    .map((r) => ({ code: 'non_chargeable', message: `Rule "${r.name}": non-chargeable. Flow keeps it and never sends it.`, short: r.name.slice(0, 40), rule: r.id ?? null }));
+}
+
 // The starter rules made from the earlier fixed settings.
 export function starterRules(settings) {
   const rules = [

package/server/core/job-board.js

@@ -50,7 +50,7 @@ export async function describeObligations(db, organisationId, listed, { accounti
   const ready = new Set(views?.ready ?? []);
   const toCheck = new Set(views?.toCheck ?? []);
   const invoiceView = (id) => (!id || !views ? null
-    : views.problems.has(id) ? 'problem' : ready.has(id) ? 'ready' : toCheck.has(id) ? 'to_check'
+    : views.problems.has(id) ? 'problem' : views.nonChargeable.has(id) ? 'non_chargeable' : ready.has(id) ? 'ready' : toCheck.has(id) ? 'to_check'
       : views.sending.has(id) ? 'sending' : null);
   // The invoicing rules a job with no invoice waits on, for every view a
   // draft can still come from.

package/server/core/sending.js

@@ -2,7 +2,7 @@ import { randomUUID } from 'node:crypto';
 import { and, asc, desc, eq, inArray, sql } from 'drizzle-orm';
 import { billingObligations, contacts, invoiceLines, invoices } from '../db/schema.js';
 import { FlowError } from './errors.js';
-import { listRules, rulePending, ruleSkip } from './invoice-rules.js';
+import { listRules, ruleNonChargeable, rulePending, ruleSkip } from './invoice-rules.js';
 import { customerBillingByContact, effectiveSettings, readInvoicingSettings } from './invoicing-rules.js';
 import { issueInvoice } from './invoices.js';
 import { CHANGED_REASON, diffJobLines, STATUS_BACK_REASON } from './ledger.js';
@@ -20,7 +20,9 @@ import { deadHoldSince, deadSince, enqueueJob, runNextJob } from './queue.js';
 // rules (invoice-rules.js) add their notes. An enabled skip rule does too:
 // a draft whose job it matches stays Pending, even when the draft was made
 // by hand or before the rule existed. A draft with a problem is
-// Pending (the "problem" view). A draft without one is Ready.
+// Pending (the "problem" view). A draft without one is Ready. A draft whose
+// job a non-chargeable rule matches is neither: it is Non-chargeable, and
+// nothing sends it.
 //
 // Send all ready issues every ready draft (each gets its number) and, when an
 // accounting system is connected, queues it to go there. The send worker
@@ -97,14 +99,14 @@ async function checkDrafts(db, organisationId, drafts, accounting) {
   // The lab's rules (invoice-rules.js). A pending rule puts its note on the
   // draft. A skip rule holds a draft that already exists: void it, or change
   // the rule. Matching stays in invoice-rules.js.
-  const rules = (await listRules(db, organisationId)).filter((r) => r.enabled && (r.action.kind === 'pending' || r.action.kind === 'skip'));
+  const rules = (await listRules(db, organisationId)).filter((r) => r.enabled && ['pending', 'skip', 'non_chargeable'].includes(r.action.kind));
   if (rules.length && jobs.length) {
     const settings = await readInvoicingSettings(db, organisationId);
     const customers = await customerBillingByContact(db, organisationId, jobs.map((j) => j.obligation.contactId));
     for (const { obligation, reference, customerName } of jobs) {
       const customer = { ...effectiveSettings(settings, customers.get(obligation.contactId)), name: customerName ?? null };
       const job = { ...obligation, reference };
-      const found = [...rulePending(rules, job, { customer }), ...ruleSkip(rules, job, { customer })];
+      const found = [...ruleNonChargeable(rules, job, { customer }), ...rulePending(rules, job, { customer }), ...ruleSkip(rules, job, { customer })];
       if (found.length) problems.set(obligation.invoiceId, [...(problems.get(obligation.invoiceId) ?? []), ...found]);
     }
   }
@@ -125,17 +127,28 @@ async function checkDrafts(db, organisationId, drafts, accounting) {
   return problems;
 }
 
+// A draft a non-chargeable rule matches has nothing to fix: it is never sent.
+const nonChargeableOf = (found) => found.filter((p) => p.code === 'non_chargeable');
+
 // The views of the Invoices page. `accounting` is the accounting adapter, or
-// null. Every draft is in one view: Problem (a check failed; the Pending tab)
-// or Ready (its checks pass). An issued invoice is Sending while
-// queued, and a Problem when the accounting system refused it. Answers
-// { toCheck: [ids], ready: [ids], problems: Map(id -> problems), sending: Set(ids) }.
+// null. Every draft is in one view: Non-chargeable (a non-chargeable rule
+// matches its job), Problem (a check failed; the Pending tab) or Ready (its
+// checks pass). An issued invoice is Sending while queued, and a Problem when
+// the accounting system refused it. Answers { toCheck: [ids], ready: [ids],
+// problems: Map(id -> problems), nonChargeable: Map(id -> rules), sending: Set(ids) }.
 export async function invoiceViews(db, organisationId, { accounting = null } = {}) {
   const drafts = await db.select({ id: invoices.id, totalCents: invoices.totalCents, readyAt: invoices.readyAt }).from(invoices)
     .where(and(eq(invoices.organisationId, organisationId), eq(invoices.status, 'draft')))
     .orderBy(asc(invoices.createdAt), asc(invoices.id))
     .limit(CHECK_LIMIT);
   const problems = await checkDrafts(db, organisationId, drafts, accounting);
+  const nonChargeable = new Map();
+  for (const [id, found] of problems) {
+    const rules = nonChargeableOf(found);
+    if (!rules.length) continue;
+    nonChargeable.set(id, rules);
+    problems.delete(id);
+  }
   const sending = new Set();
   const issued = await db.select({ id: invoices.id, sendState: invoices.sendState, sendError: invoices.sendError }).from(invoices)
     .where(and(eq(invoices.organisationId, organisationId), eq(invoices.status, 'issued'), inArray(invoices.sendState, ['queued', 'failed'])))
@@ -146,11 +159,12 @@ export async function invoiceViews(db, organisationId, { accounting = null } = {
   }
   // A draft whose checks pass is ready (Samuel, 2026-10-20): no person
   // needs to mark it. toCheck stays for callers that still read it.
-  const clean = drafts.filter((d) => !problems.has(d.id));
+  const clean = drafts.filter((d) => !problems.has(d.id) && !nonChargeable.has(d.id));
   return {
     toCheck: [],
     ready: clean.map((d) => d.id),
     problems,
+    nonChargeable,
     sending,
   };
 }
@@ -164,6 +178,8 @@ export async function invoiceView(db, organisationId, invoice, { accounting = nu
     return { view: null, problems: [] };
   }
   const found = (await checkDrafts(db, organisationId, [invoice], accounting)).get(invoice.id) ?? [];
+  const rules = nonChargeableOf(found);
+  if (rules.length) return { view: 'non_chargeable', problems: [], nonChargeable: rules };
   return { view: found.length ? 'problem' : 'ready', problems: found };
 }
 
@@ -279,6 +295,8 @@ export async function sendAllReady(db, organisationId, { accounting = null, work
     ready = ready.filter((id) => wanted.has(id));
     held = wanted.size - ready.length;
     if (!ready.length) {
+      const kept = invoiceIds.map((id) => views.nonChargeable.get(id)?.[0]?.message).find(Boolean);
+      if (kept) throw new FlowError('not_ready', `Not sent: ${kept}`);
       const reason = invoiceIds.map((id) => views.problems.get(id)?.[0]?.message).find(Boolean);
       throw new FlowError('not_ready', reason
         ? `Not sent: ${reason.replace(/\.?$/, '.')} The invoice is on Pending.`

package/server/integrations/xero/connections.js

@@ -10,6 +10,8 @@ import { xeroError } from './client.js';
 // settings and are never stored. Tokens are never logged.
 
 const FORMAT = 'v1';
+// What a Custom Connection's row seals in place of a refresh token.
+export const CUSTOM_CONNECTION = 'custom-connection';
 
 function aad(organisationId) {
   return Buffer.from(`flow:xero:refresh-token:${organisationId}`);

package/server/integrations/xero/index.js

@@ -40,6 +40,7 @@ export const XERO_SETUP = {
   },
   fields: [
     { name: 'XERO_MODE', label: 'Mode', kind: 'choice', choices: [{ value: 'live', label: 'Live: your Xero organisation' }, { value: 'sandbox', label: 'Sandbox: a Xero Demo Company' }] },
+    { name: 'XERO_CONNECTION', label: 'Xero app type', kind: 'choice', choices: [{ value: 'app', label: 'Web app' }, { value: 'custom', label: 'Custom connection (Demo Company only)' }], help: 'Custom connection: no Xero sign-in step. Sandbox mode only.' },
     { name: 'XERO_REDIRECT_URI', label: 'Redirect URI', kind: 'url', suggest: 'callback', help: 'Register the same address on the Xero app.' },
     { name: 'XERO_CLIENT_ID', label: 'Client id', help: 'From the Xero app\'s Configuration.' },
     { name: 'XERO_CLIENT_SECRET', label: 'Client secret', secret: true, help: 'Stored encrypted. Flow never shows it again.' },

package/server/integrations/xero/oauth.js

@@ -1,8 +1,9 @@
 import { randomBytes } from 'node:crypto';
 import { DEFAULT_TIMEOUT_MS, xeroError } from './client.js';
 
-// Xero OAuth 2.0 (authorisation code with offline_access). Bodies that carry
-// tokens never reach a log or an error message.
+// Xero OAuth 2.0: the authorisation code with offline_access, or a Custom
+// Connection's client credentials (settings.js, XERO_CONNECTION). Bodies that
+// carry tokens never reach a log or an error message.
 
 export const STATE_TTL_MS = 10 * 60 * 1000;
 
@@ -58,7 +59,7 @@ async function tokenRequest(settings, fetchImpl, form, what) {
       oauthError: typeof body?.error === 'string' ? body.error.slice(0, 40) : null,
     });
   }
-  if (!body?.access_token || !body?.refresh_token) {
+  if (!body?.access_token || (form.grant_type !== 'client_credentials' && !body?.refresh_token)) {
     throw xeroError('xero_token_failed', `Xero's answer to ${what} had no tokens.`, { status: 502 });
   }
   return body;
@@ -73,6 +74,12 @@ export function refreshTokens(settings, fetchImpl, refreshToken) {
   return tokenRequest(settings, fetchImpl, { grant_type: 'refresh_token', refresh_token: refreshToken }, 'the token refresh');
 }
 
+// A Custom Connection's access token. There is no refresh token: Flow asks
+// again when the token runs out.
+export function clientCredentials(settings, fetchImpl) {
+  return tokenRequest(settings, fetchImpl, { grant_type: 'client_credentials', scope: settings.scope }, 'the Custom Connection token');
+}
+
 // Best effort: a disconnect deletes Flow's copy even when Xero is down.
 export async function revokeToken(settings, fetchImpl, refreshToken) {
   const basic = Buffer.from(`${settings.clientId}:${settings.clientSecret}`).toString('base64');

package/server/integrations/xero/routes.js

@@ -12,8 +12,8 @@ import { IMPORT_STATES, importOverview, linkXeroInvoice, makeFlowInvoice, matchX
 import { queueHistoryImport, resetImport } from './import.js';
 import { MIRROR_RESOURCES, mirrorStatus, mirrorXero } from './mirror.js';
 import { accountingStatus, checkSentInvoices } from './reconcile.js';
-import { decryptToken, deleteConnection, describeConnection, readConnection, saveConnection } from './connections.js';
-import { authorizeUrl, exchangeCode, fetchConnections, revokeToken, selectConnection } from './oauth.js';
+import { CUSTOM_CONNECTION, decryptToken, deleteConnection, describeConnection, readConnection, saveConnection } from './connections.js';
+import { authorizeUrl, clientCredentials, exchangeCode, fetchConnections, revokeToken, selectConnection } from './oauth.js';
 import { writesAllowed } from './settings.js';
 import { readXeroUsage } from './usage.js';
 import { saveEvents, signatureValid } from './webhooks.js';
@@ -23,7 +23,8 @@ import { messagePage as themedMessagePage } from '../../ui/page.js';
 // The Xero adapter's routes, mounted at /api/xero (server/integrations/port.js).
 //
 //   GET  /status?organisationId=   any signed-in person: mode and connection
-//   POST /connect                  owner: returns Xero's approval address
+//   POST /connect                  owner: returns Xero's approval address, or
+//                                  connects a Custom Connection at once
 //   GET  /oauth/callback           Xero sends the owner back here
 //   POST /disconnect               owner: revokes and forgets the connection
 //   POST /sync                     owner or admin: copies Xero contacts and items
@@ -182,8 +183,59 @@ export function createXeroRouter({ db, personAuth, runtime, log = console, butto
     });
   }));
 
+  // Keeps the one Xero organisation these tokens reach, after proving it is
+  // one Flow may use (a Demo Company in sandbox). A refused code-flow grant
+  // is revoked at Xero. Then the history import starts.
+  async function connectWith(tokens, { organisationId, personId }) {
+    const connections = await fetchConnections(settings, runtime.transport, tokens.access_token);
+    let chosen;
+    try {
+      chosen = selectConnection(connections, settings);
+      const probe = createXeroClient({
+        tenantId: chosen.tenantId,
+        accessToken: async () => tokens.access_token,
+        fetch: runtime.transport,
+        governor: runtime.governor,
+        apiBase: settings.endpoints.api,
+        log,
+      });
+      await runtime.assertEnvironment(probe);
+    } catch (error) {
+      // Refused: Xero keeps no grant for an organisation Flow will not use.
+      if (tokens.refresh_token) await revokeToken(settings, runtime.transport, tokens.refresh_token).catch(() => false);
+      throw error;
+    }
+    const previous = await readConnection(db, organisationId);
+    const connection = await saveConnection(db, {
+      organisationId,
+      mode: settings.mode,
+      tenantId: chosen.tenantId,
+      tenantName: chosen.tenantName ?? null,
+      scope: tokens.scope ?? settings.scope,
+      // A Custom Connection has no refresh token; the column holds a sealed
+      // marker that is never read (runtime.js asks Xero again instead).
+      refreshToken: tokens.refresh_token ?? CUSTOM_CONNECTION,
+      connectedBy: personId,
+      key: settings.tokenKey,
+    });
+    runtime.remember(organisationId, tokens);
+    // A new connection is a person acting: calls stopped before resume.
+    await runtime.guardFor(db).resume();
+    // Another Xero organisation starts its history from the beginning.
+    if (previous && previous.tenantId !== connection.tenantId) await resetImport(db, organisationId);
+    await queueHistoryImport(db, organisationId, { reason: 'connected' });
+    log.info?.(`[xero] organisation ${organisationId} connected to Xero tenant ${connection.tenantId} (${settings.mode}, ${settings.connection}) by person ${personId}`);
+    return connection;
+  }
+
+  // A Custom Connection connects here at once; a Xero app answers with the
+  // approval address the browser opens.
   router.post('/connect', ...owner, handle(log, async (req, res) => {
     const organisationId = await requireOrganisation(db, req.body?.organisationId);
+    if (settings.connection === 'custom') {
+      const connection = await connectWith(await clientCredentials(settings, runtime.transport), { organisationId, personId: req.person.id });
+      return res.json({ ok: true, connected: true, connection: describeConnection(connection), mode: settings.mode });
+    }
     if (!settings.redirectUri) {
       throw Object.assign(new FlowError('xero_redirect_uri_missing', 'Set FLOW_PUBLIC_ORIGIN (or XERO_REDIRECT_URI) to this installation\'s address, and register its /api/xero/oauth/callback on the Xero app.'), { status: 503 });
     }
@@ -202,42 +254,7 @@ export function createXeroRouter({ db, personAuth, runtime, log = console, butto
     }
     try {
       const tokens = await exchangeCode(settings, runtime.transport, typeof req.query.code === 'string' ? req.query.code : '');
-      const connections = await fetchConnections(settings, runtime.transport, tokens.access_token);
-      let chosen;
-      try {
-        chosen = selectConnection(connections, settings);
-        const probe = createXeroClient({
-          tenantId: chosen.tenantId,
-          accessToken: async () => tokens.access_token,
-          fetch: runtime.transport,
-          governor: runtime.governor,
-          apiBase: settings.endpoints.api,
-          log,
-        });
-        await runtime.assertEnvironment(probe);
-      } catch (error) {
-        // Refused: Xero keeps no grant for an organisation Flow will not use.
-        await revokeToken(settings, runtime.transport, tokens.refresh_token).catch(() => false);
-        throw error;
-      }
-      const previous = await readConnection(db, entry.organisationId);
-      const connection = await saveConnection(db, {
-        organisationId: entry.organisationId,
-        mode: settings.mode,
-        tenantId: chosen.tenantId,
-        tenantName: chosen.tenantName ?? null,
-        scope: tokens.scope ?? settings.scope,
-        refreshToken: tokens.refresh_token,
-        connectedBy: entry.personId,
-        key: settings.tokenKey,
-      });
-      runtime.remember(entry.organisationId, tokens);
-      // A new connection is a person acting: calls stopped before resume.
-      await runtime.guardFor(db).resume();
-      // Another Xero organisation starts its history from the beginning.
-      if (previous && previous.tenantId !== connection.tenantId) await resetImport(db, entry.organisationId);
-      await queueHistoryImport(db, entry.organisationId, { reason: 'connected' });
-      log.info?.(`[xero] organisation ${entry.organisationId} connected to Xero tenant ${connection.tenantId} (${settings.mode}) by person ${entry.personId}`);
+      const connection = await connectWith(tokens, entry);
       const organisation = connection.tenantName || 'your Xero organisation';
       return res.type('html').send(page(
         'Xero is connected',
@@ -257,7 +274,8 @@ export function createXeroRouter({ db, personAuth, runtime, log = console, butto
     const connection = await readConnection(db, organisationId);
     if (!connection) return res.json({ ok: true, disconnected: false });
     let revoked = false;
-    try {
+    // A Custom Connection has no token to revoke: it ends in Xero's My Apps.
+    if (settings.connection !== 'custom') try {
       revoked = await revokeToken(settings, runtime.transport, decryptToken(connection.refreshTokenEnc, settings.tokenKey, organisationId));
     } catch (error) {
       log.warn?.(`[xero] could not revoke the Xero token for organisation ${organisationId}: ${error.code ?? 'error'}`);

package/server/integrations/xero/runtime.js

@@ -2,7 +2,7 @@ import { createCallGuard } from '../call-guard.js';
 import { createXeroClient, xeroError } from './client.js';
 import { decryptToken, readConnection, storeRotatedToken } from './connections.js';
 import { createGovernor } from './governor.js';
-import { createStateStore, refreshTokens } from './oauth.js';
+import { clientCredentials, createStateStore, refreshTokens } from './oauth.js';
 import { createReplayFetch, DEFAULT_REPLAY_FIXTURES, loadReplayFixtures } from './replay.js';
 import { resolveXeroSettings, writesAllowed } from './settings.js';
 
@@ -101,10 +101,13 @@ export function createXeroRuntime({ settings, fetch, now = Date.now, log = conso
     return db.transaction(async (tx) => {
       const connection = usable(await readConnection(tx, organisationId, { lock: true }));
       await guard.check(connection.tenantId, { resource: 'token' });
-      const refreshToken = decryptToken(connection.refreshTokenEnc, settings.tokenKey, organisationId);
+      // A Custom Connection has no refresh token: Flow asks with the client
+      // id and secret again, and nothing rotates.
+      const custom = settings.connection === 'custom';
+      const refreshToken = custom ? null : decryptToken(connection.refreshTokenEnc, settings.tokenKey, organisationId);
       let tokens;
       try {
-        tokens = await refreshTokens(settings, transport, refreshToken);
+        tokens = custom ? await clientCredentials(settings, transport) : await refreshTokens(settings, transport, refreshToken);
       } catch (error) {
         // invalid_grant: the connection is gone. invalid_client: the app's
         // client id or secret is wrong. Neither clears without a person.
@@ -116,7 +119,7 @@ export function createXeroRuntime({ settings, fetch, now = Date.now, log = conso
         throw error;
       }
       await guard.record(connection.tenantId, { resource: 'token', statusCode: 200 });
-      await storeRotatedToken(tx, organisationId, { refreshToken: tokens.refresh_token, scope: tokens.scope, key: settings.tokenKey });
+      if (!custom) await storeRotatedToken(tx, organisationId, { refreshToken: tokens.refresh_token, scope: tokens.scope, key: settings.tokenKey });
       remember(organisationId, tokens);
       return tokens.access_token;
     });

package/server/integrations/xero/settings.js

@@ -10,6 +10,14 @@
 //            is not DEMO, so a sandbox can never write to a real ledger.
 //   replay   no network: recorded, synthetic Xero responses
 //            (server/integrations/xero/fixtures). Development and CI.
+//
+// XERO_CONNECTION says how Flow gets its Xero access tokens.
+//   app      (default) a Xero web app: an owner approves in the browser, and
+//            Flow keeps the rotating refresh token.
+//   custom   a Xero Custom Connection (client credentials): no browser step
+//            and no refresh token. Sandbox only: Xero makes Custom
+//            Connections free on the Demo Company, so a demo or a test
+//            session connects with the client id and secret alone.
 
 import { backgroundJobsOn } from '../../core/host.js';
 
@@ -29,6 +37,8 @@ export const XERO_ENDPOINTS = Object.freeze({
 export const XERO_CALLBACK_PATH = '/api/xero/oauth/callback';
 // 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';
+// A Custom Connection has no refresh token, so it asks for no offline_access.
+export const DEFAULT_CUSTOM_SCOPE = DEFAULT_XERO_SCOPE.replace('offline_access ', '');
 export const DEFAULT_XERO_DAY_LIMIT = 1000;
 export const DEFAULT_DUE_DAYS = 30;
 export const DEFAULT_MIRROR_PAGE_SIZE = 200;
@@ -121,6 +131,12 @@ export function resolveXeroSettings(env = process.env) {
   if (!mode) return null;
   if (!XERO_MODES.includes(mode)) throw new Error('XERO_MODE must be "live", "sandbox", "replay" or unset');
 
+  const connection = (readEnv(env, 'XERO_CONNECTION') || 'app').toLowerCase();
+  if (!['app', 'custom'].includes(connection)) throw new Error('XERO_CONNECTION must be "app", "custom" or unset');
+  if (connection === 'custom' && mode !== 'sandbox') {
+    throw new Error('XERO_CONNECTION=custom works only with XERO_MODE=sandbox (a Xero Demo Company)');
+  }
+
   const clientId = readEnv(env, 'XERO_CLIENT_ID');
   const clientSecret = readEnv(env, 'XERO_CLIENT_SECRET');
   const tokenKey = decodeTokenKey(readEnv(env, 'XERO_TOKEN_KEY'));
@@ -150,11 +166,12 @@ export function resolveXeroSettings(env = process.env) {
 
   return {
     mode,
+    connection,
     clientId: clientId || (mode === 'replay' ? 'replay-client-id' : ''),
     clientSecret: clientSecret || (mode === 'replay' ? 'replay-client-secret' : ''),
     tokenKey,
     redirectUri: resolveRedirectUri(env),
-    scope: readEnv(env, 'XERO_SCOPE') || DEFAULT_XERO_SCOPE,
+    scope: readEnv(env, 'XERO_SCOPE') || (connection === 'custom' ? DEFAULT_CUSTOM_SCOPE : DEFAULT_XERO_SCOPE),
     tenantId,
     tenantName,
     liveWrites: readOnOff(env, 'XERO_ALLOW_LIVE_WRITES'),

package/server/ui/app-page.js

@@ -51,7 +51,7 @@ const BODY = `<div class="fx-app">
   <div id="toasts" class="fx-toasts" aria-live="polite"></div>
 </div>`;
 
-export const APP_PATHS = ['/sign-in', '/jobs', '/invoices', '/invoices/:id', '/reconcile', '/reconcile/:id', '/xero-import', '/people', '/integrations', '/integrations/:id', '/account', '/appearance', '/invoicing-settings', '/invoicing-settings/:id', '/automations', '/price-list', '/custom-fields'];
+export const APP_PATHS = ['/sign-in', '/jobs', '/invoices', '/invoices/:id', '/contacts', '/contacts/:id', '/reconcile', '/reconcile/:id', '/xero-import', '/people', '/integrations', '/integrations/:id', '/account', '/appearance', '/invoicing-settings', '/invoicing-settings/:id', '/automations', '/price-list', '/price-list/:id', '/custom-fields'];
 
 export function appPage({ defaultFamily }) {
   return renderPage({

package/server/ui/app.js

@@ -1014,8 +1014,11 @@ function xeroConnection(organisations, canChange) {
         if (canChange) {
           control = h('button', { class: `fx-btn fx-btn--sm${status.connected && !stopped && !refused ? '' : ' fx-btn--primary'}`, type: 'button', onclick: async () => {
             try {
+              // A Custom Connection connects at once; a Xero app sends the
+              // browser to Xero to approve.
               const { authorizeUrl } = await flow('/api/xero/connect', { method: 'POST', body: JSON.stringify({ organisationId: organisation.id }) });
-              location.assign(authorizeUrl);
+              if (authorizeUrl) location.assign(authorizeUrl);
+              else location.reload();
             } catch (error) {
               toast(error.message, 'danger');
             }

package/server/ui/flow.css

@@ -440,7 +440,12 @@ a.fx-strong:hover { text-decoration: underline; }
 .fx-toolbar { display: flex; flex-wrap: wrap; align-items: end; justify-content: space-between; gap: 12px; border-bottom: 1px solid var(--fx-line); }
 .fx-tabs { display: flex; gap: 2px; }
 .fx-tabs button { flex: none; }
-@media (max-width: 639px) { .fx-tabs { max-width: 100%; overflow-x: auto; scrollbar-width: none; } }
+/* Phones and tablets: the tabs scroll in one row and each is 44px tall, so
+   seven tabs never run past the page and a thumb hits each one. */
+@media (max-width: 1023px) {
+  .fx-tabs { max-width: 100%; overflow-x: auto; scrollbar-width: none; }
+  .fx-tabs button { min-height: 44px; }
+}
 .fx-tabs button {
   display: inline-flex; align-items: center; gap: 8px; padding: 10px 14px; margin-bottom: -1px;
   border: 0; border-bottom: 2px solid transparent; background: transparent; cursor: pointer;
@@ -1346,7 +1351,6 @@ body[data-state="loading"] .fx-loading { display: grid; justify-items: center; }
   /* Touch: every control a thumb uses is 44px (docs/MOBILE_TESTS.md). The
      icons and text keep their size; the box around them grows. */
   #menu-toggle, #search { width: 44px; height: 44px; }
-  .fx-tabs button { min-height: 44px; }
   /* The notice's buttons grow to 44px into its padding, so the notice
      stays one short line. */
   .fx-alerts__close { width: 44px; height: 44px; margin: -12px -8px; }

package/server/ui/invoice-rules.js

@@ -14,7 +14,7 @@ const TEST_LABELS = {
   is_not_one_of: 'is not one of', contains: 'contains', does_not_contain: 'does not contain',
   starts_with: 'starts with', does_not_start_with: 'does not start with', has_number: 'has a number', number_in_words: 'has a number beside words', one_word: 'is one word',
 };
-const ACTION_LABELS = { wait: 'Wait for a person', skip: 'Never draft', pending: 'Pending, with a note' };
+const ACTION_LABELS = { wait: 'Wait for a person', skip: 'Never draft', pending: 'Pending, with a note', non_chargeable: 'Non-chargeable' };
 const NO_VALUE = ['is_empty', 'is_not_empty', 'has_number', 'number_in_words', 'one_word'];
 const MANY = ['is_one_of', 'is_not_one_of'];
 const TYPED = ['contains', 'does_not_contain', 'starts_with', 'does_not_start_with'];

package/server/ui/invoicing.js

@@ -25,9 +25,10 @@ import { findBox, today, viewBar } from '/assets/ui/view-bar.js';
 // person must look), Ready (checks pass), then the accounting system's
 // stages: Draft (a draft there, or on its way), Approved, Sent (to the
 // customer). With no accounting system, an issued invoice is Approved.
-const TABS = [['pending', 'Pending'], ['ready', 'Ready'], ['draft', 'Draft'], ['approved', 'Approved'], ['sent', 'Sent'], ['void', 'Void']];
+// Non-chargeable: work a lab's rule keeps in Flow and never bills.
+const TABS = [['pending', 'Pending'], ['ready', 'Ready'], ['draft', 'Draft'], ['approved', 'Approved'], ['sent', 'Sent'], ['non_chargeable', 'Non-chargeable'], ['void', 'Void']];
 const TAB_LABEL = Object.fromEntries(TABS);
-const TAB_TONE = { pending: 'danger', ready: 'success', draft: 'info', approved: 'info', sent: 'success', void: 'mute' };
+const TAB_TONE = { pending: 'danger', ready: 'success', draft: 'info', approved: 'info', sent: 'success', non_chargeable: 'mute', void: 'mute' };
 // Tab names an earlier Flow kept in this browser.
 const OLD_TAB = { problem: 'pending', to_check: 'ready', issued: 'approved' };
 const NUMBERED = ['draft', 'approved', 'sent', 'void'];
@@ -359,7 +360,8 @@ export async function renderInvoiceList(main, ui) {
         run: () => voidAll(voidable),
       });
     }
-    // A draft that was never issued is deleted on Pending and Ready. An issued
+    // A draft that was never issued is deleted on Pending, Ready and
+    // Non-chargeable. An issued
     // invoice is deleted only while Flow's copy of Xero says Draft. Approved
     // or paid stays hidden. A mix runs every ticked row and reports each one.
     const fresh = rows.filter((i) => i.status === 'draft' && i.issuedVersion === 0);
@@ -367,7 +369,7 @@ export async function renderInvoiceList(main, ui) {
     const xeroDraft = issuedXero.filter((i) => xeroById.get(i.id)?.state === 'draft');
     const xeroApproved = issuedXero.filter((i) => ['approved', 'part_paid', 'paid'].includes(xeroById.get(i.id)?.state));
     const deletable = [...fresh, ...xeroDraft, ...xeroApproved];
-    const onDraftTabs = ['pending', 'ready'].includes(state.status) && fresh.length;
+    const onDraftTabs = ['pending', 'ready', 'non_chargeable'].includes(state.status) && fresh.length;
     if (context.canIssue && (onDraftTabs || xeroDraft.length)) {
       danger.push({
         icon: 'trash-2', label: 'Delete', iconOnly: true, tone: 'danger', title: 'Delete',
@@ -554,6 +556,9 @@ export async function renderInvoiceList(main, ui) {
       ...(id === 'pending' && counts?.pending ? { 'data-tone': 'danger' } : {}),
       onclick: () => { if (state.status !== id) openTab(id); },
     }, label, h('span', { class: 'fx-tabs__count' }, String(counts?.[id] ?? 0)))));
+    // On a phone the tabs scroll, and a redraw starts them at the left: keep
+    // the selected one in view, so the page says which tab it shows.
+    tabs.children[TABS.findIndex(([id]) => id === state.status)]?.scrollIntoView({ block: 'nearest', inline: 'nearest' });
   }
 
   async function draw(answer) {
@@ -587,7 +592,7 @@ export async function renderInvoiceList(main, ui) {
     const open = (href) => { saveNav({ ...readNav(), scrollY: window.scrollY, frameY: frame.body.scrollTop }); go(href); };
     const link = (href, label) => h('a', { class: 'fx-strong', href, onclick: (event) => { event.preventDefault(); event.stopPropagation(); open(href); } }, label);
     const showProblem = state.status === 'pending';
-    const created = ['pending', 'ready'].includes(state.status);
+    const created = ['pending', 'ready', 'non_chargeable'].includes(state.status);
     // An invoice gets its number when it is sent or issued, so only the
     // Numbered tabs show a Number column; the others open on Client.
     const numbered = !created;
@@ -620,7 +625,7 @@ export async function renderInvoiceList(main, ui) {
     const statusCell = (invoice) => {
       const cell = h('span', {}, invoice.sending
         ? h('span', { class: 'fx-status', 'data-tone': 'info' }, 'Sending')
-        : h('span', { class: 'fx-status', 'data-tone': TAB_TONE[invoice.tab] ?? 'mute' }, TAB_LABEL[invoice.tab] ?? ''));
+        : h('span', { class: 'fx-status', 'data-tone': TAB_TONE[invoice.tab] ?? 'mute', title: TAB_LABEL[invoice.tab] ?? null }, TAB_LABEL[invoice.tab] ?? ''));
       if (!linked) statusCells.set(invoice.id, cell);
       return cell;
     };
@@ -1108,7 +1113,10 @@ function draftView(invoice, ui, context, redraw) {
       if (!saved) return;
       const passes = saved.view === 'ready';
       const why = brief(saved.problems?.[0]?.message);
-      if (isNew) {
+      if (saved.view === 'non_chargeable') {
+        toast('Saved. It is Non-chargeable.', 'success');
+        if (isNew) go(`/invoices/${saved.id}`, { replace: true }); else redraw(saved);
+      } else if (isNew) {
         toast(passes ? 'Saved. It is Ready.' : `Saved. It is Pending. ${why}`, passes ? 'success' : 'warn');
         go(`/invoices/${saved.id}`, { replace: true });
       } else if (passes && keepsSave) {
@@ -1135,6 +1143,8 @@ function draftView(invoice, ui, context, redraw) {
   // and keeps it. A Pending draft has no send: fix its problem first.
   const to = invoice?.sendsTo ?? context.sendsTo ?? null;
   const ready = invoice?.view === 'ready';
+  // A lab's rule keeps a non-chargeable draft in Flow: nothing sends or approves it.
+  const nonChargeable = invoice?.view === 'non_chargeable';
   const nextNumber = `${context.organisations[0]?.invoicePrefix ?? ''}${String(context.organisations[0]?.nextInvoiceNumber ?? '').padStart(4, '0')}`;
   const emails = invoice?.sendMode?.mode === 'approve_and_email';
   const sendButton = context.canIssue && to && ready ? h('button', {
@@ -1159,7 +1169,7 @@ function draftView(invoice, ui, context, redraw) {
   }, emails ? `Send to ${to} and email` : `Send to ${to}`) : null;
   // With no accounting system, Approve gives the draft its number and locks
   // it. A changed job blocks it.
-  const issueButton = context.canIssue && !to ? h('button', {
+  const issueButton = context.canIssue && !to && !nonChargeable ? h('button', {
     class: 'fx-btn fx-btn--primary', type: 'button',
     onclick: async () => {
       const saved = await save();
@@ -1242,7 +1252,7 @@ function draftView(invoice, ui, context, redraw) {
 
   const previewBtn = isNew ? null : previewButton(ui, invoice.id, 'Shows the saved invoice.');
   const showAccept = Boolean(jobChange?.canAccept && context.canIssue);
-  const header = ui.pageHeader(isNew ? 'New invoice' : ready ? 'Ready invoice' : 'Pending invoice', {
+  const header = ui.pageHeader(isNew ? 'New invoice' : ready ? 'Ready invoice' : nonChargeable ? 'Non-chargeable invoice' : 'Pending invoice', {
     actions: [fromJob, deleteButton, previewBtn, saveButton, sendButton ?? issueButton].filter(Boolean),
   });
   const primaryOf = () => (showAccept ? null : (sendButton ?? issueButton ?? (saveButton.hidden ? null : saveButton)));
@@ -1260,6 +1270,7 @@ function draftView(invoice, ui, context, redraw) {
     chrome.pager,
     header,
     draftNote(to, invoice) ? ui.notice(draftNote(to, invoice), 'warn') : null,
+    nonChargeable ? ui.notice(brief(invoice.nonChargeable?.[0]?.message ?? 'Non-chargeable.')) : null,
     ...problems,
     h('div', { class: 'fx-invoice__grid' },
       h('div', { class: 'fx-invoice__main' },

package/server/ui/job-board.js

@@ -42,7 +42,7 @@ export function orderStatuses(statuses = [], jobs = []) {
 }
 
 export const INVOICE_STAGES = {
-  drafted: 'Drafted', problem: 'Pending', ready: 'Ready to invoice', invoiced: 'Invoiced', paid: 'Paid',
+  drafted: 'Drafted', problem: 'Pending', ready: 'Ready to invoice', invoiced: 'Invoiced', non_chargeable: 'Non-chargeable', paid: 'Paid',
 };
 
 const PROBLEM_VIEWS = ['pending', 'review_required', 'held'];
@@ -58,6 +58,7 @@ const isRule = (reason) => reason !== 'the job is not marked ready to invoice';
 //                     that stops the draft, or a problem with the draft
 //   Ready to invoice  a person marked the draft ready
 //   Invoiced          issued, sent, or in the accounting system
+//   Non-chargeable    a lab's rule keeps the draft in Flow, never billed
 //   Paid              paid in full
 export function invoiceStage(o) {
   if (!o || o.view === 'in_work') return null;
@@ -66,6 +67,7 @@ export function invoiceStage(o) {
   if (o.view === 'invoiced') return 'invoiced';
   if (o.invoiceView === 'problem' || o.invoiceStatus === 'void') return 'problem';
   if (o.invoiceStatus === 'issued') return 'invoiced';
+  if (o.invoiceView === 'non_chargeable') return 'non_chargeable';
   if (o.invoiceView === 'ready') return 'ready';
   if (o.view === 'ready') return (o.waitingFor ?? []).some(isRule) ? 'problem' : 'drafted';
   if (o.view === 'drafted') return 'drafted';

package/server/ui/jobs.js

@@ -50,7 +50,7 @@ const ACTIVITY = {
 const BY = { person: 'A person', automation: 'An automation' };
 // Grouped by invoice stage: a job with no invoice stage yet is still in work.
 const STAGE_GROUPS = { in_work: 'In work', ...INVOICE_STAGES };
-const STAGE_RANK = { 'In work': 0, Drafted: 2, Problem: 2, 'Ready to invoice': 4, Invoiced: 5, Paid: 6 };
+const STAGE_RANK = { 'In work': 0, Drafted: 2, Problem: 2, 'Ready to invoice': 4, Invoiced: 5, 'Non-chargeable': 5, Paid: 6 };
 
 const showDate = (iso) => (iso ? new Date(`${iso}T00:00:00`).toLocaleDateString('en-AU', { day: 'numeric', month: 'short' }) : '—');
 const fullDate = (iso) => (iso ? new Date(`${iso}T00:00:00`).toLocaleDateString('en-AU', { day: 'numeric', month: 'short', year: 'numeric' }) : '—');

package/server/ui/mobile.js

@@ -585,7 +585,7 @@ export const RULES = {
       "layout": "scroll"
     },
     "tablet": {
-      "layout": "tabs"
+      "layout": "scroll"
     },
     "desk": {
       "layout": "tabs"