@arcforgelabs/flow 2026.10.32-beta.1 → 2026.10.32

package/server/db/migrations/meta/_journal.json

@@ -113,6 +113,13 @@
       "when": 1792452497948,
       "tag": "0015_alert_dismissals",
       "breakpoints": true
+    },
+    {
+      "idx": 16,
+      "version": "7",
+      "when": 1792456270558,
+      "tag": "0016_invoice_reference",
+      "breakpoints": true
     }
   ]
 }

package/server/db/schema.js

@@ -624,6 +624,8 @@ export const invoicingSettings = pgTable('invoicing_settings', {
   // The price item code of a rush charge, and its share of the other lines.
   rushItemCode: text('rush_item_code'),
   rushPercent: integer('rush_percent').notNull().default(20),
+  // The invoice Reference, from tokens (server/core/references.js).
+  referenceTemplate: text('reference_template').notNull().default('{practitioner} - {patient}'),
   // The fixed checks above became invoice rules (invoice_rules). True once
   // this organisation's starter rules were made from them.
   rulesSeeded: boolean('rules_seeded').notNull().default(false),

package/server/integrations/port.js

@@ -20,6 +20,7 @@ export const CAPABILITIES = Object.freeze([
   'pushBill', // send an approved bill; the Flow record id is the idempotency key
   'pullPayments', // payments since a cursor, matched to invoices and bills
   'checkInvoice', // does the accounting system hold an invoice for a billable job? (the ledger's liveCheck)
+  'jobReferenceFields', // { patient }: the fields a job gives the invoice Reference (server/core/references.js)
   'listWork', // the work system's jobs from its copy in Flow, open and lately finished, for the Jobs board
   '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)

package/server/integrations/seazona/feed.js

@@ -11,9 +11,16 @@ import { seazonaClients, seazonaInvoices, seazonaOrders, seazonaReference } from
 //
 // The cursor is opaque; pass back `cursor` from the last page. A change to
 // the order or to its invoice moves the order to the end of the feed.
+//
+// A read that found no change moves the order to the end of the feed too, at
+// most once an hour (`SEEN_STEP`). Without it, an order that never changes
+// is reported once, its ledger report gets older than a day, and the ledger
+// refuses its draft as "out of date" for ever, though the lanes read the
+// order every few minutes.
 
 const BILLABLE = /\b(complete|completed|shipped|delivered)\b/i;
 const SHIPPED = /\b(shipped|delivered)\b/i;
+const SEEN_STEP = 'hour';
 
 function decodeCursor(cursor) {
   if (!cursor) return null;
@@ -31,7 +38,7 @@ function encodeCursor(at, id) {
 
 export async function readBillableWork(db, { cursor = null, limit = 200 } = {}) {
   const after = decodeCursor(cursor);
-  const changedAt = sql`greatest(${seazonaOrders.lastChangedAt}, coalesce(${seazonaInvoices.lastChangedAt}, ${seazonaOrders.lastChangedAt}))`;
+  const changedAt = sql`greatest(${seazonaOrders.lastChangedAt}, coalesce(${seazonaInvoices.lastChangedAt}, ${seazonaOrders.lastChangedAt}), date_trunc(${SEEN_STEP}, ${seazonaOrders.lastSyncedAt}))`;
   const pageSize = Math.max(1, Math.min(1000, limit));
   const rows = await db.select({
     order: seazonaOrders,

package/server/integrations/seazona/index.js

@@ -5,6 +5,7 @@ import { historyJobIssues, historySummary, readHistoryWork } from './history/ind
 import { readSeazonaSyncHealth, runSeazonaSync } from './lanes.js';
 import { SEAZONA_CALL_GUARD } from './governor.js';
 import { createSeazonaRouter } from './routes.js';
+import { orderPatient } from './patients.js';
 import { createSeazonaScheduler } from './scheduler.js';
 import { resetFailedLanes, resetStoppedLanes } from './store.js';
 import { describeSeazonaSettings, resolveSeazonaSettings } from './settings.js';
@@ -44,6 +45,7 @@ export const SEAZONA_SETUP = {
     { name: 'SEAZONA_API_BASE_URL', label: 'API address', kind: 'url', help: 'The API root of your account, https://…' },
     { name: 'SEAZONA_API_CLIENT_ID', label: 'Client id' },
     { name: 'SEAZONA_API_CLIENT_SECRET', label: 'Client secret', secret: true, help: 'Stored encrypted. Flow never shows it again.' },
+    { name: 'SEAZONA_KEEP_PATIENT_REFERENCE', label: 'Keep patient names', kind: 'onoff', help: 'On: Flow keeps the patient name of each job for the invoice Reference.' },
   ],
 };
 
@@ -149,6 +151,13 @@ export function createSeazonaAdapter({ env = null, fetchImpl = null, now = Date.
         return listWork(current().db, { now: now() });
       },
 
+      // The fields a job gives the invoice Reference: the patient name, when
+      // this installation keeps patient names (patients.js).
+      async jobReferenceFields({ sourceJobRef, read = false }) {
+        const { db, client, settings } = current();
+        return orderPatient({ db, client, settings, now }, sourceJobRef, { read });
+      },
+
       // History jobs a person must decide, as issues on their job cards,
       // each with a link to the reconciliation. Reads Flow's copy only.
       async jobIssues({ refs = [] } = {}) {

package/server/integrations/seazona/lanes.js

@@ -157,7 +157,7 @@ function judgeReads(what, attempted, failures, extra = {}) {
 
 // Reads one order's detail and applies issue #12. Returns
 // { outcome: 'read' | 'deleted' | 'failed', failure? }.
-async function readOrder(ctx, id, { listItem = null, known = null } = {}) {
+export async function readOrder(ctx, id, { listItem = null, known = null } = {}) {
   const { db, client, sync, at } = ctx;
   const mapOptions = { keepPatientReference: sync.keepPatientReference };
   try {

package/server/integrations/seazona/patients.js

@@ -0,0 +1,30 @@
+import { eq } from 'drizzle-orm';
+import { readOrder } from './lanes.js';
+import { seazonaInvoices, seazonaOrders } from './schema.js';
+
+// The patient name of one Seazona order, for the invoice Reference
+// (server/core/references.js). Flow keeps it only when the installation keeps
+// patient names (SEAZONA_KEEP_PATIENT_REFERENCE); off, this answers no name
+// and never calls Seazona. An order read before the setting was on has no
+// name yet: with `read`, Flow reads that order once more. An order that has
+// no patient in Seazona is kept as '' so it is not read again.
+export async function orderPatient({ db, client, settings, now }, orderId, { read = false } = {}) {
+  if (!settings.sync.keepPatientReference) return { patient: null };
+  const stored = async () => {
+    const [order] = await db.select({ patient: seazonaOrders.patientReference, invoiceNumber: seazonaOrders.invoiceNumber })
+      .from(seazonaOrders).where(eq(seazonaOrders.id, orderId));
+    if (order?.patient != null || !order?.invoiceNumber) return order ?? null;
+    const [invoice] = await db.select({ patient: seazonaInvoices.patientReference })
+      .from(seazonaInvoices).where(eq(seazonaInvoices.invoiceNumber, order.invoiceNumber));
+    return { ...order, patient: invoice?.patient || order.patient };
+  };
+  const known = await stored();
+  if (!known) return { patient: null };
+  if (known.patient != null) return { patient: known.patient || null };
+  if (!read) return { patient: null };
+  const result = await readOrder({ db, client, sync: settings.sync, at: new Date(Number(now())) }, orderId, { known: true });
+  if (result.outcome !== 'read') return { patient: null, asked: true };
+  const after = await stored();
+  if (after?.patient == null) await db.update(seazonaOrders).set({ patientReference: '' }).where(eq(seazonaOrders.id, orderId));
+  return { patient: after?.patient || null, asked: true };
+}

package/server/integrations/xero/client.js

@@ -263,6 +263,18 @@ export function createXeroClient({
       });
       return payload[path] ?? [];
     },
+    // Invoices by Xero id, with their lines (a `page` brings the lines).
+    // Up to 50 ids a call, for the webhook inbox (webhooks.js).
+    async listInvoicesByIds(ids) {
+      if (!ids.length) return [];
+      const payload = await request('GET', 'Invoices', { query: { IDs: ids.join(','), page: 1, pageSize: 100 } });
+      return payload.Invoices ?? [];
+    },
+    // One page of every invoice, in summary (no lines), for the daily check.
+    async listInvoiceSummaries({ page = 1, pageSize = 1000 } = {}) {
+      const payload = await request('GET', 'Invoices', { query: { summaryOnly: 'true', page, pageSize, order: 'InvoiceID ASC' } });
+      return payload.Invoices ?? [];
+    },
     // Xero emails one approved invoice to its contact, with the organisation's
     // own template, and marks it sent. Not idempotent: a repeat sends again.
     async emailInvoice(invoiceId) {

package/server/integrations/xero/import.js

@@ -6,6 +6,7 @@ import { lastSync, syncCatalogue } from './catalogue.js';
 import { mirrorState } from './lookup.js';
 import { MIRROR_RESOURCES, mirrorXero } from './mirror.js';
 import { checkSentInvoices } from './reconcile.js';
+import { runWebhookWork, WEBHOOK_REFRESH_MS, webhooksActive } from './webhooks.js';
 
 // The history import, then the reads of changes. When an owner connects Xero,
 // Flow copies the organisation's invoices, credit notes and payments into the
@@ -13,8 +14,9 @@ import { checkSentInvoices } from './reconcile.js';
 // job reads in slices; a slice that stops at the day's budget or its page
 // limit queues the next slice. When every resource is read to its end, the
 // same job is queued again for REFRESH_MS later and reads only what changed
-// since its cursor (issue #131), so the copy stays fresh (lookup.js). It only
-// reads from Xero.
+// since its cursor (issue #131), so the copy stays fresh (lookup.js). While
+// Xero's webhooks arrive (webhooks.js), it waits WEBHOOK_REFRESH_MS instead.
+// It only reads from Xero.
 
 export const IMPORT_KIND = 'xero.import';
 const IMPORT_KEY = 'history';
@@ -98,7 +100,9 @@ export async function runImportOnce(db, runtime, { workerId = `xero-import-${ran
   } else if (ran?.outcome === 'succeeded' && !ran.job.result?.stoppedBy) {
     // Read to the end: read the changes again later. A stop only a person
     // clears queues nothing; connecting or saving the settings queues it.
-    await queueChangesRead(db, ran.job.organisationId, { runAfter: new Date(Number(now()) + REFRESH_MS) });
+    // While Xero's webhooks arrive, the poll is only the safety net (issue #45).
+    const every = await webhooksActive(db, runtime, ran.job.organisationId, { now: Number(now()) }) ? WEBHOOK_REFRESH_MS : REFRESH_MS;
+    await queueChangesRead(db, ran.job.organisationId, { runAfter: new Date(Number(now()) + every) });
   }
   return ran;
 }
@@ -192,6 +196,7 @@ export function createImportWorker({ db, runtime, log = console, timers = { setT
   const workerId = `xero-import-${randomUUID()}`;
   const startedAtMs = Date.now();
   const stale = new Set();
+  const holds = new Map();
   let timer = null;
   let running = null;
   let stopped = true;
@@ -211,6 +216,7 @@ export function createImportWorker({ db, runtime, log = console, timers = { setT
         await refreshStaleCatalogues(db, runtime, { log });
         await keepReadsQueued(db, runtime, { startedAtMs });
         await reportStaleCopies(db, runtime, { stale, log });
+        await runWebhookWork(db, runtime, { log, holds });
         const ran = await runImportOnce(db, runtime, { workerId });
         if (ran) {
           busy = true;

package/server/integrations/xero/index.js

@@ -14,7 +14,7 @@ import { writesAllowed } from './settings.js';
 // XERO_MODE says which Xero it acts on. Its tables are created only while it
 // is on (docs/INTEGRATIONS.md).
 
-export const XERO_TABLES = Object.freeze(['xero_connections', 'xero_contacts', 'xero_items', 'xero_sync_runs', 'xero_invoice_pushes', 'xero_payment_cursors', 'xero_invoices', 'xero_credit_notes', 'xero_payments', 'xero_mirror_cursors', 'xero_call_guard', 'xero_calls']);
+export const XERO_TABLES = Object.freeze(['xero_connections', 'xero_contacts', 'xero_items', 'xero_sync_runs', 'xero_invoice_pushes', 'xero_payment_cursors', 'xero_invoices', 'xero_credit_notes', 'xero_payments', 'xero_mirror_cursors', 'xero_call_guard', 'xero_calls', 'xero_webhook_events', 'xero_daily_checks']);
 
 // What an owner enters in Settings, Integrations (server/integrations/setup.js).
 // The refresh token's key comes from Flow's secrets key.
@@ -29,6 +29,7 @@ export const XERO_SETUP = {
       'Redirect URI: copy it from below, exactly.',
       'Open the app\'s Configuration. Copy the client id. Generate a secret and copy it: Xero shows it once.',
       'Paste both below, choose the mode, name your Xero organisation, and turn Xero on.',
+      'Optional, for changes in seconds: open the app\'s Webhooks page. Delivery URL: this installation\'s address plus /api/xero/webhooks. Tick Contacts and Invoices, and Credit notes when Xero offers it. Copy the webhook key into "Webhook key" below and save, then press Send "Intent to receive" in Xero.',
     ],
   },
   fields: [
@@ -38,6 +39,7 @@ export const XERO_SETUP = {
     { name: 'XERO_CLIENT_SECRET', label: 'Client secret', secret: true, help: 'Stored encrypted. Flow never shows it again.' },
     { name: 'XERO_TENANT_NAME', label: 'Xero organisation name', help: 'Live mode connects only the organisation with this exact name.' },
     { name: 'XERO_ALLOW_LIVE_WRITES', label: 'Create draft invoices in live Xero', kind: 'onoff', help: 'Off: Flow only reads from Xero.' },
+    { name: 'XERO_WEBHOOK_KEY', label: 'Webhook key', secret: true, help: 'From the Xero app\'s Webhooks page. Empty: Flow reads Xero\'s changes every 15 minutes instead.' },
   ],
   derivedKeys: ['XERO_TOKEN_KEY'],
 };

package/server/integrations/xero/migrations/0007_xero_webhooks.sql

@@ -0,0 +1,30 @@
+-- Xero's webhooks and the daily check (issue #45). Each event Xero pushes, and
+-- each record the daily check finds out of step, waits here until Flow reads
+-- that record by id into its copy. One row per record: a second event for the
+-- same record before it is read only marks it pending again.
+CREATE TABLE IF NOT EXISTS "xero_webhook_events" (
+	"organisation_id" uuid NOT NULL REFERENCES "organisations"("id"),
+	"resource" text NOT NULL,
+	"resource_id" text NOT NULL,
+	"event_type" text,
+	"source" text NOT NULL,
+	"event_at" timestamp with time zone,
+	"received_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"pending" boolean DEFAULT true NOT NULL,
+	"read_at" timestamp with time zone,
+	CONSTRAINT "xero_webhook_events_pk" PRIMARY KEY("organisation_id", "resource", "resource_id")
+);
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "xero_webhook_events_pending" ON "xero_webhook_events" ("organisation_id", "resource") WHERE "pending";
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "xero_webhook_events_received" ON "xero_webhook_events" ("organisation_id", "source", "received_at");
+--> statement-breakpoint
+-- One full summary read of the invoices a day for each organisation.
+CREATE TABLE IF NOT EXISTS "xero_daily_checks" (
+	"organisation_id" uuid PRIMARY KEY NOT NULL REFERENCES "organisations"("id"),
+	"last_started_at" timestamp with time zone,
+	"last_finished_at" timestamp with time zone,
+	"last_read" integer,
+	"last_flagged" integer,
+	"last_error" text
+);

package/server/integrations/xero/migrations/meta/_journal.json

@@ -50,6 +50,13 @@
       "when": 1792490000000,
       "tag": "0006_xero_call_guard",
       "breakpoints": true
+    },
+    {
+      "idx": 7,
+      "version": "7",
+      "when": 1792500000000,
+      "tag": "0007_xero_webhooks",
+      "breakpoints": true
     }
   ]
 }

package/server/integrations/xero/mirror.js

@@ -182,6 +182,20 @@ const UPSERT = {
 const MAPPERS = { invoices: mapInvoice, credit_notes: mapCreditNote, payments: mapPayment };
 const ID_OF = { invoices: 'xeroInvoiceId', credit_notes: 'xeroCreditNoteId', payments: 'xeroPaymentId' };
 
+// Xero records as the copy's rows.
+export const mapRecords = (resource, raw, settings) => raw.map((record) => MAPPERS[resource](record, settings)).filter((r) => r[ID_OF[resource]]);
+
+// Writes each mapped row to the copy. `tx` is a transaction or the database.
+// Adds to `counts` (inserted, changed, unchanged).
+export async function storeRows(tx, organisationId, resource, rows, counts) {
+  for (const row of rows) {
+    const { rows: written } = await tx.execute(UPSERT[resource](organisationId, row, hashOf(row)));
+    if (!written.length) counts.unchanged += 1;
+    else if (written[0].inserted) counts.inserted += 1;
+    else counts.changed += 1;
+  }
+}
+
 async function readCursor(db, organisationId, resource) {
   await db.execute(sql`insert into xero_mirror_cursors (organisation_id, resource) values (${organisationId}, ${resource})
     on conflict do nothing`);
@@ -213,7 +227,6 @@ export function nextPosition({ modifiedSince, page }, rows, pageSize) {
 export async function mirrorResource(db, runtime, organisationId, resource, { maxPages = 50 } = {}) {
   if (!MIRROR_RESOURCES.includes(resource)) throw new TypeError(`unknown Xero mirror resource: ${resource}`);
   const { settings } = runtime;
-  const map = MAPPERS[resource];
   const pageSize = settings.mirrorPageSize;
   const counts = { pages: 0, read: 0, inserted: 0, changed: 0, unchanged: 0 };
   return withXeroLane('sync', async () => {
@@ -233,15 +246,10 @@ export async function mirrorResource(db, runtime, organisationId, resource, { ma
           where organisation_id = ${organisationId} and resource = ${resource}`);
         throw error;
       }
-      const rows = raw.map((record) => map(record, settings)).filter((r) => r[ID_OF[resource]]);
+      const rows = mapRecords(resource, raw, settings);
       const next = nextPosition(position, rows, pageSize);
       await db.transaction(async (tx) => {
-        for (const row of rows) {
-          const { rows: written } = await tx.execute(UPSERT[resource](organisationId, row, hashOf(row)));
-          if (!written.length) counts.unchanged += 1;
-          else if (written[0].inserted) counts.inserted += 1;
-          else counts.changed += 1;
-        }
+        await storeRows(tx, organisationId, resource, rows, counts);
         await tx.execute(sql`update xero_mirror_cursors set
           modified_since = ${next.modifiedSince}, page = ${next.page}, rows_read = rows_read + ${raw.length},
           last_read_at = now(), last_error = null,

package/server/integrations/xero/routes.js

@@ -12,6 +12,7 @@ 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 { writesAllowed } from './settings.js';
+import { saveEvents, signatureValid } from './webhooks.js';
 import { DEFAULT_FAMILY } from '../../theme/themes.js';
 import { messagePage as themedMessagePage } from '../../ui/page.js';
 
@@ -38,6 +39,8 @@ import { messagePage as themedMessagePage } from '../../ui/page.js';
 //   POST /mirror                   owner or admin: copies Xero invoices, credit
 //                                  notes and payments changed since the last copy
 //   GET  /mirror?organisationId=   any signed-in person: what the copy holds
+//   POST /webhooks                 Xero: change events, signed with the
+//                                  webhook key (XERO_WEBHOOK_KEY); no session
 //
 // Only an owner, with a verified owner sign-in, can connect or disconnect.
 // The callback carries no Flow session: the one-use state from /connect,
@@ -93,6 +96,23 @@ export function createXeroRouter({ db, personAuth, runtime, log = console, messa
   const page = (title, text, tone) => messagePage({ title, text, tone });
   const { settings } = runtime;
   const router = express.Router();
+
+  // Xero's webhooks (webhooks.js), before the JSON parser: the signature
+  // covers the raw body. Xero wants 200 with no body within 5 seconds, and
+  // 401 for a bad signature (its "intent to receive" test sends both).
+  router.post('/webhooks', express.raw({ type: () => true, limit: '1mb' }), async (req, res) => {
+    if (!settings.webhookKey) return res.status(404).end();
+    const raw = Buffer.isBuffer(req.body) ? req.body : Buffer.alloc(0);
+    if (!signatureValid(settings.webhookKey, raw, req.get('x-xero-signature'))) return res.status(401).end();
+    try {
+      await saveEvents(db, runtime, JSON.parse(raw.toString('utf8') || '{}'));
+    } catch (error) {
+      log.error?.(`[xero] saving webhook events failed: ${error?.code ?? error?.name ?? 'error'}`);
+      return res.status(500).end();
+    }
+    return res.status(200).end();
+  });
+
   router.use(express.json({ limit: '256kb' }));
 
   // Sign-in off: nothing but the callback answers, and it fails for want of

package/server/integrations/xero/settings.js

@@ -167,6 +167,9 @@ export function resolveXeroSettings(env = process.env) {
     mirrorPageSize: Math.min(readPositiveInteger(env, 'XERO_MIRROR_PAGE_SIZE', DEFAULT_MIRROR_PAGE_SIZE), MAX_MIRROR_PAGE_SIZE),
     // The share of the day's calls the mirror leaves for drafts and people.
     mirrorReserveFraction: readFraction(env, 'XERO_MIRROR_RESERVE_FRACTION', 0.3),
+    // The key Xero signs each webhook with (issue #45), from the Xero app's
+    // Webhooks page. Unset, Flow answers no webhook and reads by polling only.
+    webhookKey: readEnv(env, 'XERO_WEBHOOK_KEY') || null,
     endpoints: XERO_ENDPOINTS,
   };
 }