@arcforgelabs/flow 2026.10.47 → 2026.10.48

package/README.md

@@ -43,6 +43,7 @@ run a lab.
 | `docs/INVOICING_RULES.md` | The invoicing rules that draft a job's invoice, and the two ways an invoice goes to Xero |
 | `docs/INVOICE_RULES.md` | Invoice rules a lab builds (When, If, Then) that make a ready job wait or never draft |
 | `docs/INVOICE_SENDING.md` | The invoice tabs (Pending, Ready, Draft, Approved, Sent, Void), a changed job, and Send all ready to the accounting system |
+| `docs/CONTACTS.md` | Contacts: Flow's own customers and suppliers, and creating a missing Xero client from one |
 | `docs/RECONCILE.md` | The daily reconcile: counts and totals per day across the work system's copy, the ledger and the accounting copy |
 | `docs/ALERTS.md` | Quiet alerts: the slim line on a page when something there needs a person, and how a person dismisses it |
 | `docs/AUTOMATIONS.md` | Automations: Flow routines that mark jobs ready to invoice and draft them, each on or off |

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@arcforgelabs/flow",
-  "version": "2026.10.47",
+  "version": "2026.10.48",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@arcforgelabs/flow",
-      "version": "2026.10.47",
+      "version": "2026.10.48",
       "license": "MIT",
       "dependencies": {
         "@clerk/backend": "3.25.0",

package/package.json

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

package/server/api/invoicing.js

@@ -33,6 +33,7 @@ import {
 import { isHistoryHeld } from '../core/history.js';
 import { invoicePdfDocument, pdfFields, pdfFilename, renderInvoicePdf } from '../core/invoice-pdf.js';
 import { invoiceView, invoiceViews, markNotReady, markReady, sendAgain, sendAllReady } from '../core/sending.js';
+import { createContact, getContact, listContacts, presentContact, updateContact } from '../core/contacts.js';
 import {
   billingObligations, contacts, invoices, INVOICE_STATUSES, organisations, priceItems, TAX_CODES,
 } from '../db/schema.js';
@@ -131,7 +132,8 @@ const MAX_UNIT_CENTS = 100_000_000;
 const ERROR_STATUS = {
   invalid: 400, organisation_required: 400, not_found: 404, not_draft: 409, not_issued: 409,
   never_issued: 409, was_issued: 409, not_ready: 409, live_check_unavailable: 409, conflict: 409,
-  accounting_not_connected: 409, accounting_writes_off: 409,
+  accounting_not_connected: 409, accounting_writes_off: 409, accounting_unavailable: 409, accounting_approved: 409,
+  conflict: 409,
 };
 
 function sendError(res, error, log) {
@@ -653,21 +655,46 @@ export function createInvoicingRouter({
   router.delete('/invoices/:id', ...manager, handle(log, async (req, res) => {
     const invoiceId = pathId(req.params.id, 'invoice');
     const organisationId = await organisationOf(req);
-    await deleteDraft(db, organisationId, invoiceId, { actor: `person:${req.person.id}` });
-    log.info?.(`[invoicing] organisation ${organisationId}: person ${req.person.id} deleted draft invoice ${invoiceId}`);
+    const removed = await deleteDraft(db, organisationId, invoiceId, { actor: `person:${req.person.id}`, accounting: accounting() });
+    log.info?.(`[invoicing] organisation ${organisationId}: person ${req.person.id} ${removed.status === 'void' ? 'voided invoice' : 'deleted draft invoice'} ${invoiceId}`);
     res.json({ ok: true });
   }));
 
   router.get('/contacts', ...signedIn, handle(log, async (req, res) => {
     const organisationId = await organisationOf(req);
-    const q = text(req.query.q);
-    const where = [eq(contacts.organisationId, organisationId), eq(contacts.kind, 'customer')];
-    if (q) where.push(ilike(contacts.name, containing(q)));
-    const rows = await db.select({ id: contacts.id, name: contacts.name, email: contacts.email }).from(contacts)
-      .where(and(...where)).orderBy(asc(contacts.name), asc(contacts.id)).limit(limitOf(req.query.limit, 50, 500));
+    const kind = text(req.query.kind);
+    if (kind && !['customer', 'supplier', 'all'].includes(kind)) throw invalid('kind must be customer, supplier or all');
+    const active = text(req.query.active);
+    if (active && !['true', 'false', 'all'].includes(active)) throw invalid('active must be true, false or all');
+    const rows = await listContacts(db, organisationId, {
+      q: text(req.query.q),
+      kind: kind === 'all' ? null : (kind || 'customer'),
+      active: active === 'all' ? null : active === 'false' ? false : true,
+      limit: limitOf(req.query.limit, 50, 500),
+      offset: offsetOf(req.query.offset),
+    });
     res.json({ ok: true, contacts: rows });
   }));
 
+  router.post('/contacts', ...manager, handle(log, async (req, res) => {
+    const organisationId = await organisationOf(req);
+    const contact = presentContact(await createContact(db, organisationId, req.body ?? {}));
+    log.info?.(`[invoicing] organisation ${organisationId}: person ${req.person.id} created contact ${contact.id}`);
+    res.status(201).json({ ok: true, contact });
+  }));
+
+  router.get('/contacts/:id', ...signedIn, handle(log, async (req, res) => {
+    const organisationId = await organisationOf(req);
+    res.json({ ok: true, contact: presentContact(await getContact(db, organisationId, pathId(req.params.id, 'contact'))) });
+  }));
+
+  router.patch('/contacts/:id', ...manager, handle(log, async (req, res) => {
+    const organisationId = await organisationOf(req);
+    const contact = presentContact(await updateContact(db, organisationId, pathId(req.params.id, 'contact'), req.body ?? {}));
+    log.info?.(`[invoicing] organisation ${organisationId}: person ${req.person.id} updated contact ${contact.id}`);
+    res.json({ ok: true, contact });
+  }));
+
   router.get('/price-items', ...signedIn, handle(log, async (req, res) => {
     const organisationId = await organisationOf(req);
     const q = text(req.query.q);

package/server/core/contacts.js

@@ -0,0 +1,160 @@
+import { and, asc, eq, ilike, or, sql } from 'drizzle-orm';
+import { contacts, CONTACT_KINDS } from '../db/schema.js';
+import { FlowError, notFound } from './errors.js';
+
+// Flow's own contacts (docs/CONTACTS.md). A contact is a customer or a
+// supplier the lab bills or buys from. The fields are what Xero needs to
+// bill them and what Seazona keeps for the practice a job belongs to.
+// Practitioners are people at that practice. Flow stores no patient.
+
+const NAME_MAX = 255;
+const TEXT_MAX = 255;
+const SHORT_MAX = 50;
+const PRACTITIONERS_MAX = 30;
+const ADDRESS_KEYS = ['line1', 'line2', 'city', 'region', 'postalCode', 'country'];
+
+const invalid = (message) => new FlowError('invalid', message);
+
+function text(value, name, max) {
+  if (value == null || value === '') return null;
+  if (typeof value !== 'string') throw invalid(`${name} must be text`);
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+  if (trimmed.length > max) throw invalid(`${name} is too long (${max} characters at most)`);
+  return trimmed;
+}
+
+function readAddress(raw) {
+  if (raw == null) return null;
+  if (typeof raw !== 'object' || Array.isArray(raw)) throw invalid('address must be an object');
+  const out = {};
+  for (const key of ADDRESS_KEYS) {
+    const value = text(raw[key], `address.${key}`, TEXT_MAX);
+    if (value) out[key] = value;
+  }
+  return Object.keys(out).length ? out : null;
+}
+
+function readPractitioners(raw) {
+  if (raw == null) return [];
+  if (!Array.isArray(raw)) throw invalid('practitioners must be a list');
+  if (raw.length > PRACTITIONERS_MAX) throw invalid(`a contact has ${PRACTITIONERS_MAX} practitioners at most`);
+  return raw.map((item, index) => {
+    const at = `practitioner ${index + 1}`;
+    const source = typeof item === 'string' ? { name: item } : item;
+    if (!source || typeof source !== 'object' || Array.isArray(source)) throw invalid(`${at} must be a name`);
+    const name = text(source.name, `${at} name`, NAME_MAX);
+    if (!name) throw invalid(`${at} needs a name`);
+    const email = text(source.email, `${at} email`, TEXT_MAX);
+    return email ? { name, email } : { name };
+  });
+}
+
+// The fields a create or an update may set. `partial` is an update: only the
+// keys the caller sent are returned.
+export function readContact(input, { partial = false } = {}) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) throw invalid('contact must be an object');
+  const out = {};
+  const has = (key) => Object.prototype.hasOwnProperty.call(input, key);
+  if (!partial || has('kind')) {
+    if (!CONTACT_KINDS.includes(input.kind)) throw invalid(`kind must be ${CONTACT_KINDS.join(' or ')}`);
+    out.kind = input.kind;
+  }
+  if (!partial || has('name')) {
+    const name = text(input.name, 'name', NAME_MAX);
+    if (!name) throw invalid('contact name is required');
+    out.name = name;
+  }
+  if (!partial || has('firstName')) out.firstName = text(input.firstName, 'firstName', NAME_MAX);
+  if (!partial || has('lastName')) out.lastName = text(input.lastName, 'lastName', NAME_MAX);
+  if (!partial || has('email')) out.email = text(input.email, 'email', TEXT_MAX);
+  if (!partial || has('phone')) out.phone = text(input.phone, 'phone', SHORT_MAX);
+  if (!partial || has('mobile')) out.mobile = text(input.mobile, 'mobile', SHORT_MAX);
+  if (!partial || has('accountNumber')) out.accountNumber = text(input.accountNumber, 'accountNumber', SHORT_MAX);
+  if (!partial || has('taxNumber')) out.taxNumber = text(input.taxNumber, 'taxNumber', SHORT_MAX);
+  if (!partial || has('taxRate')) out.taxRate = text(input.taxRate, 'taxRate', SHORT_MAX);
+  if (!partial || has('address')) out.address = readAddress(input.address);
+  if (!partial || has('practitioners')) out.practitioners = readPractitioners(input.practitioners);
+  if (!partial || has('active')) {
+    if (input.active != null && typeof input.active !== 'boolean') throw invalid('active must be true or false');
+    out.active = input.active !== false;
+  }
+  return out;
+}
+
+function duplicate(error, kind) {
+  const code = error?.code ?? error?.cause?.code;
+  if (code === '23505') throw new FlowError('conflict', `A ${kind ?? 'contact'} with this name already exists.`);
+  throw error;
+}
+
+export function presentContact(row) {
+  return {
+    id: row.id,
+    kind: row.kind,
+    name: row.name,
+    firstName: row.firstName ?? null,
+    lastName: row.lastName ?? null,
+    email: row.email ?? null,
+    phone: row.phone ?? null,
+    mobile: row.mobile ?? null,
+    accountNumber: row.accountNumber ?? null,
+    taxNumber: row.taxNumber ?? null,
+    taxRate: row.taxRate ?? null,
+    address: row.address ?? null,
+    practitioners: row.practitioners ?? [],
+    active: row.active !== false,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+}
+
+export async function createContact(db, organisationId, input) {
+  const values = readContact(input);
+  try {
+    const [row] = await db.insert(contacts).values({ organisationId, ...values }).returning();
+    return row;
+  } catch (error) {
+    duplicate(error, values.kind);
+  }
+}
+
+export async function getContact(db, organisationId, id) {
+  const [row] = await db.select().from(contacts)
+    .where(and(eq(contacts.organisationId, organisationId), eq(contacts.id, id)));
+  if (!row) throw notFound('contact');
+  return row;
+}
+
+export async function updateContact(db, organisationId, id, input) {
+  const current = await getContact(db, organisationId, id);
+  const patch = readContact(input, { partial: true });
+  if (!Object.keys(patch).length) return current;
+  try {
+    const [row] = await db.update(contacts)
+      .set({ ...patch, updatedAt: sql`now()` })
+      .where(and(eq(contacts.organisationId, organisationId), eq(contacts.id, id)))
+      .returning();
+    return row;
+  } catch (error) {
+    duplicate(error, patch.kind ?? current.kind);
+  }
+}
+
+// `kind` null lists customers and suppliers. `active` null lists both.
+export async function listContacts(db, organisationId, { q = '', kind = 'customer', active = true, limit = 200, offset = 0 } = {}) {
+  const where = [eq(contacts.organisationId, organisationId)];
+  if (kind) where.push(eq(contacts.kind, kind));
+  if (active === true) where.push(eq(contacts.active, true));
+  if (active === false) where.push(eq(contacts.active, false));
+  const needle = String(q ?? '').trim().replace(/[\\%_]/g, (c) => `\\${c}`);
+  if (needle) {
+    const like = `%${needle}%`;
+    where.push(or(ilike(contacts.name, like), ilike(contacts.email, like), ilike(contacts.accountNumber, like)));
+  }
+  const rows = await db.select().from(contacts).where(and(...where))
+    .orderBy(asc(contacts.name), asc(contacts.id))
+    .limit(limit)
+    .offset(offset);
+  return rows.map(presentContact);
+}

package/server/core/directory.js

@@ -1,5 +1,6 @@
 import { and, eq, isNull } from 'drizzle-orm';
-import { contacts, organisations, priceItems, CONTACT_KINDS, TAX_CODES } from '../db/schema.js';
+import { organisations, priceItems, TAX_CODES } from '../db/schema.js';
+import { createContact as insertContact } from './contacts.js';
 import { FlowError } from './errors.js';
 
 // Organisations, contacts and the price list: the records invoices and bills
@@ -13,14 +14,8 @@ export async function createOrganisation(db, { name, invoicePrefix }) {
   return row;
 }
 
-export async function createContact(db, organisationId, { kind, name, email = null }) {
-  if (!CONTACT_KINDS.includes(kind)) throw new FlowError('invalid', `unknown contact kind: ${kind}`);
-  if (!name?.trim()) throw new FlowError('invalid', 'contact name is required');
-  const [row] = await db.insert(contacts)
-    .values({ organisationId, kind, name: name.trim(), email })
-    .returning();
-  return row;
-}
+// Contacts live in contacts.js. This name stays so existing callers keep working.
+export const createContact = insertContact;
 
 export async function createPriceItem(db, organisationId, { code, name, unitAmountCents, taxCode = 'GST' }) {
   if (!code?.trim() || !name?.trim()) throw new FlowError('invalid', 'price item code and name are required');

package/server/core/invoices.js

@@ -8,6 +8,10 @@ import { invoiceTotals, lineTotals } from './money.js';
 // version. To change an issued invoice, revise it back to a draft and issue
 // it again: the number stays and the earlier versions stay as they were.
 // A draft that was never issued can be deleted. An issued invoice is voided.
+// When its accounting copy is still a draft, deleteDraft asks the accounting
+// adapter to delete it there first, and voids in Flow only after the adapter
+// confirms (docs/XERO.md, "Deleting a draft"). With no accounting system, an
+// issued invoice answers accounting_unavailable.
 
 async function loadInvoice(tx, organisationId, invoiceId, { lock = false } = {}) {
   let query = tx.select().from(invoices)
@@ -183,41 +187,90 @@ export async function voidInvoice(db, organisationId, invoiceId) {
   });
 }
 
-// Removes a draft that was never issued. The job it billed is free again:
-// its obligation no longer points at the draft, so the lab's rules decide
-// whether Flow drafts it once more. An invoice that was issued is voided,
-// not deleted (the database holds the same rule).
-export async function deleteDraft(db, organisationId, invoiceId, { actor = null } = {}) {
+// The job an invoice billed is free again: its obligation no longer points at
+// the invoice, so the lab's rules decide whether Flow drafts it once more.
+async function freeJobs(tx, organisationId, invoice, actor) {
+  const linked = await tx.select().from(billingObligations)
+    .where(and(eq(billingObligations.organisationId, organisationId), eq(billingObligations.invoiceId, invoice.id)))
+    .for('update');
+  if (linked.length && !actor) throw new FlowError('invalid', 'actor is required');
+  for (const obligation of linked) {
+    await tx.update(billingObligations)
+      .set({ invoiceId: null, draftBasis: null, updatedAt: sql`now()` })
+      .where(eq(billingObligations.id, obligation.id));
+    await tx.insert(obligationEvents).values({
+      createdAt: sql`clock_timestamp()`,
+      organisationId,
+      obligationId: obligation.id,
+      kind: 'draft_deleted',
+      actor,
+      evidence: { invoiceId: invoice.id },
+    });
+  }
+}
+
+// Same words as the Send gate (server/core/sending.js): writes that are off,
+// or a system that is not connected, stop before anything changes. An issued
+// invoice with no accounting delete answers accounting_unavailable.
+async function deleteInAccounting(accounting, organisationId, invoiceId, actor) {
+  if (!accounting || typeof accounting.capabilities?.deleteInvoice !== 'function') {
+    throw new FlowError('accounting_unavailable', 'No accounting system is connected. An issued invoice stays as it is.');
+  }
+  const status = typeof accounting.capabilities.sendStatus === 'function'
+    ? await accounting.capabilities.sendStatus({ organisationId })
+    : { connected: false, writesAllowed: false };
+  if (!status?.connected) {
+    throw new FlowError('accounting_not_connected', `${accounting.name} is not connected. Connect it in Integrations, then send.`);
+  }
+  if (!status.writesAllowed) {
+    throw new FlowError('accounting_writes_off', `${accounting.name} does not take invoices from this installation yet (writes are off). Nothing was issued.`);
+  }
+  const answer = await accounting.capabilities.deleteInvoice({ organisationId, invoiceId, actor });
+  if (answer?.state === 'approved') {
+    throw new FlowError('accounting_approved', answer.message || 'Approved in the accounting system. Void it there first.');
+  }
+  if (answer?.state === 'deleted' || answer?.state === 'gone') return answer;
+  throw new FlowError('accounting_unavailable', answer?.message || 'The accounting system cannot delete this invoice. Nothing was changed.');
+}
+
+// Removes a draft that was never issued, and frees its job. An invoice that
+// was issued is voided only after its accounting adapter deletes the draft
+// there, or reports it already gone. The issued versions stay. With no
+// accounting delete, or when the accounting invoice is approved or paid,
+// nothing in Flow changes.
+export async function deleteDraft(db, organisationId, invoiceId, { actor = null, accounting = null } = {}) {
+  const current = await loadInvoice(db, organisationId, invoiceId);
+  if (current.status === 'void') throw new FlowError('conflict', 'a void invoice is final');
+  if (current.status === 'draft' && current.issuedVersion === 0) {
+    return db.transaction(async (tx) => {
+      const invoice = await loadInvoice(tx, organisationId, invoiceId, { lock: true });
+      if (invoice.status !== 'draft' || invoice.issuedVersion !== 0) {
+        throw new FlowError('was_issued', 'an invoice that was issued cannot be deleted; void it');
+      }
+      await freeJobs(tx, organisationId, invoice, actor);
+      try {
+        await tx.delete(invoices).where(eq(invoices.id, invoice.id));
+      } catch (error) {
+        const code = error?.code ?? error?.cause?.code;
+        if (code === '23503') throw new FlowError('conflict', 'this draft is still linked; remove the link, then delete it');
+        throw error;
+      }
+      return invoice;
+    });
+  }
+  // Read and delete outside the Flow transaction. A timeout or a refusal
+  // throws here, and the invoice stays as it was. The next try reads again.
+  await deleteInAccounting(accounting, organisationId, invoiceId, actor);
   return db.transaction(async (tx) => {
     const invoice = await loadInvoice(tx, organisationId, invoiceId, { lock: true });
-    if (invoice.status !== 'draft' || invoice.issuedVersion !== 0) {
+    if (invoice.status === 'void') return invoice;
+    if (invoice.issuedVersion === 0) {
       throw new FlowError('was_issued', 'an invoice that was issued cannot be deleted; void it');
     }
-    const linked = await tx.select().from(billingObligations)
-      .where(and(eq(billingObligations.organisationId, organisationId), eq(billingObligations.invoiceId, invoice.id)))
-      .for('update');
-    if (linked.length && !actor) throw new FlowError('invalid', 'actor is required');
-    for (const obligation of linked) {
-      await tx.update(billingObligations)
-        .set({ invoiceId: null, draftBasis: null, updatedAt: sql`now()` })
-        .where(eq(billingObligations.id, obligation.id));
-      await tx.insert(obligationEvents).values({
-        createdAt: sql`clock_timestamp()`,
-        organisationId,
-        obligationId: obligation.id,
-        kind: 'draft_deleted',
-        actor,
-        evidence: { invoiceId: invoice.id },
-      });
-    }
-    try {
-      await tx.delete(invoices).where(eq(invoices.id, invoice.id));
-    } catch (error) {
-      const code = error?.code ?? error?.cause?.code;
-      if (code === '23503') throw new FlowError('conflict', 'this draft is still linked; remove the link, then delete it');
-      throw error;
-    }
-    return invoice;
+    const [row] = await tx.update(invoices).set({ status: 'void', updatedAt: sql`now()` })
+      .where(eq(invoices.id, invoice.id)).returning();
+    await freeJobs(tx, organisationId, row, actor);
+    return row;
   });
 }
 

package/server/core/sending.js

@@ -37,6 +37,13 @@ export const CHECK_LIMIT = 500;
 const WORKER_BATCH = 25;
 const WORKER_EVERY_MS = 30 * 1000;
 const LEASE_MS = 15 * 60 * 1000;
+// One error report names this many refused invoices. The count still says
+// how many the accounting system refused.
+const REFUSAL_REPORT_CAP = 5;
+const REFUSAL_MESSAGE_LIMIT = 160;
+const INVOICE_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const INVOICE_NUMBER = /^[A-Za-z0-9-]{1,32}$/;
+const REFUSAL_CODE = /^[a-z0-9_]{1,64}$/i;
 // Outcomes that mean the accounting system holds the invoice.
 const SENT = new Set(['created', 'reconciled', 'existing', 'already_in_xero']);
 
@@ -339,14 +346,65 @@ function unqueue(db, organisationId, invoiceId) {
     .where(and(eq(invoices.organisationId, organisationId), eq(invoices.id, invoiceId), eq(invoices.status, 'draft')));
 }
 
+// The short refusal message for an error report. An email address is dropped,
+// and so is a double-quoted name: Flow's own messages put a customer name in
+// quotes. Single quotes stay, because the accounting system quotes an account
+// code that way. The invoice's own problem, shown to a person, keeps the
+// full message.
+function refusalMessage(message) {
+  let text = String(message ?? '')
+    .replace(/[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/gi, '')
+    .replace(/"[^"\n]{0,240}"/g, '')
+    .replace(/\s+/g, ' ')
+    .replace(/\s+([.,;:])/g, '$1')
+    .trim();
+  // Dropping the address and the quoted name can leave an empty "See for."
+  text = text.replace(/(?:^|\.\s*)See for\.$/i, (match) => (match.startsWith('.') ? '.' : '')).trim();
+  return text.slice(0, REFUSAL_MESSAGE_LIMIT);
+}
+
+// One refused invoice, as the error report may name it. Anything that is not
+// an id, a number or a code is left out.
+function refusalFact(row, error) {
+  const invoiceId = INVOICE_ID.test(row?.id ?? '') ? row.id : null;
+  if (!invoiceId) return null;
+  const number = INVOICE_NUMBER.test(row?.number ?? '') ? row.number : null;
+  const code = REFUSAL_CODE.test(error?.code ?? '') ? error.code : 'send_failed';
+  const message = refusalMessage(error?.message);
+  return { invoiceId, ...(number ? { number } : {}), code, ...(message ? { message } : {}) };
+}
+
+function formatRefusal(item) {
+  const fact = refusalFact(
+    { id: item?.invoiceId, number: item?.number },
+    { code: item?.code, message: item?.message },
+  );
+  if (!fact) return null;
+  const who = fact.number ? `${fact.number} (${fact.invoiceId})` : fact.invoiceId;
+  return fact.message ? `${who} ${fact.code}: ${fact.message}` : `${who} ${fact.code}`;
+}
+
+// The line the error service gets when the accounting system refuses invoices.
+// `result` is the send pass summary (`failed`, `refusals`).
+export function refusalReport(result) {
+  const refusals = Array.isArray(result?.refusals) ? result.refusals : [];
+  const count = Number.isInteger(result?.failed) && result.failed > 0 ? result.failed : refusals.length;
+  const shown = refusals.slice(0, REFUSAL_REPORT_CAP).map(formatRefusal).filter(Boolean);
+  const hidden = Math.max(0, refusals.length - REFUSAL_REPORT_CAP);
+  const detail = [...shown, ...(hidden ? [`and ${hidden} more`] : [])].join('; ');
+  const word = count === 1 ? 'invoice' : 'invoices';
+  return `[sending] the accounting system refused ${count} ${word}${detail ? `: ${detail}` : ''}`;
+}
+
 // One pass of the send worker: up to `limit` queued invoices, oldest first.
 export async function sendQueued(db, organisationId, { accounting, limit = WORKER_BATCH }) {
-  const rows = await db.select({ id: invoices.id, by: invoices.sendRequestedBy }).from(invoices)
+  const rows = await db.select({ id: invoices.id, number: invoices.number, by: invoices.sendRequestedBy }).from(invoices)
     .where(and(eq(invoices.organisationId, organisationId), eq(invoices.status, 'issued'), eq(invoices.sendState, 'queued')))
     .orderBy(asc(invoices.sendUpdatedAt), asc(invoices.id))
     .limit(limit);
   const summary = { sent: 0, failed: 0, waiting: 0 };
   for (const [by, group] of Map.groupBy(rows, (r) => r.by ?? null)) {
+    const known = new Map(group.map((row) => [row.id, row]));
     const { invoices: results } = await accounting.capabilities.pushInvoices({
       organisationId, invoiceIds: group.map((r) => r.id), pushedBy: by,
     });
@@ -362,6 +420,8 @@ export async function sendQueued(db, organisationId, { accounting, limit = WORKE
         await settle(db, organisationId, result.invoiceId, { sendState: 'failed', sendError: { code: error.code, message: error.message } });
         summary.failed += 1;
         summary.refused = [...new Set([...(summary.refused ?? []), error.code])];
+        const fact = refusalFact(known.get(result.invoiceId), error);
+        if (fact) summary.refusals = [...(summary.refusals ?? []), fact];
       }
     }
   }
@@ -412,9 +472,10 @@ export function createSendWorker({ db, integrations, log = console, timers = { s
         if (!ran) return;
         const line = `[sending] ${ran.outcome}: ${JSON.stringify(ran.job.result ?? ran.job.lastError ?? {})}`;
         // An invoice the accounting system refused waits in Problem for a
-        // person; it is reported once, when it is refused.
+        // person. The error report names which invoices and why, once, when
+        // they are refused. The host log keeps the same pass on warn.
         if (ran.outcome === 'dead') log.error?.('[sending] the send run gave up after its last attempt');
-        if (ran.job.result?.failed) log.error?.('[sending] the accounting system refused an invoice');
+        if (ran.job.result?.failed) log.error?.(refusalReport(ran.job.result));
         (ran.outcome === 'succeeded' && !ran.job.result?.failed ? log.info : log.warn)?.(line);
       } catch (error) {
         log.error?.(`[sending] ${error?.code ?? 'error'}: ${error?.message ?? error}`);
@@ -436,5 +497,6 @@ export function createSendWorker({ db, integrations, log = console, timers = { s
       timer = null;
       await running;
     },
+    tick,
   };
 }

package/server/db/doctor.js

@@ -82,7 +82,7 @@ export async function diagnoseDatabase(pool, { adapters = [] } = {}) {
     .map((journal) => ({ journal: journal.id, applied: applied[journal.id], shipped: journal.tags.length, next: journal.tags.slice(applied[journal.id]) }));
 
   const { rows } = await pool.query(
-    "select table_name, column_name from information_schema.columns where table_schema = 'public'",
+    "select table_name, column_name from information_schema.columns where table_schema = current_schema()",
   );
   const actual = new Map();
   for (const row of rows) {

package/server/db/index.js

@@ -13,10 +13,28 @@ const migrationsFolder = fileURLToPath(new URL('./migrations', import.meta.url))
 export const MIGRATION_LOCK_KEY = 7_139_000_101n;
 const DEFAULT_MIGRATION_LOCK_TIMEOUT_MS = 300_000;
 
+// Flow's tables live in their own schema, not "public": Replit's publish
+// compares the workspace's "public" with production's and offers to make
+// production match, deletes included (migration 0021, docs/REPLIT.md). Every
+// connection searches "flow" first, so queries keep plain table names; the
+// database's own default says the same for a pooler's sessions.
+export const FLOW_SCHEMA = 'flow';
+export const FLOW_SEARCH_PATH = `${FLOW_SCHEMA}, public`;
+const setSearchPath = (client) => client.query(`set search_path to ${FLOW_SEARCH_PATH}`);
+
 // Opens Flow's PostgreSQL database. The caller owns the pool: call close().
 export function openDatabase({ url = process.env.DATABASE_URL, max = 10 } = {}) {
   if (!url) throw new Error('flow: DATABASE_URL is not set');
   const pool = new pg.Pool({ connectionString: url, max });
+  // A client runs its queries in order, so this comes before any other.
+  pool.on('connect', (client) => {
+    setSearchPath(client).catch(() => {});
+  });
+  // The server can close an idle connection (a restart, a pooler, migration
+  // 0021); the pool drops it and opens another. Unheard, it would stop Flow.
+  pool.on('error', (error) => {
+    console.warn(`[db] an idle database connection closed: ${error.message}`);
+  });
   const db = drizzle(pool, { schema });
   return { db, pool, close: () => pool.end() };
 }
@@ -56,6 +74,7 @@ export async function withMigrationLock(db, fn, { timeoutMs = migrationLockTimeo
   if (direct) {
     client = new pg.Client({ connectionString: direct });
     await client.connect();
+    await setSearchPath(client);
   } else {
     client = source instanceof pg.Pool ? await source.connect() : source;
   }

package/server/db/migrations/0021_flow_schema.sql

@@ -0,0 +1,68 @@
+-- Flow's tables move from "public" to their own schema, "flow" (issue: Replit's
+-- publish compares the workspace's "public" schema with production's and
+-- offers to make production match, deletes included; docs/REPLIT.md, "The
+-- workspace database"). Every connection searches "flow" first
+-- (server/db/index.js, FLOW_SEARCH_PATH), so queries keep their table names.
+-- The adapters' tables move too, when they exist; an adapter turned on later
+-- creates its tables in "flow". It runs again without harm.
+DO $flow_guard$
+DECLARE
+	t text;
+BEGIN
+	CREATE SCHEMA IF NOT EXISTS flow;
+	FOREACH t IN ARRAY ARRAY[
+		'alert_dismissals', 'automations', 'background_jobs', 'billing_obligations', 'contacts',
+		'customer_billing_settings', 'external_links', 'integration_setting_events', 'integration_settings',
+		'invoice_lines', 'invoice_rules', 'invoice_versions', 'invoices', 'invoicing_settings',
+		'job_field_events', 'job_field_settings', 'job_field_values', 'job_fields', 'line_mappings',
+		'link_rejections', 'link_suggestions', 'obligation_events', 'obligation_payments',
+		'obligation_writebacks', 'organisations', 'outbox', 'people', 'pipeline_cursors',
+		'price_item_links', 'price_items', 'prior_links', 'review_items',
+		'seazona_api_governor', 'seazona_api_requests', 'seazona_clients', 'seazona_history_batch_jobs',
+		'seazona_history_batches', 'seazona_history_jobs', 'seazona_history_rows', 'seazona_invoices',
+		'seazona_lane_state', 'seazona_order_read_failures', 'seazona_orders', 'seazona_person_settings',
+		'seazona_record_read_failures', 'seazona_reference', 'seazona_stage_moves', 'seazona_sweep_findings',
+		'xero_call_guard', 'xero_calls', 'xero_connections', 'xero_contacts', 'xero_credit_notes',
+		'xero_daily_checks', 'xero_import_settings', 'xero_invoice_links', 'xero_invoice_pushes',
+		'xero_invoices', 'xero_items', 'xero_mirror_cursors', 'xero_payment_cursors', 'xero_payments',
+		'xero_sync_runs', 'xero_webhook_events'
+	] LOOP
+		IF to_regclass(format('public.%I', t)) IS NOT NULL AND to_regclass(format('flow.%I', t)) IS NULL THEN
+			EXECUTE format('ALTER TABLE public.%I SET SCHEMA flow', t);
+		END IF;
+	END LOOP;
+	FOREACH t IN ARRAY ARRAY['flow_refuse_change', 'flow_invoice_lines_draft_only', 'flow_invoice_rules'] LOOP
+		IF to_regprocedure(format('public.%I()', t)) IS NOT NULL AND to_regprocedure(format('flow.%I()', t)) IS NULL THEN
+			EXECUTE format('ALTER FUNCTION public.%I() SET SCHEMA flow', t);
+		END IF;
+		-- The trigger functions name tables without a schema.
+		IF to_regprocedure(format('flow.%I()', t)) IS NOT NULL THEN
+			EXECUTE format('ALTER FUNCTION flow.%I() SET search_path = flow, public', t);
+		END IF;
+	END LOOP;
+	-- New sessions, a pooler's included, search "flow" first: a transaction
+	-- pooler does not keep a session's SET. Flow's role sets it for itself, and
+	-- the database too when Flow owns it; Flow's own connections set it anyway.
+	BEGIN
+		EXECUTE format('ALTER ROLE %I IN DATABASE %I SET search_path TO flow, public', current_user, current_database());
+	EXCEPTION WHEN insufficient_privilege THEN
+		RAISE NOTICE 'flow: this role cannot set its own search_path; Flow sets its own';
+	END;
+	BEGIN
+		EXECUTE format('ALTER DATABASE %I SET search_path TO flow, public', current_database());
+	EXCEPTION WHEN insufficient_privilege THEN
+		RAISE NOTICE 'flow: not the database owner, so its default search_path stays; Flow sets its own';
+	END;
+	-- A pooler keeps the server sessions it opened before this move, with the
+	-- old search_path, and hands them to new clients. Close the idle ones
+	-- of this role: the pooler opens new ones, which take the setting above.
+	BEGIN
+		PERFORM pg_terminate_backend(a.pid) FROM pg_stat_activity a
+		 WHERE a.datname = current_database() AND a.usename = current_user
+		   AND a.pid <> pg_backend_pid() AND a.state = 'idle' AND a.backend_type = 'client backend';
+	EXCEPTION WHEN others THEN
+		RAISE NOTICE 'flow: could not close the idle sessions; a pooler''s open sessions keep the old search_path until they close';
+	END;
+	-- This session too: the migrations after this one create their tables in "flow".
+	PERFORM set_config('search_path', 'flow, public', false);
+END $flow_guard$;