@arcforgelabs/flow 2026.10.32-beta.1 → 2026.10.32

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@arcforgelabs/flow",
-  "version": "2026.10.32-beta.1",
+  "version": "2026.10.32",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@arcforgelabs/flow",
-      "version": "2026.10.32-beta.1",
+      "version": "2026.10.32",
       "license": "MIT",
       "dependencies": {
         "@clerk/backend": "3.23.2",

package/package.json

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

package/server/api/invoicing.js

@@ -13,9 +13,10 @@ import {
 } from '../core/line-mapping.js';
 import {
   effectiveSettings, INVOICING_DEFAULTS, readCustomerBilling, readInvoicingSettings,
-  saveCustomerBilling, saveInvoicingSettings, sendModeSummary,
+  saveCustomerBilling, saveInvoicingSettings, sendModeFor, sendModeSummary,
 } from '../core/invoicing-rules.js';
 import { boardJobs, describeObligations } from '../core/job-board.js';
+import { jobReference } from '../core/references.js';
 import {
   acceptFindings, archivePriceItem, checkPrices, createPriceItem, linkPriceItem, readCatalogues, readPriceList, unlinkPriceItem, updatePriceItem,
 } from '../core/price-list.js';
@@ -36,9 +37,9 @@ import {
 //   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
-//                                     accounting system { issueDate }
+//                                     accounting system { issueDate, invoiceIds? (only these, each ready) }
 //   POST  /invoices/send-again        owner or admin: queue failed sends again { invoiceIds? }
-//   GET   /invoices/:id               one invoice: lines, contact, job, issued versions
+//   GET   /invoices/:id               one invoice: lines, contact, job, issued versions, and where it sends
 //   GET   /invoices/:id/pdf?version=  the invoice as a PDF, drawn by Flow (server/core/invoice-pdf.js),
 //                                     with the accounting system's number and dates once it holds it;
 //                                     no accounting system calls
@@ -250,6 +251,11 @@ async function invoiceDetail(db, organisationId, invoiceId, accounting = null) {
   return {
     ...invoice,
     ...(await invoiceView(db, organisationId, invoice, { accounting })),
+    // Where a draft goes when it is sent, and how: this customer's send mode.
+    sendsTo: accounting?.name ?? null,
+    sendMode: accounting && invoice.status === 'draft'
+      ? { mode: await sendModeFor(db, organisationId, invoice.contactId), otherCustomers: 0, ...(await accounting.capabilities.sendStatus({ organisationId })) }
+      : null,
     contact: contact ?? null,
     job: jobs.get(invoiceId) ?? null,
     versions: versions.map(({ version, issuedAt, issuedBy }) => ({ version, issuedAt, issuedBy })),
@@ -348,7 +354,8 @@ export function createInvoicingRouter({
   router.post('/invoices/send-ready', ...manager, handle(log, async (req, res) => {
     const organisationId = await organisationOf(req);
     const issueDate = optionalDate(req.body?.issueDate, 'issueDate') ?? today();
-    const result = await sendAllReady(db, organisationId, { accounting: accounting(), personId: req.person.id, issueDate });
+    const ids = req.body?.invoiceIds === undefined ? null : invoiceIdsOf(req.body);
+    const result = await sendAllReady(db, organisationId, { accounting: accounting(), personId: req.person.id, issueDate, invoiceIds: ids });
     log.info?.(`[invoicing] organisation ${organisationId}: person ${req.person.id} sent all ready: ${JSON.stringify(result)}`);
     res.json({ ok: true, ...result });
   }));
@@ -488,7 +495,11 @@ export function createInvoicingRouter({
     const organisationId = await organisationOf(req);
     // With no accounting system connected, Flow's own records are the check.
     const liveCheck = liveCheckFor(organisationId) ?? null;
-    const { invoice } = await draftInvoiceForObligation(db, organisationId, obligationId, { liveCheck, actor: `person:${req.person.id}` });
+    const [obligation] = await db.select().from(billingObligations)
+      .where(and(eq(billingObligations.organisationId, organisationId), eq(billingObligations.id, obligationId)));
+    const { referenceTemplate: template } = await readInvoicingSettings(db, organisationId);
+    const reference = obligation ? await jobReference(db, organisationId, obligation, { template, work: work().find((a) => a.id === obligation.sourceSystem) ?? null }) : null;
+    const { invoice } = await draftInvoiceForObligation(db, organisationId, obligationId, { liveCheck, actor: `person:${req.person.id}`, reference });
     log.info?.(`[invoicing] organisation ${organisationId}: person ${req.person.id} drafted invoice ${invoice.id} from job ${obligationId}`);
     res.status(201).json({ ok: true, invoice: await invoiceDetail(db, organisationId, invoice.id) });
   }));

package/server/core/automations.js

@@ -1,9 +1,10 @@
 import { and, eq, sql } from 'drizzle-orm';
 import { automations, billingObligations, invoices } from '../db/schema.js';
 import { FlowError, notFound } from './errors.js';
-import { autoDraftJobs } from './invoicing-rules.js';
+import { autoDraftJobs, readInvoicingSettings } from './invoicing-rules.js';
 import { MAPPING_DEFAULTS, readMappingConfig, remapJobs } from './line-mapping.js';
 import { setReady } from './ledger.js';
+import { refreshReferences } from './references.js';
 
 // Automations (docs/AUTOMATIONS.md): Flow's routines. Each one watches Flow's
 // own records and moves them on, and each is on or off with its own settings,
@@ -19,6 +20,8 @@ import { setReady } from './ledger.js';
 //     rules (invoicing-rules.js) gets a draft invoice in Flow.
 //   ready_when_drafted: a draft the draft routine made goes straight to Ready
 //     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.
 
 const BATCH = 500;
 
@@ -92,6 +95,14 @@ export const AUTOMATIONS = Object.freeze([
     defaults: { enabled: true, config: {} },
     readConfig: () => ({}),
   },
+  {
+    key: 'reference_from_rule',
+    place: 'invoicing',
+    name: 'Reference from the rule',
+    hint: 'A draft made from a job gets its Reference from the Reference rule. A Reference a person typed stays.',
+    defaults: { enabled: true, config: {} },
+    readConfig: () => ({}),
+  },
 ]);
 
 const byKey = new Map(AUTOMATIONS.map((a) => [a.key, a]));
@@ -169,16 +180,19 @@ async function readyWhenDrafted(db, organisationId) {
 
 // Runs every routine that is on. `accounting` is the integration whose copy
 // the draft routine checks; without one, Flow's own records are the check.
-export async function runAutomations(db, organisationId, { accounting = null, now = new Date() } = {}) {
+export async function runAutomations(db, organisationId, { accounting = null, work = null, now = new Date() } = {}) {
   const summary = {};
   for (const automation of await listAutomations(db, organisationId)) {
     if (!automation.enabled) continue;
     if (automation.key === 'mark_ready_from_work_status') {
       summary[automation.key] = await markReadyFromWorkStatus(db, organisationId, automation.config);
     } else if (automation.key === 'draft_when_ready') {
-      summary[automation.key] = await autoDraftJobs(db, organisationId, { accounting, now, actor: actorOf(automation.key) });
+      summary[automation.key] = await autoDraftJobs(db, organisationId, { accounting, work, now, actor: actorOf(automation.key) });
     } else if (automation.key === 'ready_when_drafted') {
       summary[automation.key] = await readyWhenDrafted(db, organisationId);
+    } else if (automation.key === 'reference_from_rule') {
+      const { referenceTemplate: template } = await readInvoicingSettings(db, organisationId);
+      summary[automation.key] = await refreshReferences(db, organisationId, { template, work });
     }
   }
   return summary;

package/server/core/invoices.js

@@ -98,8 +98,8 @@ export async function updateDraftInvoice(db, organisationId, invoiceId, changes)
     }
     if ('reference' in changes) fields.reference = changes.reference;
     if ('dueDate' in changes) fields.dueDate = changes.dueDate;
-    // A changed draft needs a person to check it again.
-    if (Object.keys(fields).length || 'lines' in changes) Object.assign(fields, { readyAt: null, readyBy: null });
+    // A saved change keeps the draft where it is. Flow's checks still run on
+    // it, so a change that breaks one puts the draft in Problem.
     let row = invoice;
     if (Object.keys(fields).length) {
       [row] = await tx.update(invoices).set({ ...fields, updatedAt: sql`now()` })

package/server/core/invoicing-rules.js

@@ -5,6 +5,7 @@ import {
 import { FlowError, notFound } from './errors.js';
 import { listRules, ruleReasons } from './invoice-rules.js';
 import { draftInvoiceForObligation } from './ledger.js';
+import { checkReferenceTemplate, DEFAULT_REFERENCE, jobReference } from './references.js';
 
 // Invoicing rules (docs/INVOICING_RULES.md). They are the checks a job that
 // is ready to invoice passes before Flow drafts its invoice, and how a checked
@@ -30,6 +31,7 @@ export const INVOICING_DEFAULTS = Object.freeze({
   requirePractitioner: false,
   rushItemCode: null,
   rushPercent: 20,
+  referenceTemplate: DEFAULT_REFERENCE,
 });
 
 const CUSTOMER_DEFAULTS = Object.freeze({
@@ -58,6 +60,15 @@ function shortText(value, name) {
   return value.trim() || null;
 }
 
+// An empty rule gives no Reference: the accounting system shows the number.
+function referenceTemplate(value) {
+  if (value === null) return '';
+  if (typeof value !== 'string' || value.length > 200) throw invalid('referenceTemplate must be text of 200 characters at most');
+  const problem = checkReferenceTemplate(value);
+  if (problem) throw invalid(`referenceTemplate: ${problem}`);
+  return value.trim();
+}
+
 function sendMode(value, name) {
   if (!SEND_MODES.includes(value)) throw invalid(`${name} must be one of ${SEND_MODES.join(', ')}`);
   return value;
@@ -79,6 +90,7 @@ function readSettingChanges(changes) {
     else if (key === 'paymentTermsDays') out[key] = wholeNumber(value, key, 0, 365);
     else if (key === 'rushPercent') out[key] = wholeNumber(value, key, 0, 100);
     else if (key === 'rushItemCode') out[key] = shortText(value, key);
+    else if (key === 'referenceTemplate') out[key] = referenceTemplate(value);
     else throw invalid(`unknown setting: ${key}`);
   }
   return out;
@@ -215,7 +227,7 @@ export function copyCheck(accounting, organisationId) {
 // The draft automation (automations.js) runs it. Answers counts.
 // With `accounting` null no accounting system is connected: Flow's own records
 // are the only check, as for a person's draft (ledger.js, ledgerView).
-export async function autoDraftJobs(db, organisationId, { accounting = null, now = new Date(), limit = DRAFT_BATCH, actor = ACTOR }) {
+export async function autoDraftJobs(db, organisationId, { accounting = null, work = null, now = new Date(), limit = DRAFT_BATCH, actor = ACTOR }) {
   const result = { drafted: 0, waiting: 0, off: 0, refused: 0 };
   const settings = await readInvoicingSettings(db, organisationId);
   const rules = await listRules(db, organisationId);
@@ -255,6 +267,7 @@ export async function autoDraftJobs(db, organisationId, { accounting = null, now
         liveCheck,
         actor,
         now,
+        reference: await jobReference(db, organisationId, obligation, { template: settings.referenceTemplate, work }),
         dueDate: addDays(invoiceDate, effective.paymentTermsDays),
       });
       result.drafted += 1;

package/server/core/ledger.js

@@ -399,7 +399,7 @@ function draftBlockers(o, { now, sourceMaxAgeMs, accounting = true }) {
 // the write, finds no invoice for the job. Any doubt refuses the draft, and
 // the refusal is recorded.
 export async function draftInvoiceForObligation(db, organisationId, obligationId, {
-  liveCheck, actor, now = new Date(), sourceMaxAgeMs = SOURCE_MAX_AGE_MS, dueDate = null,
+  liveCheck, actor, now = new Date(), sourceMaxAgeMs = SOURCE_MAX_AGE_MS, dueDate = null, reference = null,
 }) {
   requireActor(actor);
   // A null liveCheck says no accounting system is connected (ledgerView).
@@ -423,7 +423,8 @@ export async function draftInvoiceForObligation(db, organisationId, obligationId
     }
     const invoice = await createDraftInvoice(tx, organisationId, {
       contactId: obligation.contactId,
-      reference: obligation.caseRef ?? obligation.sourceJobRef,
+      // The Reference rule's text (references.js), never a work system id.
+      reference,
       dueDate,
       lines: obligation.lines.map(({ priceItemId, accountCode, description, quantity, unitAmountCents, taxCode }) => (
         { priceItemId, accountCode, description, quantity, unitAmountCents, taxCode }

package/server/core/pipeline.js

@@ -511,7 +511,7 @@ export async function runPipelineOnce(db, integrations, { now = new Date() } = {
     const settings = await readInvoicingSettings(db, organisationId);
     summary.matching = await matchJobs(db, organisationId, { accounting, now, staleDays: settings.staleDays });
   }
-  if (work || accounting) summary.automations = await runAutomations(db, organisationId, { accounting: accounting ?? null, now });
+  if (work || accounting) summary.automations = await runAutomations(db, organisationId, { accounting: accounting ?? null, work: work ?? null, now });
   return summary;
 }
 

package/server/core/references.js

@@ -0,0 +1,99 @@
+import { and, eq, inArray, isNotNull } from 'drizzle-orm';
+import { billingObligations, invoices } from '../db/schema.js';
+
+// The invoice Reference (docs/INVOICING_RULES.md, "Reference"). The lab writes it as a
+// rule in Invoice rules, from tokens: {practitioner} is the job's
+// practitioner, {patient} the patient name the work system gives (only when
+// its integration keeps patient names). Flow
+// never puts a work system's ids in the Reference: the customer reads it.
+
+export const REFERENCE_TOKENS = Object.freeze(['practitioner', 'patient']);
+export const DEFAULT_REFERENCE = '{practitioner} - {patient}';
+const TOKEN = /\{([a-z]+)\}/g;
+const MAX = 255;
+
+// The template's parts: text and tokens, in order.
+function parts(template) {
+  const out = [];
+  let at = 0;
+  for (const match of String(template ?? '').matchAll(TOKEN)) {
+    out.push({ text: template.slice(at, match.index) }, { token: match[1] });
+    at = match.index + match[0].length;
+  }
+  out.push({ text: String(template ?? '').slice(at) });
+  return out;
+}
+
+// Unknown tokens are refused, so a typing error shows when it is saved.
+export function checkReferenceTemplate(template) {
+  const unknown = parts(template).filter((p) => p.token && !REFERENCE_TOKENS.includes(p.token)).map((p) => `{${p.token}}`);
+  return unknown.length ? `unknown token ${unknown[0]}: use ${REFERENCE_TOKENS.map((t) => `{${t}}`).join(', ')}` : null;
+}
+
+// The Reference for some fields. Text between two tokens is a spacer: it
+// shows only when the tokens on both sides have a value, so
+// "{practitioner} - {patient}" with no patient is the practitioner alone.
+// Text before the first token and after the last always shows. Null when no
+// token has a value.
+export function renderReference(template, fields) {
+  const list = parts(template);
+  let out = list[0].text;
+  let filled = false;
+  for (let i = 1; i < list.length; i += 2) {
+    const value = String(fields[list[i].token] ?? '').trim().replace(/\s+/g, ' ');
+    if (!value) continue;
+    if (filled) out += list[i - 1].text;
+    out += value;
+    filled = true;
+  }
+  if (!filled) return null;
+  return `${out}${list.at(-1).text}`.trim().slice(0, MAX) || null;
+}
+
+// The fields of one job. `work` is the work system adapter; it gives the
+// patient name when it keeps one. With `read`, it may ask the work system for
+// a name it has not read yet.
+export async function jobReferenceFields(db, organisationId, obligation, { work = null, read = false } = {}) {
+  let found = {};
+  if (work?.id === obligation.sourceSystem && typeof work.capabilities.jobReferenceFields === 'function') {
+    // A work system that cannot answer gives no name; the rule still works.
+    found = (await work.capabilities.jobReferenceFields({ organisationId, sourceJobRef: obligation.sourceJobRef, read }).catch(() => null)) ?? {};
+  }
+  return { fields: { practitioner: obligation.practitioner, patient: found.patient ?? null }, asked: Boolean(found.asked) };
+}
+
+// The Reference of a new draft for a job. `template` is the organisation's
+// rule (invoicing settings, referenceTemplate).
+export async function jobReference(db, organisationId, obligation, { template, ...options }) {
+  return renderReference(template, (await jobReferenceFields(db, organisationId, obligation, options)).fields);
+}
+
+// Drafts Flow made from a job keep the Reference the rule gives, as the rule
+// or the job's fields change. A Reference a person typed is never changed:
+// only one that is empty, a work system id (as earlier releases wrote), or
+// the rule's own text without a field it now has, is updated. The status of
+// the draft does not change. `reads` caps how many jobs may ask the work
+// system for a name in one pass. Answers { updated }.
+export async function refreshReferences(db, organisationId, { template, work = null, reads = 10 }) {
+  const rows = await db.select({ obligation: billingObligations, invoiceId: invoices.id, reference: invoices.reference })
+    .from(billingObligations)
+    .innerJoin(invoices, eq(invoices.id, billingObligations.invoiceId))
+    .where(and(eq(billingObligations.organisationId, organisationId), isNotNull(billingObligations.invoiceId), eq(invoices.status, 'draft')));
+  let updated = 0;
+  let asked = 0;
+  for (const { obligation, invoiceId, reference } of rows) {
+    const found = await jobReferenceFields(db, organisationId, obligation, { work, read: asked < reads });
+    const { fields } = found;
+    if (found.asked) asked += 1;
+    const wanted = renderReference(template, fields);
+    if ((wanted ?? null) === (reference ?? null)) continue;
+    const ours = [null, '', obligation.caseRef, obligation.sourceJobRef,
+      renderReference(template, { ...fields, patient: null }), renderReference(DEFAULT_REFERENCE, { ...fields, patient: null }),
+      renderReference(DEFAULT_REFERENCE, fields)];
+    if (!ours.includes(reference)) continue;
+    await db.update(invoices).set({ reference: wanted })
+      .where(and(eq(invoices.organisationId, organisationId), inArray(invoices.id, [invoiceId]), eq(invoices.status, 'draft')));
+    updated += 1;
+  }
+  return { updated };
+}

package/server/core/sending.js

@@ -13,8 +13,8 @@ import { deadHoldSince, deadSince, enqueueJob, runNextJob } from './queue.js';
 // charge, an account) on every line. When an accounting
 // system is connected, its own checks are added (for Xero: the customer
 // matches one Xero contact, every item is in Xero). A draft with a problem is
-// in Problem. A person marks a draft without one ready; any later change to
-// the draft sends it back to be checked again.
+// in Problem. A person marks a draft without one ready. A saved change keeps
+// it ready; only Move to Drafts (markNotReady) takes it back.
 //
 // 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
@@ -147,10 +147,16 @@ async function assertCanSend(accounting, organisationId) {
 }
 
 // Send all ready: issues each ready draft, then queues it for the accounting
-// system. Answers { issued, queued, remaining }.
-export async function sendAllReady(db, organisationId, { accounting = null, personId, issueDate }) {
+// system. With `invoiceIds`, only those drafts, and each must be ready (the
+// Send button on one invoice). Answers { issued, queued, remaining }.
+export async function sendAllReady(db, organisationId, { accounting = null, personId, issueDate, invoiceIds = null }) {
   await assertCanSend(accounting, organisationId);
-  const { ready } = await invoiceViews(db, organisationId, { accounting });
+  let { ready } = await invoiceViews(db, organisationId, { accounting });
+  if (invoiceIds) {
+    const wanted = new Set(invoiceIds);
+    ready = ready.filter((id) => wanted.has(id));
+    if (ready.length !== wanted.size) throw new FlowError('not_ready', 'Only a ready invoice can be sent. Mark it ready first.');
+  }
   const batch = ready.slice(0, SEND_BATCH);
   let issued = 0;
   for (const invoiceId of batch) {

package/server/db/migrations/0016_invoice_reference.sql

@@ -0,0 +1 @@
+ALTER TABLE "invoicing_settings" ADD COLUMN IF NOT EXISTS "reference_template" text DEFAULT '{practitioner} - {patient}' NOT NULL;