@arcforgelabs/flow 2026.10.36 → 2026.10.38

package/server/core/ledger.js

@@ -1,7 +1,7 @@
 import { createHash } from 'node:crypto';
 import { and, asc, desc, eq, inArray, sql } from 'drizzle-orm';
 import {
-  billingObligations, invoices, obligationEvents, obligationPayments, obligationWritebacks, priceItems,
+  billingObligations, invoices, linkRejections, linkSuggestions, obligationEvents, obligationPayments, obligationWritebacks, priceItems,
 } from '../db/schema.js';
 import { FlowError, notFound } from './errors.js';
 import { createDraftInvoice, getInvoice, updateDraftInvoice } from './invoices.js';
@@ -668,6 +668,85 @@ export async function setHold(db, organisationId, obligationId, { holdState, rea
   });
 }
 
+// A job with no invoice of its own whose accounting evidence is ambiguous:
+// the matcher found accounting invoices that may be this job's, but none
+// exactly. A person settles it on the Reconcile page: "Make invoice", or a
+// link to a Flow invoice (linkJobToInvoice).
+const unlinked = (o) => o.accountingState === 'ambiguous' && !o.invoiceId && !o.accountingRef;
+
+// The matcher's open suggestions for one job, best first.
+export async function linkSuggestionsFor(db, organisationId, obligationId) {
+  return db.select({
+    system: linkSuggestions.system, externalId: linkSuggestions.externalId, externalNumber: linkSuggestions.externalNumber,
+    score: linkSuggestions.score, signals: linkSuggestions.signals,
+  }).from(linkSuggestions).where(and(
+    eq(linkSuggestions.organisationId, organisationId),
+    eq(linkSuggestions.obligationId, obligationId),
+    eq(linkSuggestions.state, 'open'),
+  )).orderBy(asc(linkSuggestions.rank));
+}
+
+// Rejects every open suggestion for the job ("not this one"): the matcher
+// never suggests those pairs again.
+async function rejectSuggestions(tx, obligation, { actor }) {
+  const open = await tx.select().from(linkSuggestions).where(and(
+    eq(linkSuggestions.organisationId, obligation.organisationId),
+    eq(linkSuggestions.obligationId, obligation.id),
+    eq(linkSuggestions.state, 'open'),
+  ));
+  for (const suggestion of open) {
+    await tx.update(linkSuggestions).set({ state: 'rejected', decidedBy: actor, decidedAt: sql`now()`, updatedAt: sql`now()` })
+      .where(eq(linkSuggestions.id, suggestion.id));
+    await tx.insert(linkRejections)
+      .values({ organisationId: obligation.organisationId, obligationId: obligation.id, system: suggestion.system, externalId: suggestion.externalId, actor })
+      .onConflictDoNothing();
+  }
+  return open.map((s) => s.externalId);
+}
+
+// "Make invoice": a person says the job has no invoice yet. Every suggestion
+// is rejected and the job is recorded as not found, so it can draft. The
+// live check before the draft still runs (draftInvoiceForObligation).
+export async function confirmNoInvoice(db, organisationId, obligationId, { actor }) {
+  requireActor(actor);
+  return db.transaction(async (tx) => {
+    const obligation = await loadObligation(tx, organisationId, obligationId, { lock: true });
+    if (!unlinked(obligation)) throw new FlowError('invalid', 'the job is not waiting for a person to settle its invoice');
+    const rejected = await rejectSuggestions(tx, obligation, { actor });
+    const row = await update(tx, obligation, { accountingState: 'not_found', accountingCheckedAt: sql`now()` });
+    await addEvent(tx, row, 'accounting_checked', actor, { reported: 'not_found', state: 'not_found', matchedBy: 'person', rejected });
+    return row;
+  });
+}
+
+// A person links a job to a Flow invoice that already exists (Reconcile).
+// The job then has its invoice: Flow drafts no other. A job held on unclear
+// accounting evidence is settled by it; whether the Flow invoice matches one
+// in the accounting system is that integration's own work, not the job's.
+// `accountingRef` is given by an accounting integration that made the Flow
+// invoice from the accounting invoice the job is tied to already.
+export async function linkJobToInvoice(db, organisationId, obligationId, { invoiceId, accountingRef = null, actor }) {
+  requireActor(actor);
+  return db.transaction(async (tx) => {
+    const obligation = await loadObligation(tx, organisationId, obligationId, { lock: true });
+    if (obligation.invoiceId) throw new FlowError('invalid', 'the job has an invoice already');
+    if (obligation.accountingRef && obligation.accountingRef !== accountingRef) throw new FlowError('invalid', 'the job is linked to an accounting invoice already');
+    const [invoice] = await tx.select({ id: invoices.id, status: invoices.status, contactId: invoices.contactId }).from(invoices)
+      .where(and(eq(invoices.organisationId, organisationId), eq(invoices.id, invoiceId)));
+    if (!invoice) throw notFound('invoice');
+    if (invoice.status === 'void') throw new FlowError('invalid', 'the invoice is void');
+    const rejected = await rejectSuggestions(tx, obligation, { actor });
+    const row = await update(tx, obligation, {
+      invoiceId: invoice.id,
+      draftBasis: basisOf(obligation),
+      ...(obligation.accountingState === 'ambiguous' ? { accountingState: 'unknown' } : {}),
+      ...(obligation.readyAt ? {} : { readyAt: sql`now()`, readyBy: actor }),
+    });
+    await addEvent(tx, row, 'invoice_linked', actor, { invoiceId: invoice.id, matchedBy: 'person', rejected });
+    return row;
+  });
+}
+
 // The obligation's view and the reasons for it, from its stored evidence only.
 // `accounting` is false while no accounting system is connected: Flow's own
 // records are then the only check, so a job nobody checked in one can draft.

package/server/index.js

@@ -13,6 +13,7 @@ import { createMonitoredLog } from './core/monitoring.js';
 import { createTracing, traceQueries } from './core/tracing.js';
 import { createPipelineWorker } from './core/pipeline.js';
 import { createReconcileWorker } from './core/reconcile.js';
+import { backgroundJobsOn } from './core/host.js';
 import { createSendWorker } from './core/sending.js';
 import { resolveSecretsKey } from './core/secrets.js';
 import { adapters as shippedAdapters } from './integrations/adapters.js';
@@ -96,20 +97,25 @@ try {
 const integrationsOn = integrations.list().filter((a) => a.enabled).map((a) => `${a.id}${a.state === 'ready' ? '' : ` (${a.state})`}`);
 console.log(`[integrations] on: ${integrationsOn.join(', ') || 'none'}; secrets key ${secrets ? `from ${secrets.source}` : 'not set (FLOW_SECRETS_KEY)'}`);
 
+// Background jobs run only where FLOW_BACKGROUND_JOBS allows: never in a
+// Replit workspace, which shares the published app's secrets
+// (server/core/host.js).
+const jobsOn = backgroundJobsOn(process.env);
+if (!jobsOn) console.log('[flow] background jobs off (FLOW_BACKGROUND_JOBS): no sync, pipeline, reconcile or sending in this copy');
 // The pipeline (server/core/pipeline.js) joins what the integrations copy into
 // Flow: jobs into the ledger, and each job to its accounting invoice. It runs
 // only while an integration that feeds it is on, and writes to no other
 // system. FLOW_PIPELINE=off stops it.
-if (process.env.FLOW_PIPELINE !== 'off') {
+if (jobsOn && process.env.FLOW_PIPELINE !== 'off') {
   createPipelineWorker({ db: database.db, integrations, log }).start();
 }
 // The daily reconcile (server/core/reconcile.js) compares Flow's own copies
 // and opens a review item for a day that does not agree. It never calls or
 // writes to another system.
-createReconcileWorker({ db: database.db, integrations, log }).start();
+if (jobsOn) createReconcileWorker({ db: database.db, integrations, log }).start();
 // The send worker (server/core/sending.js) sends only what a person queued
 // with Send all ready, to the accounting integration that is on.
-createSendWorker({ db: database.db, integrations, log }).start();
+if (jobsOn) createSendWorker({ db: database.db, integrations, log }).start();
 
 let auth = null;
 if (settings.mode === 'clerk') {

package/server/integrations/seazona/feed.js

@@ -202,7 +202,7 @@ export async function listWork(db, { now = Date.now(), finishedDays = WORK_FINIS
     return {
       sourceSystem: 'seazona',
       sourceJobRef: order.id,
-      // The Seazona order id is the case number. Never patient data.
+      // The Seazona order id is the case number.
       caseRef: order.id,
       status,
       clientId: order.clientId,
@@ -211,6 +211,9 @@ export async function listWork(db, { now = Date.now(), finishedDays = WORK_FINIS
       department: order.department,
       orderedOn: parseSeazonaDate(order.orderedText),
       dueOn: parseSeazonaDate(order.dueText),
+      // The patient, only when this installation keeps patient names
+      // (SEAZONA_KEEP_PATIENT_REFERENCE); otherwise the copy has none.
+      patient: order.patientReference ?? null,
       lines: (order.lines ?? []).map((l) => ({ code: l.code ?? null, description: l.description, amountCents: l.amountCents ?? null })),
       totalCents: order.subtotalCents,
     };

package/server/integrations/seazona/index.js

@@ -111,7 +111,7 @@ export function createSeazonaAdapter({ env = null, fetchImpl = null, now = Date.
       const scheduler = settings.scheduled ? createSeazonaScheduler({ db, settings, run, now, log, timers }) : null;
       runtime = { settings, db, client, run, scheduler };
       scheduler?.start();
-      log.info?.(`[seazona] mode ${settings.mode}; background sync ${scheduler ? 'on' : 'off (live mode only)'}; ${settings.rate.requestsPerMinute} requests a minute at most`);
+      log.info?.(`[seazona] mode ${settings.mode}; background sync ${scheduler ? 'on' : settings.mode === 'live' ? 'off (FLOW_BACKGROUND_JOBS)' : 'off (live mode only)'}; ${settings.rate.requestsPerMinute} requests a minute at most`);
     },
 
     async stop() {

package/server/integrations/seazona/settings.js

@@ -8,6 +8,8 @@
 //   replay   recorded, synthetic responses from a file; no network at all.
 // There is no default mode. Without one the adapter does nothing.
 
+import { backgroundJobsOn } from '../../core/host.js';
+
 export const MODES = Object.freeze(['live', 'sandbox', 'replay']);
 
 // Seazona publishes 60 requests a minute per API client. Flow stays at half of
@@ -190,8 +192,9 @@ export function resolveSeazonaSettings(env = process.env) {
     credentials: null,
     replayFile: '',
     rate,
-    // The scheduler starts only in live mode (issue #10).
-    scheduled: mode === 'live',
+    // The scheduler starts only in live mode (issue #10), and only where
+    // background jobs run: never in a Replit workspace (server/core/host.js).
+    scheduled: mode === 'live' && backgroundJobsOn(env),
     // The address of one order in Seazona's own screens, with {ref} for the
     // order number, for "Open in Seazona" on a stage move. Optional; one
     // without {ref} is ignored.

package/server/integrations/sentry/index.js

@@ -1,4 +1,5 @@
 import * as SentryNode from '@sentry/node';
+import { isReplitWorkspace } from '../../core/host.js';
 import { scrubSpan } from '../../ui/monitoring.js';
 
 // The Sentry adapter (docs/SENTRY.md). It sends the errors Flow logs, the
@@ -40,7 +41,7 @@ export const SENTRY_SETUP = {
   },
   fields: [
     { 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.' },
+    { name: 'SENTRY_ENVIRONMENT', label: 'Environment', help: 'How Sentry labels this installation, for example production. Empty: production, or workspace in a Replit workspace.' },
     { 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_TRACES_SAMPLE_RATE', label: 'Traces', help: 'The share of clicks, page loads and requests timed, from 0 (off) to 1 (all). Empty: 0.2.' },
   ],
@@ -50,7 +51,9 @@ export function readSentrySettings(env) {
   const dsn = String(env.SENTRY_DSN ?? '').trim();
   if (!dsn) throw new Error('SENTRY_DSN is not set. Enter the Sentry project\'s DSN in Settings, Integrations.');
   if (!DSN_PATTERN.test(dsn)) throw new Error('SENTRY_DSN is not a Sentry DSN (https://<key>@<host>/<project id>).');
-  const environment = String(env.SENTRY_ENVIRONMENT ?? '').trim() || 'production';
+  // A Replit workspace shares the published app's secrets; its errors are
+  // labelled apart so they never read as the live app's.
+  const environment = String(env.SENTRY_ENVIRONMENT ?? '').trim() || (isReplitWorkspace(env) ? 'workspace' : 'production');
   const feedback = String(env.SENTRY_FEEDBACK ?? 'on').trim() !== 'off';
   const rate = String(env.SENTRY_TRACES_SAMPLE_RATE ?? '').trim();
   const tracesSampleRate = rate === '' ? DEFAULT_TRACES_SAMPLE_RATE : Number(rate);

package/server/integrations/xero/fit.js

@@ -0,0 +1,108 @@
+// How sure Flow is that a Xero invoice in the copy is one Flow invoice
+// (docs/XERO_IMPORT.md, "Sure match"). The checks are the ones the job
+// matcher learned on work-system jobs against Xero (server/core/pipeline.js
+// scoreCandidate), plus what the Flow invoice's own jobs know: the matcher's
+// tie to this Xero invoice, and the work system's invoice number.
+//
+// A pair is sure only when one piece of hard evidence ties it, or when the
+// score is high and clearly ahead; and in both cases only when it is the one
+// fit both ways (`sureFits`).
+
+export const SURE_SCORE = 11; // total, same items, and within 3 days
+export const SURE_LEAD = 3;
+export const POOL_DAYS = 14;
+const day = (iso) => Date.parse(`${iso}T00:00:00Z`);
+const daysApart = (a, b) => (a && b ? Math.abs(day(a) - day(b)) / 86_400_000 : null);
+const withGst = (cents) => Math.round(cents * 1.1);
+const withoutReissue = (ref) => String(ref ?? '').trim().replace(/R$/i, '').toLowerCase();
+const words = (text) => String(text ?? '').trim().toLowerCase().replace(/\s+/g, ' ');
+
+// xero: { id, number, contactId, totalCents, issuedOn, itemCodes[], reference }
+// flow: { id, contactId, totalCents, subtotalCents, date, itemCodes[], reference,
+//         jobs: [{ accountingRef, sourceInvoiceRef, practitioner }] }
+// Answers { score, signals, hard }; `hard` names the evidence that ties them.
+export function scoreFit(xero, flow) {
+  const signals = [];
+  const add = (signal, weight) => signals.push({ signal, weight });
+  const jobs = flow.jobs ?? [];
+  let hard = null;
+  if (jobs.some((j) => j.accountingRef && j.accountingRef === xero.id)) hard = 'job_tied';
+  else if (xero.number && jobs.some((j) => j.sourceInvoiceRef && withoutReissue(j.sourceInvoiceRef) === withoutReissue(xero.number))) hard = 'work_invoice_number';
+  if (hard) add(hard, 10);
+  if (xero.contactId && xero.contactId === flow.contactId) add('client', 2);
+  if (xero.totalCents === flow.totalCents) add('total', 6);
+  else if ([flow.subtotalCents, withGst(flow.subtotalCents)].includes(xero.totalCents)) add('total_gst', 5);
+  const ours = new Set(flow.itemCodes ?? []);
+  const theirs = new Set(xero.itemCodes ?? []);
+  if (ours.size && theirs.size) {
+    const shared = [...ours].filter((c) => theirs.has(c)).length;
+    if (shared === ours.size && shared === theirs.size) add('items_same', 3);
+    else if (shared) add('items_overlap', 1);
+    else add('items_differ', -3);
+  }
+  const apart = daysApart(xero.issuedOn, flow.date);
+  if (apart !== null && apart <= 3) add('date_close', 2);
+  else if (apart !== null && apart <= POOL_DAYS) add('date_near', 1);
+  // A Reference is in the copy unless XERO_KEEP_REFERENCE is off.
+  if (xero.reference && flow.reference) {
+    if (words(xero.reference) === words(flow.reference)) add('reference_same', 3);
+    else add('reference_differs', -2);
+  } else if (xero.reference && jobs.some((j) => j.practitioner && words(xero.reference).includes(words(j.practitioner)))) {
+    add('practitioner', 1);
+  }
+  return { score: signals.reduce((sum, s) => sum + s.weight, 0), signals, hard };
+}
+
+// Whether the pair may be offered at all: hard evidence, or the same client
+// with an amount that fits and dates within two weeks.
+export function canFit(xero, flow, scored) {
+  if (scored.hard) return true;
+  const amount = scored.signals.some((s) => s.signal === 'total' || s.signal === 'total_gst');
+  const near = scored.signals.some((s) => s.signal === 'date_close' || s.signal === 'date_near');
+  return Boolean(xero.contactId && xero.contactId === flow.contactId && amount && near);
+}
+
+// pairs: [{ xeroId, flowId, apart, fit }], `fit` being the candidate with its
+// score. A fit loses RIVAL_WEIGHT, and is marked `rival`, when the same Flow
+// invoice has another Xero invoice dated at least RIVAL_DAYS closer to it, or
+// the same Xero invoice has another Flow invoice that much closer. Fits a day
+// or two apart stay level, so a person picks.
+export const RIVAL_WEIGHT = 4;
+export const RIVAL_DAYS = 3;
+export function markRivals(pairs) {
+  for (const p of pairs) {
+    if (p.fit.hard) continue;
+    const closer = pairs.some((o) => o !== p && o.apart + RIVAL_DAYS <= p.apart && (o.flowId === p.flowId || o.xeroId === p.xeroId));
+    if (closer) {
+      p.fit.score -= RIVAL_WEIGHT;
+      p.fit.rival = true;
+    }
+  }
+}
+
+// pairs: [{ xeroId, flowId, score, hard }]. Answers the set of `xeroId` whose
+// best fit is sure: hard evidence or SURE_SCORE, at least SURE_LEAD ahead of
+// that Xero invoice's next fit, and that Flow invoice's best fit back.
+export function sureFits(pairs) {
+  const byXero = new Map();
+  const byFlow = new Map();
+  for (const p of pairs) {
+    if (!byXero.has(p.xeroId)) byXero.set(p.xeroId, []);
+    if (!byFlow.has(p.flowId)) byFlow.set(p.flowId, []);
+    byXero.get(p.xeroId).push(p);
+    byFlow.get(p.flowId).push(p);
+  }
+  const ranked = (list) => [...list].sort((a, b) => b.score - a.score);
+  const clear = (list) => {
+    const [top, next] = ranked(list);
+    if (!top || !(top.hard || top.score >= SURE_SCORE)) return null;
+    if (next && (next.hard || top.score - next.score < SURE_LEAD)) return null;
+    return top;
+  };
+  const sure = new Map();
+  for (const [xeroId, list] of byXero) {
+    const top = clear(list);
+    if (top && clear(byFlow.get(top.flowId))?.xeroId === xeroId) sure.set(xeroId, top.flowId);
+  }
+  return sure;
+}

package/server/integrations/xero/import.js

@@ -5,6 +5,7 @@ import { isCallsStopped } from '../call-guard.js';
 import { lastSync, syncCatalogue } from './catalogue.js';
 import { mirrorState } from './lookup.js';
 import { MIRROR_RESOURCES, mirrorXero } from './mirror.js';
+import { matchXero } from './links.js';
 import { checkSentInvoices } from './reconcile.js';
 import { runWebhookWork, WEBHOOK_REFRESH_MS, webhooksActive } from './webhooks.js';
 
@@ -82,7 +83,11 @@ export async function runImportSlice(db, runtime, job, { maxPages = SLICE_PAGES
   const sent = invoices && (invoices.inserted || invoices.changed || job.payload?.reason !== 'changes')
     ? await checkSentInvoices(db, runtime, job.organisationId)
     : null;
-  return { results, more: stopped, ...(sent ? { sent } : {}) };
+  // Each Xero invoice against Flow's own (links.js): sure fits are linked, and
+  // with the Import setting on, a Flow invoice is made for each with no fit.
+  // Flow's database only.
+  const matched = sent ? await matchXero(db, job.organisationId) : null;
+  return { results, more: stopped, ...(sent ? { sent } : {}), ...(matched ? { matched } : {}) };
 }
 
 // Claims and runs one due import job, then queues the next slice when one is

package/server/integrations/xero/index.js

@@ -15,7 +15,7 @@ import { readChangesFirst } from './webhooks.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', 'xero_webhook_events', 'xero_daily_checks']);
+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', 'xero_invoice_links', 'xero_import_settings']);
 
 // What an owner enters in Settings, Integrations (server/integrations/setup.js).
 // The refresh token's key comes from Flow's secrets key.
@@ -75,10 +75,10 @@ export function createXeroAdapter({ runtime: given = null } = {}) {
       if (!given) runtime = createXeroRuntime({ settings: requireXeroSettings(env ?? process.env) });
       const { settings } = current();
       if (reconfigured) await current().guardFor(db).resume();
-      log.info?.(`[xero] mode ${settings.mode}; writes ${writesAllowed(settings) ? 'on' : 'off (XERO_ALLOW_LIVE_WRITES)'}; redirect URI ${settings.redirectUri ?? 'not set (FLOW_PUBLIC_ORIGIN)'}`);
+      log.info?.(`[xero] mode ${settings.mode}; writes ${writesAllowed(settings) ? 'on' : settings.backgroundJobs === false ? 'off (FLOW_BACKGROUND_JOBS)' : 'off (XERO_ALLOW_LIVE_WRITES)'}; redirect URI ${settings.redirectUri ?? 'not set (FLOW_PUBLIC_ORIGIN)'}`);
       // The history import (import.js) runs in the background outside replay
-      // mode. Replay tests run its slices directly.
-      if (settings.mode !== 'replay') {
+      // mode, where background jobs run. Replay tests run its slices directly.
+      if (settings.mode !== 'replay' && settings.backgroundJobs !== false) {
         importer = createImportWorker({ db, runtime: current(), log });
         await importer.start();
       }

package/server/integrations/xero/ledger.js

@@ -218,7 +218,10 @@ export async function recordXeroPayments(db, runtime, organisationId, { actor, s
     const xeroIds = [...new Set(payments.map((p) => p.xeroInvoiceId))];
     const byFlowInvoice = new Map();
     if (xeroIds.length) {
+      // Flow invoices sent to Xero, and those the Import page linked (links.js).
       const { rows } = await db.execute(sql`select xero_invoice_id, invoice_id from xero_invoice_pushes
+        where organisation_id = ${organisationId} and xero_invoice_id = any(${sql.param(xeroIds)}::text[])
+        union all select xero_invoice_id, invoice_id from xero_invoice_links
         where organisation_id = ${organisationId} and xero_invoice_id = any(${sql.param(xeroIds)}::text[])`);
       for (const row of rows) byFlowInvoice.set(row.xero_invoice_id, row.invoice_id);
     }