@arcforgelabs/flow 2026.10.48 → 2026.10.49

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@arcforgelabs/flow",
-  "version": "2026.10.48",
+  "version": "2026.10.49",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@arcforgelabs/flow",
-      "version": "2026.10.48",
+      "version": "2026.10.49",
       "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.49",
   "description": "Invoicing, bill entry and a financial dashboard for labs, with Seazona and Xero integrations.",
   "license": "MIT",
   "repository": {

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/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/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', {