@arcforgelabs/flow 2026.10.25 → 2026.10.27

package/server/core/invoicing-rules.js

@@ -0,0 +1,255 @@
+import { and, eq, inArray, isNull, sql } from 'drizzle-orm';
+import {
+  billingObligations, contacts, customerBillingSettings, invoicingSettings, SEND_MODES,
+} from '../db/schema.js';
+import { FlowError, notFound } from './errors.js';
+import { listRules, ruleReasons } from './invoice-rules.js';
+import { draftInvoiceForObligation } from './ledger.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
+// draft goes to the accounting system. Each rule is a setting of the
+// organisation; a customer can override some of them. The rules come from
+// the earlier lab app, where they were fixed in its code. When Flow drafts is
+// an automation (automations.js): Flow's own "ready to invoice" stage
+// triggers it, never another system's status.
+//
+// The ledger's own checks (ledger.js, draftBlockers) still guard every draft:
+// the job is not held, every line maps to a price item, it has a customer, the
+// accounting copy holds no invoice for it, and the work system's report is
+// recent. The lab's own checks are invoice rules it builds (invoice-rules.js);
+// the old job limit, practitioner and rush settings here only seed them.
+
+export const ACTOR = 'system:rules';
+const DRAFT_BATCH = 200;
+
+export const INVOICING_DEFAULTS = Object.freeze({
+  sendMode: 'accounting_draft',
+  staleDays: 90,
+  paymentTermsDays: 30,
+  requirePractitioner: false,
+  rushItemCode: null,
+  rushPercent: 20,
+});
+
+const CUSTOMER_DEFAULTS = Object.freeze({
+  billable: true, defaultPractitioner: null, autoDraft: null, sendMode: null, paymentTermsDays: null,
+});
+
+const pick = (row, keys) => Object.fromEntries(keys.map((k) => [k, row[k]]));
+const SETTING_KEYS = Object.keys(INVOICING_DEFAULTS);
+const CUSTOMER_KEYS = Object.keys(CUSTOMER_DEFAULTS);
+
+const invalid = (message) => new FlowError('invalid', message);
+
+function wholeNumber(value, name, min, max) {
+  if (!Number.isInteger(value) || value < min || value > max) throw invalid(`${name} must be a whole number from ${min} to ${max}`);
+  return value;
+}
+
+function flag(value, name) {
+  if (typeof value !== 'boolean') throw invalid(`${name} must be true or false`);
+  return value;
+}
+
+function shortText(value, name) {
+  if (value === null || value === '') return null;
+  if (typeof value !== 'string' || value.length > 200) throw invalid(`${name} must be text of 200 characters at most`);
+  return value.trim() || null;
+}
+
+function sendMode(value, name) {
+  if (!SEND_MODES.includes(value)) throw invalid(`${name} must be one of ${SEND_MODES.join(', ')}`);
+  return value;
+}
+
+// The organisation's settings as stored, or the defaults.
+export async function readInvoicingSettings(db, organisationId) {
+  const [row] = await db.select().from(invoicingSettings).where(eq(invoicingSettings.organisationId, organisationId));
+  return row ? pick(row, SETTING_KEYS) : { ...INVOICING_DEFAULTS };
+}
+
+function readSettingChanges(changes) {
+  if (!changes || typeof changes !== 'object' || Array.isArray(changes)) throw invalid('the settings must be an object');
+  const out = {};
+  for (const [key, value] of Object.entries(changes)) {
+    if (key === 'requirePractitioner') out[key] = flag(value, key);
+    else if (key === 'sendMode') out[key] = sendMode(value, key);
+    else if (key === 'staleDays') out[key] = wholeNumber(value, key, 1, 3650);
+    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 throw invalid(`unknown setting: ${key}`);
+  }
+  return out;
+}
+
+export async function saveInvoicingSettings(db, organisationId, changes, { personId = null } = {}) {
+  const fields = readSettingChanges(changes);
+  await db.insert(invoicingSettings)
+    .values({ organisationId, ...fields, updatedBy: personId })
+    .onConflictDoUpdate({ target: invoicingSettings.organisationId, set: { ...fields, updatedBy: personId, updatedAt: sql`now()` } });
+  return readInvoicingSettings(db, organisationId);
+}
+
+async function requireCustomer(db, organisationId, contactId) {
+  const [contact] = await db.select({ id: contacts.id, kind: contacts.kind }).from(contacts)
+    .where(and(eq(contacts.organisationId, organisationId), eq(contacts.id, contactId)));
+  if (!contact) throw notFound('customer');
+  if (contact.kind !== 'customer') throw invalid('invoicing settings are for a customer contact');
+}
+
+// One customer's own settings. A null value takes the organisation's setting.
+export async function readCustomerBilling(db, organisationId, contactId) {
+  await requireCustomer(db, organisationId, contactId);
+  const [row] = await db.select().from(customerBillingSettings)
+    .where(and(eq(customerBillingSettings.organisationId, organisationId), eq(customerBillingSettings.contactId, contactId)));
+  return row ? pick(row, CUSTOMER_KEYS) : { ...CUSTOMER_DEFAULTS };
+}
+
+export async function saveCustomerBilling(db, organisationId, contactId, changes, { personId = null } = {}) {
+  if (!changes || typeof changes !== 'object' || Array.isArray(changes)) throw invalid('the settings must be an object');
+  await requireCustomer(db, organisationId, contactId);
+  const fields = {};
+  for (const [key, value] of Object.entries(changes)) {
+    if (key === 'billable') fields[key] = flag(value, key);
+    else if (key === 'defaultPractitioner') fields[key] = shortText(value, key);
+    else if (key === 'autoDraft') fields[key] = value === null ? null : flag(value, key);
+    else if (key === 'sendMode') fields[key] = value === null ? null : sendMode(value, key);
+    else if (key === 'paymentTermsDays') fields[key] = value === null ? null : wholeNumber(value, key, 0, 365);
+    else throw invalid(`unknown setting: ${key}`);
+  }
+  await db.insert(customerBillingSettings)
+    .values({ organisationId, contactId, ...fields, updatedBy: personId })
+    .onConflictDoUpdate({
+      target: [customerBillingSettings.organisationId, customerBillingSettings.contactId],
+      set: { ...fields, updatedBy: personId, updatedAt: sql`now()` },
+    });
+  return readCustomerBilling(db, organisationId, contactId);
+}
+
+// The customers' own settings, by contact id.
+export async function customerBillingByContact(db, organisationId, contactIds) {
+  const ids = [...new Set(contactIds.filter(Boolean))];
+  if (!ids.length) return new Map();
+  const rows = await db.select().from(customerBillingSettings)
+    .where(and(eq(customerBillingSettings.organisationId, organisationId), inArray(customerBillingSettings.contactId, ids)));
+  return new Map(rows.map((r) => [r.contactId, pick(r, CUSTOMER_KEYS)]));
+}
+
+// The settings that apply to one customer: its own, else the organisation's.
+// `autoDraft` is the customer's own switch for the draft automation.
+export function effectiveSettings(settings, customer = CUSTOMER_DEFAULTS) {
+  const own = { ...CUSTOMER_DEFAULTS, ...customer };
+  return {
+    ...settings,
+    billable: own.billable,
+    defaultPractitioner: own.defaultPractitioner,
+    autoDraft: own.autoDraft ?? true,
+    sendMode: own.sendMode ?? settings.sendMode,
+    paymentTermsDays: own.paymentTermsDays ?? settings.paymentTermsDays,
+  };
+}
+
+// How one customer's checked drafts go to the accounting system.
+export async function sendModeFor(db, organisationId, contactId) {
+  const settings = await readInvoicingSettings(db, organisationId);
+  const customers = await customerBillingByContact(db, organisationId, [contactId]);
+  return effectiveSettings(settings, customers.get(contactId)).sendMode;
+}
+
+// What a job still waits on before Flow drafts it, as reasons a person can
+// read: Flow's own ready stage, then the lab's invoice rules (invoice-rules.js)
+// in their order. An empty list means the job may be drafted. `rules` is the
+// organisation's rules, read once per run with listRules.
+export function ruleBlockers(obligation, effective, { now = new Date(), rules = [] } = {}) {
+  const reasons = [];
+  if (!obligation.readyAt) reasons.push('the job is not marked ready to invoice');
+  return [...reasons, ...ruleReasons(rules, obligation, { customer: effective, now })];
+}
+
+function addDays(date, days) {
+  const at = new Date(`${date}T00:00:00Z`);
+  at.setUTCDate(at.getUTCDate() + days);
+  return at.toISOString().slice(0, 10);
+}
+
+const isoDay = (at) => `${at.getFullYear()}-${String(at.getMonth() + 1).padStart(2, '0')}-${String(at.getDate()).padStart(2, '0')}`;
+
+// The ledger's live check, answered from the accounting system's copy in Flow
+// instead of a call for each job: the copy is complete and was read lately,
+// the matcher checked the job after the copy last changed, and the copy holds
+// no invoice with the job's own invoice number.
+export function copyCheck(accounting, organisationId) {
+  return async (obligation) => {
+    const { complete, fresh, changedAt, invoices } = await accounting.capabilities.findInvoices({
+      organisationId,
+      numbers: obligation.sourceInvoiceRef ? [obligation.sourceInvoiceRef] : [],
+    });
+    if (!complete || !fresh) throw new Error('the accounting copy is not complete or not fresh');
+    if (obligation.accountingState !== 'not_found') return { state: obligation.accountingState, matchedBy: 'copy' };
+    if (changedAt && (!obligation.accountingCheckedAt || new Date(obligation.accountingCheckedAt) < changedAt)) {
+      throw new Error('the accounting copy changed after the job was last matched');
+    }
+    const sales = invoices.filter((i) => !['voided', 'deleted'].includes(i.state));
+    if (sales.length) return { state: sales[0].state, accountingRef: sales[0].id, matchedBy: 'copy' };
+    return { state: 'not_found', matchedBy: 'copy' };
+  };
+}
+
+// Drafts the invoice of each job that is ready to invoice and passes the
+// ledger's checks and every rule, except for customers whose drafting is off.
+// It writes only Flow's own records: the drafts wait in Flow for a person.
+// 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 }) {
+  const result = { drafted: 0, waiting: 0, off: 0, refused: 0 };
+  const settings = await readInvoicingSettings(db, organisationId);
+  const rules = await listRules(db, organisationId);
+  if (accounting) {
+    const mirror = await accounting.capabilities.findInvoices({ organisationId });
+    if (!mirror.complete || !mirror.fresh) return { ...result, skipped: 'the accounting copy is not complete or not fresh' };
+  }
+
+  const candidates = await db.select().from(billingObligations).where(and(
+    eq(billingObligations.organisationId, organisationId),
+    isNull(billingObligations.invoiceId),
+    sql`${billingObligations.readyAt} is not null`,
+    eq(billingObligations.holdState, 'none'),
+    accounting
+      ? eq(billingObligations.accountingState, 'not_found')
+      : inArray(billingObligations.accountingState, ['not_found', 'unknown']),
+    eq(billingObligations.mappingComplete, true),
+    sql`${billingObligations.contactId} is not null`,
+    // Newest first: a backlog of jobs that wait on a rule never hides new work.
+  )).orderBy(sql`${billingObligations.jobDate} desc nulls last`, billingObligations.id).limit(limit);
+  const customers = await customerBillingByContact(db, organisationId, candidates.map((o) => o.contactId));
+  const liveCheck = accounting ? copyCheck(accounting, organisationId) : null;
+  const invoiceDate = isoDay(now);
+
+  for (const obligation of candidates) {
+    const effective = effectiveSettings(settings, customers.get(obligation.contactId));
+    if (!effective.autoDraft) {
+      result.off += 1;
+      continue;
+    }
+    if (ruleBlockers(obligation, effective, { now, rules }).length) {
+      result.waiting += 1;
+      continue;
+    }
+    try {
+      await draftInvoiceForObligation(db, organisationId, obligation.id, {
+        liveCheck,
+        actor,
+        now,
+        dueDate: addDays(invoiceDate, effective.paymentTermsDays),
+      });
+      result.drafted += 1;
+    } catch (error) {
+      if (error.code !== 'not_ready') throw error;
+      result.refused += 1;
+    }
+  }
+  return result;
+}

package/server/core/ledger.js

@@ -8,16 +8,18 @@ import { createDraftInvoice } from './invoices.js';
 import { invoiceTotals, lineTotals } from './money.js';
 
 // The billing obligation ledger. One billable job in a work system is one
-// obligation. Its view (Ready, Pending, Held, Drafted, Invoiced, Paid, Review
-// required) comes only from the evidence stored on it, never from a fresh
+// obligation. Its view (In work, Ready, Pending, Held, Drafted, Invoiced,
+// Paid, Review required) comes only from the evidence stored on it, never from a fresh
 // guess, and each change of evidence is an event. To make a draft invoice is a
 // guarded transition that fails closed.
 
 // How old the work system's report of a job may be when Flow drafts its invoice.
 export const SOURCE_MAX_AGE_MS = 24 * 60 * 60 * 1000;
 
-// Ways to tie accounting evidence to a job that are exact, not a guess.
-export const EXACT_MATCHES = ['flow_invoice', 'source_invoice_ref', 'accounting_ref'];
+// Ways to tie accounting evidence to a job that are exact, not a guess:
+// `prior_link` is a link the earlier installation held, checked against the
+// accounting mirror; `person` is a link a person chose.
+export const EXACT_MATCHES = ['flow_invoice', 'source_invoice_ref', 'accounting_ref', 'prior_link', 'person'];
 
 const LINKED_STATES = ['drafted', 'authorised', 'part_paid', 'paid', 'voided', 'deleted'];
 
@@ -30,8 +32,11 @@ async function loadObligation(tx, organisationId, obligationId, { lock = false }
   return row;
 }
 
+// clock_timestamp, not now(): events written in one transaction keep their
+// order when they are read back by time.
 async function addEvent(tx, obligation, kind, actor, evidence = {}) {
   await tx.insert(obligationEvents).values({
+    createdAt: sql`clock_timestamp()`,
     organisationId: obligation.organisationId,
     obligationId: obligation.id,
     kind,
@@ -107,6 +112,8 @@ export async function observeJob(db, organisationId, job) {
       contactId: job.contactId ?? null,
       practitioner: job.practitioner ?? null,
       shippedOn: job.shippedOn ?? null,
+      jobDate: job.jobDate ?? null,
+      sourceStatus: job.sourceStatus ?? null,
       lines,
       lineFingerprint: fingerprint(lines),
       ...invoiceTotals(lines),
@@ -135,7 +142,9 @@ export async function observeJob(db, organisationId, job) {
     const changed = ['sourceInvoiceRef', 'caseRef', 'contactId', 'practitioner', 'shippedOn', 'lineFingerprint', 'totalCents']
       .filter((key) => String(existing[key] ?? '') !== String(facts[key] ?? ''));
     if (!changed.length) {
-      return update(tx, existing, { sourceSeenAt: seenAt, mappingComplete: facts.mappingComplete, lines });
+      return update(tx, existing, {
+        sourceSeenAt: seenAt, mappingComplete: facts.mappingComplete, lines, jobDate: facts.jobDate, sourceStatus: facts.sourceStatus,
+      });
     }
     const fields = { ...facts, sourceSeenAt: seenAt };
     if (existing.invoiceId && changed.some((key) => ['lineFingerprint', 'totalCents', 'contactId'].includes(key))) {
@@ -310,6 +319,20 @@ export async function recordWritebackResult(db, organisationId, writebackId, { o
   });
 }
 
+// Marks a job ready to invoice, or back in work. `actor` is a person or the
+// automation that decided. A job with an invoice stays as it is.
+export async function setReady(db, organisationId, obligationId, { ready = true, actor }) {
+  requireActor(actor);
+  return db.transaction(async (tx) => {
+    const obligation = await loadObligation(tx, organisationId, obligationId, { lock: true });
+    if (Boolean(obligation.readyAt) === ready) return obligation;
+    if (!ready && obligation.invoiceId) throw new FlowError('invalid', 'the job has an invoice already');
+    const row = await update(tx, obligation, ready ? { readyAt: sql`now()`, readyBy: actor } : { readyAt: null, readyBy: null });
+    await addEvent(tx, row, ready ? 'ready' : 'in_work', actor, {});
+    return row;
+  });
+}
+
 // Puts an obligation on hold, sends it to review, or releases it.
 export async function setHold(db, organisationId, obligationId, { holdState, reason = null, actor }) {
   requireActor(actor);
@@ -326,7 +349,9 @@ export async function setHold(db, organisationId, obligationId, { holdState, rea
 }
 
 // The obligation's view and the reasons for it, from its stored evidence only.
-export function ledgerView(obligation, { now = new Date(), sourceMaxAgeMs = SOURCE_MAX_AGE_MS } = {}) {
+// `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.
+export function ledgerView(obligation, { now = new Date(), sourceMaxAgeMs = SOURCE_MAX_AGE_MS, accounting = true } = {}) {
   const o = obligation;
   if (o.holdState === 'review') return { view: 'review_required', reasons: [o.holdReason ?? 'sent to review'] };
   if (['ambiguous', 'conflict'].includes(o.accountingState)) {
@@ -341,15 +366,20 @@ export function ledgerView(obligation, { now = new Date(), sourceMaxAgeMs = SOUR
     return { view: 'invoiced', reasons: [`invoice ${o.accountingRef} is ${o.accountingState.replace('_', ' ')}`] };
   }
   if (o.invoiceId || o.accountingState === 'drafted') return { view: 'drafted', reasons: ['a draft invoice exists'] };
-  const reasons = draftBlockers(o, { now, sourceMaxAgeMs });
+  const reasons = draftBlockers(o, { now, sourceMaxAgeMs, accounting });
+  // Flow's own stage: a job is in work until a person or an automation marks
+  // it ready to invoice (setReady).
+  if (!o.readyAt) return { view: 'in_work', reasons: ['the job is not marked ready to invoice', ...reasons] };
   return reasons.length ? { view: 'pending', reasons } : { view: 'ready', reasons: ['all checks pass'] };
 }
 
-function draftBlockers(o, { now, sourceMaxAgeMs }) {
+function draftBlockers(o, { now, sourceMaxAgeMs, accounting = true }) {
   const reasons = [];
   if (o.holdState !== 'none') reasons.push(`the job is ${o.holdState}`);
   if (o.invoiceId) reasons.push('the job already has an invoice');
-  if (o.accountingState === 'unknown') reasons.push('the accounting system was not checked');
+  if (o.accountingState === 'unknown') {
+    if (accounting) reasons.push('the accounting system was not checked');
+  }
   else if (o.accountingState !== 'not_found') reasons.push(`the accounting system reports ${o.accountingState}`);
   if (!o.mappingComplete) reasons.push('a line does not map to a price item');
   if (!o.contactId) reasons.push('the job has no customer contact');
@@ -362,15 +392,17 @@ function draftBlockers(o, { now, sourceMaxAgeMs }) {
 // 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,
+  liveCheck, actor, now = new Date(), sourceMaxAgeMs = SOURCE_MAX_AGE_MS, dueDate = null,
 }) {
   requireActor(actor);
-  if (typeof liveCheck !== 'function') throw new FlowError('invalid', 'liveCheck is required');
+  // A null liveCheck says no accounting system is connected (ledgerView).
+  if (liveCheck !== null && typeof liveCheck !== 'function') throw new FlowError('invalid', 'liveCheck must be a function, or null with no accounting system');
+  const accounting = liveCheck !== null;
   const outcome = await db.transaction(async (tx) => {
     const obligation = await loadObligation(tx, organisationId, obligationId, { lock: true });
-    const reasons = draftBlockers(obligation, { now, sourceMaxAgeMs });
+    const reasons = draftBlockers(obligation, { now, sourceMaxAgeMs, accounting });
     let live = null;
-    if (!reasons.length) {
+    if (!reasons.length && accounting) {
       try {
         live = await liveCheck(obligation);
       } catch (error) {
@@ -385,11 +417,15 @@ export async function draftInvoiceForObligation(db, organisationId, obligationId
     const invoice = await createDraftInvoice(tx, organisationId, {
       contactId: obligation.contactId,
       reference: obligation.caseRef ?? obligation.sourceJobRef,
+      dueDate,
       lines: obligation.lines.map(({ priceItemId, description, quantity, unitAmountCents, taxCode }) => (
         { priceItemId, description, quantity, unitAmountCents, taxCode }
       )),
     });
-    const row = await update(tx, obligation, { invoiceId: invoice.id, accountingCheckedAt: now });
+    // Drafting the invoice says the job is ready, whoever asked.
+    const row = await update(tx, obligation, {
+      invoiceId: invoice.id, accountingCheckedAt: now, ...(obligation.readyAt ? {} : { readyAt: now, readyBy: actor }),
+    });
     await addEvent(tx, row, 'drafted', actor, { invoiceId: invoice.id, totalCents: invoice.totalCents, live });
     return { obligation: row, invoice };
   });

package/server/core/links.js

@@ -8,12 +8,12 @@ import { openReview, resolveReviewFor } from './review.js';
 // Pushes, imports and the ledger read the link first; matching by name only
 // ever proposes one.
 //
-// A link is exact when Flow made the external record, or both sides carry the
-// same id. A name match is a guess: it stays `proposed` and opens a review item
+// A link is exact when Flow made the external record, both sides carry the
+// same id, or one record on each side has the same name. A looser name match is a guess: it stays `proposed` and opens a review item
 // until a person confirms it. A link is never deleted; a replaced one is
 // `superseded`.
 
-const EXACT = new Set(['created_by_flow', 'exact_id', 'imported', 'person']);
+const EXACT = new Set(['created_by_flow', 'exact_id', 'exact_name', 'imported', 'person']);
 
 function check({ entity, flowId, system, externalId, matchedBy }) {
   if (!LINK_ENTITIES.includes(entity)) throw new FlowError('invalid', `unknown link entity: ${entity}`);

package/server/core/monitoring.js

@@ -0,0 +1,34 @@
+// The logger every part of Flow writes to. It passes each line to the host's
+// own log first, unchanged, then sends each error to the error services that
+// are on (the `captureError` capability, docs/SENTRY.md). With none on, it is
+// the host's log. A line's leading "[tag]" is its source.
+//
+// `reporters()` answers the adapters to send to; it is read at each error,
+// so an integration turned on or off later is followed. A failure to send is
+// logged as a warning at most once a minute, never sent, so it cannot loop.
+export function createMonitoredLog({ log = console, reporters = () => [], now = Date.now }) {
+  let lastFailure = -Infinity;
+
+  function error(...args) {
+    log.error?.(...args);
+    const cause = args.find((arg) => arg instanceof Error) ?? null;
+    const message = args.map((arg) => (arg instanceof Error ? arg.message : String(arg))).join(' ');
+    const source = /^\[([a-z0-9_-]+)\]/i.exec(message)?.[1].toLowerCase() ?? 'server';
+    for (const adapter of reporters()) {
+      try {
+        adapter.capabilities.captureError({ message, source, error: cause });
+      } catch (failure) {
+        const at = now();
+        if (at - lastFailure < 60_000) continue;
+        lastFailure = at;
+        log.warn?.(`[monitoring] ${adapter.id} could not take an error: ${failure.message}`);
+      }
+    }
+  }
+
+  return {
+    info: (...args) => log.info?.(...args),
+    warn: (...args) => log.warn?.(...args),
+    error,
+  };
+}