@arcforgelabs/flow 2026.10.48 → 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.48",
+  "version": "2026.10.50",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@arcforgelabs/flow",
-      "version": "2026.10.48",
+      "version": "2026.10.50",
       "license": "MIT",
       "dependencies": {
         "@clerk/backend": "3.25.0",
@@ -1254,18 +1254,18 @@
       "license": "MIT"
     },
     "node_modules/body-parser": {
-      "version": "2.3.0",
-      "resolved": "https://registry.npmjs.org/body-parser/-/body-parser-2.3.0.tgz",
-      "integrity": "sha512-2cGmJupaNgg+QUwVLAucDuWuoMZ6EX9iHDRswZ5lsNYEmwPaRknMPCLZz07yTzVq/83p4o/wzbDZbBrTvGGTIw==",
+      "version": "2.4.0",
+      "resolved": "https://registry.npmjs.org/body-parser/-/body-parser-2.4.0.tgz",
+      "integrity": "sha512-Ifk1KcLrxaGt1occQagQNFNNOqRt1LFuehEnHHzB8Z6cRgIxRU1TBaiIsUiCdA+gy5PL7Y1IX31DNKkRmxtXjQ==",
       "license": "MIT",
       "dependencies": {
         "bytes": "^3.1.2",
-        "content-type": "^2.0.0",
+        "content-type": "^2.1.0",
         "debug": "^4.4.3",
         "http-errors": "^2.0.1",
-        "iconv-lite": "^0.7.2",
+        "iconv-lite": "^0.7.3",
         "on-finished": "^2.4.1",
-        "qs": "^6.15.2",
+        "qs": "^6.16.1",
         "raw-body": "^3.0.2",
         "type-is": "^2.1.0"
       },
@@ -2031,9 +2031,9 @@
       "license": "ISC"
     },
     "node_modules/ip-address": {
-      "version": "10.7.3",
-      "resolved": "https://registry.npmjs.org/ip-address/-/ip-address-10.7.3.tgz",
-      "integrity": "sha512-A1kdq/tSb5QjvKvAMgIoEvDBIgL7qaqVP/jkvSwYYRZ9iEzvPpopxp2wQfu3SuZRHtpHNxMn8Fs0bS+gf5Xmwg==",
+      "version": "10.7.5",
+      "resolved": "https://registry.npmjs.org/ip-address/-/ip-address-10.7.5.tgz",
+      "integrity": "sha512-t2v0rkILYv9WXmSL7TpAaU3HXgaFYOPUcH3QHgwQ++gpJuH3bqyMy4Fvt/DJCTKwzH3Cf+bAp5W/mFL39KPLzA==",
       "license": "MIT",
       "engines": {
         "node": ">= 12"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcforgelabs/flow",
-  "version": "2026.10.48",
+  "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/automations.js

@@ -22,6 +22,10 @@ import { refreshReferences } from './references.js';
 //     on the Invoices page, until a person changes it or moves it back.
 //   reference_from_rule: a draft made from a job keeps the Reference the
 //     lab's Reference rule gives (references.js), as the job's fields arrive.
+//   add_contacts, add_xero_contacts: a customer of the work system, or of the
+//     accounting system, that no Flow contact is named like becomes one.
+//   sync_contact_edits: contact edits on either side of the Xero link reach
+//     the other (server/integrations/xero/contact-sync.js).
 
 const BATCH = 500;
 
@@ -71,6 +75,36 @@ export const AUTOMATIONS = Object.freeze([
     readConfig: (config) => readMappingConfig(config),
     remap: true,
   },
+  {
+    // Runs inside the pipeline's read of the work system's customers
+    // (pipeline.js, linkCustomers), before its jobs are read.
+    key: 'add_contacts',
+    place: 'seazona',
+    name: 'Add new clients',
+    hint: 'A new Seazona client becomes a contact.',
+    defaults: { enabled: true, config: {} },
+    readConfig: () => ({}),
+  },
+  {
+    // Runs inside the pipeline's read of the accounting system's customers
+    // (pipeline.js, linkCustomers). Off until a person turns it on.
+    key: 'add_xero_contacts',
+    place: 'xero',
+    name: 'Add Xero clients',
+    hint: 'Each Xero client becomes a contact.',
+    defaults: { enabled: false, config: {} },
+    readConfig: () => ({}),
+  },
+  {
+    // Runs on the Xero adapter's own worker (xero/contact-sync.js), which
+    // writes to Xero only while writes are allowed. Off until a person turns it on.
+    key: 'sync_contact_edits',
+    place: 'xero',
+    name: 'Two-way edits',
+    hint: 'A contact edit in Flow or Xero reaches the other. A clash waits for you.',
+    defaults: { enabled: false, config: {} },
+    readConfig: () => ({}),
+  },
   {
     key: 'mark_ready_from_work_status',
     place: 'seazona',

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/pipeline.js

@@ -10,6 +10,7 @@ import { observeJob, observeWithdrawn, recordAccountingEvidence, setHold } from
 import { loadMappingContext, mapLines } from './line-mapping.js';
 import { checkPrices, readCatalogues } from './price-list.js';
 import { linkRecord, priorLinkFor } from './links.js';
+import { createContact, readContact } from './contacts.js';
 import { HISTORY_ACTOR, HISTORY_HOLD_REASON, isHistoryHeld } from './history.js';
 import { deadHoldSince, deadSince, enqueueJob, runNextJob } from './queue.js';
 
@@ -88,20 +89,29 @@ function byName(records) {
 }
 
 // Links each customer of one system to the Flow customer with the same name,
-// when one record on each side has it and neither side is linked yet.
-export async function linkCustomers(db, organisationId, { system, customers }) {
+// when one record on each side has it and neither side is linked yet. With
+// `adopt`, a customer no Flow contact is named like becomes a new Flow
+// contact, linked to it (`imported`), so its jobs find their customer
+// (docs/CONTACTS.md). Two customers of one name stay for a person.
+export async function linkCustomers(db, organisationId, { system, customers, adopt = false }) {
   const flow = await db.select({ id: contacts.id, name: contacts.name }).from(contacts)
     .where(and(eq(contacts.organisationId, organisationId), eq(contacts.kind, 'customer')));
   const links = await activeLinks(db, organisationId, { system, entity: 'contact' });
   const linkedFlow = new Set(links.map((l) => l.flowId));
   const linkedExternal = new Set(links.map((l) => l.externalId));
   const flowByName = byName(flow);
-  const result = { linked: 0, alreadyLinked: 0, unmatched: 0, sameName: 0 };
+  const result = { linked: 0, alreadyLinked: 0, unmatched: 0, sameName: 0, added: 0 };
   for (const [key, external] of byName(customers)) {
     const own = flowByName.get(key) ?? [];
     for (const customer of external) {
       if (linkedExternal.has(String(customer.id))) result.alreadyLinked += 1;
     }
+    if (adopt && own.length === 0 && external.length === 1 && external[0].adoptable !== false && !linkedExternal.has(String(external[0].id))) {
+      if (await adoptCustomer(db, organisationId, { system, customer: external[0] })) {
+        result.added += 1;
+        continue;
+      }
+    }
     if (external.length !== 1 || own.length !== 1) {
       const waiting = external.filter((c) => !linkedExternal.has(String(c.id))).length;
       if (own.length === 0) result.unmatched += waiting;
@@ -119,6 +129,32 @@ export async function linkCustomers(db, organisationId, { system, customers }) {
   return result;
 }
 
+// The customer's own fields when Flow can keep them all, else its name only.
+async function adoptCustomer(db, organisationId, { system, customer }) {
+  const name = String(customer.name ?? '').trim();
+  const offered = { ...(customer.contact ?? {}), kind: 'customer', name };
+  let values;
+  try {
+    values = readContact(offered);
+  } catch (error) {
+    if (!(error instanceof FlowError)) throw error;
+    values = readContact({ kind: 'customer', name });
+  }
+  return db.transaction(async (tx) => {
+    let row;
+    try {
+      row = await createContact(tx, organisationId, values);
+    } catch (error) {
+      if (error instanceof FlowError && error.code === 'conflict') return false;
+      throw error;
+    }
+    const { outcome } = await linkRecord(tx, organisationId, {
+      entity: 'contact', flowId: row.id, system, externalId: String(customer.id), matchedBy: 'imported',
+    });
+    return outcome === 'linked' || outcome === 'existing';
+  });
+}
+
 async function readCursor(db, organisationId, name) {
   const [row] = await db.select().from(pipelineCursors)
     .where(and(eq(pipelineCursors.organisationId, organisationId), eq(pipelineCursors.name, name)));
@@ -500,9 +536,12 @@ export async function runPipelineOnce(db, integrations, { now = new Date() } = {
   if (work) {
     let restart = (summary.prices?.linked ?? 0) > 0;
     if (typeof work.capabilities.listCustomers === 'function') {
-      summary.workCustomers = await linkCustomers(db, organisationId, { system: work.id, customers: await work.capabilities.listCustomers({ organisationId }) });
+      const adding = (await listAutomations(db, organisationId)).find((a) => a.key === 'add_contacts');
+      summary.workCustomers = await linkCustomers(db, organisationId, {
+        system: work.id, customers: await work.capabilities.listCustomers({ organisationId }), adopt: Boolean(adding?.enabled),
+      });
       // New customer links reach jobs read before them.
-      restart ||= summary.workCustomers.linked > 0;
+      restart ||= summary.workCustomers.linked + summary.workCustomers.added > 0;
     }
     summary.work = await ingestWork(db, organisationId, { adapter: work, restart });
     // After the live feed, so a job both report is the live one.
@@ -512,8 +551,9 @@ export async function runPipelineOnce(db, integrations, { now = new Date() } = {
   }
   if (accounting) {
     if (typeof accounting.capabilities.listCustomers === 'function') {
+      const adding = (await listAutomations(db, organisationId)).find((a) => a.key === 'add_xero_contacts');
       summary.accountingCustomers = await linkCustomers(db, organisationId, {
-        system: accounting.id, customers: await accounting.capabilities.listCustomers({ organisationId }),
+        system: accounting.id, customers: await accounting.capabilities.listCustomers({ organisationId }), adopt: Boolean(adding?.enabled),
       });
     }
     const settings = await readInvoicingSettings(db, organisationId);

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/port.js

@@ -32,7 +32,7 @@ export const CAPABILITIES = Object.freeze([
   'personSettings', // { personId }: each person's own choices in this integration, as [{ key, label, hint, kind, value }]
   'setPersonSetting', // { personId, key, value }: change one, answers the new list
   'jobIssues', // open issues the integration holds for jobs, by job ref: a short phrase and the page where a person fixes it
-  'listCustomers', // the system's customers, by id and name, for the identity map (Seazona: clients; Xero: contacts)
+  'listCustomers', // the system's customers, by id and name, for the identity map (Seazona: clients; Xero: contacts). An optional `contact` is the Flow contact a new customer becomes; `adoptable` false keeps one from becoming a contact (docs/CONTACTS.md)
   'createCustomer', // { organisationId, contactId, actor }: create the system's customer from the Flow contact. Answers { outcome, contact }. Xero, when Create missing clients is on.
   'findInvoices', // sales invoices in the accounting system's copy, for the matcher; never a live call
   'readChanges', // { state: fresh | read | unavailable }: the accounting system's latest changes into its copy now, just before Flow drafts or sends (read before act)

package/server/integrations/seazona/feed.js

@@ -134,12 +134,19 @@ export async function readBillableOrder(db, orderId) {
 // with no company name is listed by its full name. A client the client list
 // never gave (the list can be closed to an API client) is listed by the
 // company name its orders carry, so its jobs still find their customer.
+// `contact` is the Flow contact a new client becomes (docs/CONTACTS.md).
 export async function listClients(db) {
-  const rows = await db.select({ id: seazonaClients.id, company: seazonaClients.company, fullName: seazonaClients.fullName, active: seazonaClients.active })
-    .from(seazonaClients);
+  const rows = await db.select({
+    id: seazonaClients.id, company: seazonaClients.company, fullName: seazonaClients.fullName, active: seazonaClients.active,
+    accountNumber: seazonaClients.accountNumber, email: seazonaClients.email, phone: seazonaClients.phone,
+    address: seazonaClients.address, taxRate: seazonaClients.taxRate, doctors: seazonaClients.doctors,
+  }).from(seazonaClients);
   const listed = rows
     .filter((r) => r.active !== false)
-    .map((r) => ({ id: r.id, name: (r.company || r.fullName || '').trim() }))
+    .map((r) => {
+      const name = (r.company || r.fullName || '').trim();
+      return { id: r.id, name, contact: clientContact(r, name) };
+    })
     .filter((r) => r.name);
   const known = new Set(rows.map((r) => r.id));
   const fromOrders = await db.selectDistinctOn([seazonaOrders.clientId], { id: seazonaOrders.clientId, company: seazonaOrders.company })
@@ -148,10 +155,40 @@ export async function listClients(db) {
     .orderBy(seazonaOrders.clientId, sql`${seazonaOrders.lastChangedAt} desc`);
   return [
     ...listed,
-    ...fromOrders.filter((r) => !known.has(r.id)).map((r) => ({ id: r.id, name: r.company.trim() })),
+    ...fromOrders.filter((r) => !known.has(r.id)).map((r) => {
+      const name = r.company.trim();
+      return { id: r.id, name, contact: { kind: 'customer', name } };
+    }),
   ];
 }
 
+// A Seazona client as a Flow contact: the billing fields and the doctors as
+// practitioners. A field Flow cannot keep is left out.
+const cut = (value, max) => {
+  const text = String(value ?? '').trim();
+  return text && text.length <= max ? text : null;
+};
+export function clientContact(row, name) {
+  const address = row.address ?? {};
+  const kept = {
+    line1: cut(address.address1, 255), line2: cut(address.address2, 255), city: cut(address.city, 255),
+    region: cut(address.region, 255), postalCode: cut(address.postalCode, 255), country: cut(address.countryCode, 255),
+  };
+  const practitioners = (Array.isArray(row.doctors) ? row.doctors : [])
+    .map((doctor) => cut(doctor?.fullName, 255)).filter(Boolean).slice(0, 30).map((person) => ({ name: person }));
+  const contact = { kind: 'customer', name, practitioners };
+  const email = cut(row.email, 255);
+  if (email) contact.email = email;
+  const phone = cut(row.phone, 50);
+  if (phone) contact.phone = phone;
+  const account = cut(row.accountNumber, 50);
+  if (account) contact.accountNumber = account;
+  const taxRate = cut(row.taxRate, 50);
+  if (taxRate) contact.taxRate = taxRate;
+  if (Object.values(kept).some(Boolean)) contact.address = Object.fromEntries(Object.entries(kept).filter(([, v]) => v));
+  return contact;
+}
+
 // Seazona's products, from Flow's copy (the products lane reads them daily),
 // for the price list's links and price check (server/core/price-list.js).
 // Seazona says only whether a product is taxable: taxable reads as GST.

package/server/integrations/seazona/sweep.js

@@ -36,7 +36,7 @@ import {
 //             withdraws it, so its invoice goes to review.
 //   clients   the whole list (GET clients/?lastModified=), read on from the
 //             last row when it is full.
-//   invoices  every change since the oldest invoice Flow holds, read on the
+//   invoices  every change since the invoice lane first read, read on the
 //             same way.
 //
 // A client or invoice that Flow holds and the whole list leaves out is read
@@ -282,12 +282,15 @@ const WHOLE_LISTS = {
     list: (client, since) => client.get('invoices/', { lastModified: since }),
     // The guide: on or after lastModified (inclusive).
     stepBackMs: 0,
-    // A day before the oldest change Flow holds: an invoice older than that
-    // was never in Flow's copy, so it cannot be missing from it.
-    async firstSince(db) {
-      const [{ oldest }] = await db.select({ oldest: sql`min(${seazonaInvoices.lastModifiedText})` }).from(seazonaInvoices);
-      const oldestMs = parseUtc(oldest);
-      return Number.isFinite(oldestMs) ? new Date(floorUtcDay(oldestMs) - DAY_MS).toISOString() : null;
+    // Where the invoice lane first read: the start of the UTC day of its
+    // first run, less SEAZONA_INVOICE_LOOKBACK_DAYS (lanes.js). An invoice
+    // last changed before that was never the lane's to read, so it is not a
+    // miss (FLOW-HORIZON-K: a day's margin before it counted such invoices).
+    // The first row Flow stored marks the first run.
+    async firstSince(db, sync) {
+      const [{ first }] = await db.select({ first: sql`min(${seazonaInvoices.firstSeenAt})` }).from(seazonaInvoices);
+      const firstMs = first ? new Date(first).getTime() : NaN;
+      return Number.isFinite(firstMs) ? new Date(floorUtcDay(firstMs) - sync.invoiceLookbackDays * DAY_MS).toISOString() : null;
     },
   },
 };
@@ -416,7 +419,7 @@ async function sweepWholeList(ctx, resource, cursor, laneStates, helpers, found)
   const readsFrom = laneReadsFrom(laneStates.get(resource), sync);
   if (readsFrom === null) return;
   if (!cursor[resource]?.cycleStartedAt) {
-    const since = await spec.firstSince(db);
+    const since = await spec.firstSince(db, sync);
     if (since === null) {
       cursor[resource] = { lastFinishedAt: at.toISOString(), listed: 0 };
       return;

package/server/integrations/sentry/index.js

@@ -47,8 +47,8 @@ export const SENTRY_SETUP = {
     { name: 'SENTRY_DSN', label: 'DSN', kind: 'url', help: 'From the Sentry project\'s Client Keys. Browsers see it, so it is not a secret.' },
     { name: 'SENTRY_ENVIRONMENT', label: 'Environment', help: 'How Sentry labels this installation, for example production. Empty: production, or workspace in a Replit workspace.' },
     { name: 'SENTRY_CLIENT', label: 'Client', help: 'The name your support desk files this installation\'s reports under. Sent as the client tag. Empty: no client tag.' },
-    { name: 'SENTRY_FEEDBACK', label: 'Report a problem button', kind: 'onoff', help: 'On: everyone signed in can send a report, with a screenshot, to this Sentry project.' },
-    { name: 'SENTRY_REPLAY', label: 'Replay with reports', kind: 'onoff', help: 'On: each report and each browser error keeps up to the last minute of the page, as a replay with every word hidden.' },
+    { name: 'SENTRY_FEEDBACK', label: 'Report button', kind: 'onoff', help: 'On: everyone signed in can send a report, with a screenshot, to this Sentry project.' },
+    { name: 'SENTRY_REPLAY', label: 'Replay', kind: 'onoff', help: 'On: each report and each browser error keeps up to the last minute of the page, as a replay with every word hidden.' },
     { name: 'SENTRY_TRACES_SAMPLE_RATE', label: 'Traces', help: 'The share of clicks, page loads and requests timed, from 0 (off) to 1 (all). Empty: 0.2.' },
   ],
 };

package/server/integrations/xero/client.js

@@ -233,6 +233,9 @@ export function createXeroClient({
     async listContacts({ maxPages } = {}) {
       return collectPages(async (page) => (await request('GET', 'Contacts', { query: { page } })).Contacts, { maxPages });
     },
+    async getContact(contactId) {
+      return first((await request('GET', `Contacts/${encodeURIComponent(contactId)}`)).Contacts);
+    },
     async findContactsByName(name) {
       return (await request('GET', 'Contacts', { query: { where: `Name==${quote(name)}` } })).Contacts ?? [];
     },
@@ -329,6 +332,26 @@ export function createXeroClient({
       }
       return created;
     },
+    // Changes the fields in `changes` on one contact (contact-sync.js). The
+    // body holds only those fields and the id; Xero keeps every other field.
+    async updateContact(contactId, changes, { idempotencyKey }) {
+      if (!contactId) throw new TypeError('updateContact: contactId is required');
+      if (!idempotencyKey) throw new TypeError('updateContact: idempotencyKey is required');
+      const payload = await request('POST', `Contacts/${encodeURIComponent(contactId)}`, {
+        query: { summarizeErrors: 'false' },
+        body: { Contacts: [{ ...changes, ContactID: contactId }] },
+        headers: { 'Idempotency-Key': idempotencyKey },
+      });
+      const updated = first(payload.Contacts);
+      const messages = validationMessages(updated);
+      if (!updated?.ContactID || updated.HasErrors || updated.StatusAttributeString === 'ERROR' || messages.length) {
+        throw xeroError('xero_validation_failed', messages.join(' ') || 'Xero refused the contact change.', {
+          status: 422,
+          details: messages.length ? { validationErrors: messages } : undefined,
+        });
+      }
+      return updated;
+    },
     async createInvoice(invoice, { idempotencyKey }) {
       if (!idempotencyKey) throw new TypeError('createInvoice: idempotencyKey is required');
       const payload = await request('POST', 'Invoices', {