@arcforgelabs/flow 2026.11.3 → 2026.11.5

package/server/core/invoices.js

@@ -111,7 +111,15 @@ export async function updateDraftInvoice(db, organisationId, invoiceId, changes)
         .where(eq(invoices.id, invoice.id)).returning();
     }
     if ('lines' in changes) {
-      row = await writeLines(tx, row, await resolveLines(tx, organisationId, changes.lines));
+      // `lines` may be a function of the draft's current lines, read under
+      // the lock, so a change made at the same time is not lost.
+      let lines = changes.lines;
+      if (typeof lines === 'function') {
+        const current = await tx.select().from(invoiceLines).where(eq(invoiceLines.invoiceId, invoice.id)).orderBy(asc(invoiceLines.position));
+        lines = lines(current);
+        if (lines === null) return row;
+      }
+      row = await writeLines(tx, row, await resolveLines(tx, organisationId, lines));
     }
     return row;
   });

package/server/core/invoicing-rules.js

@@ -1,6 +1,6 @@
 import { and, eq, inArray, isNull, sql } from 'drizzle-orm';
 import {
-  billingObligations, contacts, customerBillingSettings, invoicingSettings, SEND_MODES,
+  billingObligations, contacts, customerBillingSettings, externalLinks, invoicingSettings, SEND_MODES,
 } from '../db/schema.js';
 import { FlowError, notFound } from './errors.js';
 import { listRules, ruleReasons } from './invoice-rules.js';
@@ -214,20 +214,45 @@ const isoDay = (at) => `${at.getFullYear()}-${String(at.getMonth() + 1).padStart
 // 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) => {
+// no invoice with the job's own invoice number. Another customer's invoice
+// with the same number is not this job's: when the job's customer is linked to
+// an accounting contact (`db` given), only that contact's invoices count.
+// Send's window for the same client and Reference (xero/drafts.js).
+const SAME_REFERENCE_DAYS = 90;
+
+export function copyCheck(accounting, organisationId, { db = null } = {}) {
+  const contactOf = async (contactId) => {
+    if (!db || !contactId) return null;
+    const [link] = await db.select({ externalId: externalLinks.externalId }).from(externalLinks).where(and(
+      eq(externalLinks.organisationId, organisationId), eq(externalLinks.system, accounting.id),
+      eq(externalLinks.entity, 'contact'), eq(externalLinks.state, 'active'), eq(externalLinks.flowId, contactId),
+    ));
+    return link?.externalId ?? null;
+  };
+  return async (obligation, { reference = null } = {}) => {
     const { complete, fresh, changedAt, invoices } = await accounting.capabilities.findInvoices({
       organisationId,
       numbers: obligation.sourceInvoiceRef ? [obligation.sourceInvoiceRef] : [],
+      references: reference ? [reference] : [],
     });
     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));
+    const xeroContactId = await contactOf(obligation.contactId);
+    const live = invoices.filter((i) => !['voided', 'deleted'].includes(i.state));
+    const sameNumber = (i) => obligation.sourceInvoiceRef && String(i.number ?? '').toUpperCase() === obligation.sourceInvoiceRef.toUpperCase();
+    const sales = live.filter((i) => sameNumber(i) && (!xeroContactId || i.contactId === xeroContactId));
     if (sales.length) return { state: sales[0].state, accountingRef: sales[0].id, matchedBy: 'copy' };
+    // The same client and Reference as this draft, within Send's window: Send
+    // would stop it (xero/drafts.js), so the draft is not made. A person
+    // links the job to that invoice, or says it is another job.
+    const day = obligation.jobDate ? Date.parse(`${String(obligation.jobDate).slice(0, 10)}T00:00:00Z`) : Date.now();
+    const sameReference = reference && xeroContactId ? live.filter((i) => i.contactId === xeroContactId
+      && String(i.reference ?? '').toUpperCase() === reference.toUpperCase()
+      && (!i.issuedOn || Math.abs(Date.parse(`${String(i.issuedOn).slice(0, 10)}T00:00:00Z`) - day) <= SAME_REFERENCE_DAYS * 86_400_000)) : [];
+    if (sameReference.length) return { state: 'ambiguous', accountingRef: sameReference[0].id, matchedBy: 'reference' };
     return { state: 'not_found', matchedBy: 'copy' };
   };
 }
@@ -269,7 +294,7 @@ export async function autoDraftJobs(db, organisationId, { accounting = null, wor
   const customers = await customerBillingByContact(db, organisationId, contactIds);
   const names = await customerNames(db, organisationId, contactIds);
   const named = (contactId) => ({ ...effectiveSettings(settings, customers.get(contactId)), name: names.get(contactId) ?? null });
-  const liveCheck = accounting ? copyCheck(accounting, organisationId) : null;
+  const liveCheck = accounting ? copyCheck(accounting, organisationId, { db }) : null;
   const invoiceDate = isoDay(now);
   let accountingRead = null;
 

package/server/core/job-board.js

@@ -1,6 +1,6 @@
 import { and, eq, inArray, isNull } from 'drizzle-orm';
 import { contacts, invoices, priceItems, reviewItems } from '../db/schema.js';
-import { listRules, ruleWait } from './invoice-rules.js';
+import { listRules, ruleExceptionsFor, rulePending, ruleWait } from './invoice-rules.js';
 import { customerBillingByContact, effectiveSettings, readInvoicingSettings, ruleBlockers } from './invoicing-rules.js';
 import { REVIEW_CHANGED, listObligations } from './ledger.js';
 import { isHistoryHeld } from './history.js';
@@ -47,6 +47,20 @@ export async function describeObligations(db, organisationId, listed, { accounti
   const settings = await readInvoicingSettings(db, organisationId);
   const customers = await customerBillingByContact(db, organisationId, contactIds);
   const rules = await listRules(db, organisationId);
+  // A rule with an item to add also checks the job as the work system has it,
+  // from the first read: the lab prints from the work system, so it must be
+  // right there, not only on Flow's invoice. The card says what to add.
+  const addRules = rules.filter((r) => r.action.kind === 'pending' && r.action.addItem);
+  const excepted = addRules.length ? await ruleExceptionsFor(db, organisationId, listed.map((e) => e.obligation.id)) : new Map();
+  const sourceNeeds = (o) => {
+    if (!addRules.length) return [];
+    const customer = { ...effectiveSettings(settings, customers.get(o.contactId)), name: nameOf.get(o.contactId) ?? null };
+    // The work system's own lines count as having the item, whatever the
+    // rule's conditions say, so the badge shows only while the item is missing there.
+    const inSource = (o.lines ?? []).flatMap((l) => [l.itemCode, l.label].filter(Boolean));
+    return rulePending(addRules, { ...o, ruleExceptions: excepted.get(o.id) ?? [], draftItems: inSource }, { customer })
+      .map((p) => ({ rule: p.rule, item: p.addItem, note: p.message, short: p.short }));
+  };
   const ready = new Set(views?.ready ?? []);
   const toCheck = new Set(views?.toCheck ?? []);
   const invoiceView = (id) => (!id || !views ? null
@@ -74,6 +88,7 @@ export async function describeObligations(db, organisationId, listed, { accounti
     invoiceProblems: (o.invoiceId && views?.problems.get(o.invoiceId)) || [],
     view,
     reasons,
+    sourceNeeds: sourceNeeds(o),
     ...waiting(o, view),
   }));
 }

package/server/core/ledger.js

@@ -149,7 +149,14 @@ export function sourceBillingProblems(obligation) {
   const lines = obligation.lines ?? [];
   if (lines.some((line) => line.taxCode === null)) reasons.push('a source line has unknown tax treatment');
   const calculated = invoiceTotals(lines);
-  if (SOURCE_TOTAL_FIELDS.some((field) => obligation.sourceTotals?.[field] != null && obligation.sourceTotals[field] !== calculated[field])) {
+  const source = obligation.sourceTotals ?? {};
+  // When the source total and GST both match Flow's lines, Flow's subtotal is
+  // their difference, so a different source subtotal (Seazona can send 0) is a
+  // fault in that one source field, not a wrong invoice. It stays in evidence.
+  const totalAndTaxMatch = source.totalCents != null && source.taxCents != null
+    && source.totalCents === calculated.totalCents && source.taxCents === calculated.taxCents;
+  const compared = totalAndTaxMatch ? ['taxCents', 'totalCents'] : SOURCE_TOTAL_FIELDS;
+  if (compared.some((field) => source[field] != null && source[field] !== calculated[field])) {
     reasons.push('the source invoice totals differ from the reconstructed lines');
   }
   return reasons;
@@ -970,7 +977,9 @@ export async function draftInvoiceForObligation(db, organisationId, obligationId
     let live = null;
     if (!reasons.length && accounting) {
       try {
-        live = await liveCheck(obligation);
+        // The draft's own Reference too: Send stops the same client and
+        // Reference in Xero, so the draft must not be made either.
+        live = await liveCheck(obligation, { reference });
       } catch (error) {
         reasons.push(`the live accounting check failed: ${error.message}`);
       }

package/server/core/reconcile.js

@@ -30,6 +30,9 @@ export const RECONCILE_REVIEW_KIND = 'reconcile.day';
 export const ACTOR = 'system:reconcile';
 export const RECONCILE_DAYS = 60;
 export const EVIDENCE_IDS = 20;
+// A job ready this long with no invoice in Flow or the accounting system,
+// and no hold, is a difference: something stops it that nobody sees.
+export const READY_GRACE_DAYS = 3;
 const RUN_EVERY_MS = 24 * 60 * 60 * 1000;
 const RECHECK_MS = 60 * 60 * 1000;
 const TICK_MS = 10 * 60 * 1000;
@@ -55,7 +58,7 @@ function emptyDay(day) {
     flowInvoices: { count: 0, totalCents: 0 },
     accounting: { linked: 0, found: 0, totalCents: 0 },
     differences: {
-      missingInLedger: [], missingInWork: [], missingInAccounting: [], accountingTotalDiffers: [],
+      missingInLedger: [], missingInWork: [], missingInAccounting: [], accountingTotalDiffers: [], readyNotInvoiced: [],
     },
   };
 }
@@ -76,7 +79,7 @@ const moneyAtRisk = (entry) => Object.values(entry.differences).flat()
   .reduce((cents, d) => cents + Math.abs(d.cents ?? 0), 0);
 
 // One pass over Flow's own tables. Answers one entry per day, oldest first.
-export async function reconcileDays(db, organisationId, { integrations, from, to }) {
+export async function reconcileDays(db, organisationId, { integrations, from, to, now = Date.now() }) {
   const byDay = new Map();
   const dayOf = (day) => {
     if (!byDay.has(day)) byDay.set(day, emptyDay(day));
@@ -110,6 +113,8 @@ export async function reconcileDays(db, organisationId, { integrations, from, to
     accountingState: billingObligations.accountingState,
     accountingRef: billingObligations.accountingRef,
     invoiceId: billingObligations.invoiceId,
+    readyAt: billingObligations.readyAt,
+    holdState: billingObligations.holdState,
     invoiceStatus: invoices.status,
     invoiceTotalCents: invoices.totalCents,
   })
@@ -148,6 +153,9 @@ export async function reconcileDays(db, organisationId, { integrations, from, to
     if (o.invoiceId) {
       entry.flowInvoices.count += 1;
       entry.flowInvoices.totalCents += o.invoiceTotalCents ?? 0;
+    } else if (!o.accountingRef && o.holdState === 'none' && o.readyAt
+      && new Date(o.readyAt).getTime() < now - READY_GRACE_DAYS * 86_400_000) {
+      entry.differences.readyNotInvoiced.push({ id: o.id, cents: o.totalCents });
     }
     // Only a work system that is on can say a job is gone from its copy.
     if (reported.has(o.sourceSystem)) {
@@ -217,7 +225,7 @@ export async function runReconcile(db, organisationId, {
   const open = await openDayItems(db, organisationId);
   // An open item older than the window is checked too, so it can close.
   const oldest = [...open.keys()].reduce((min, day) => (day < min ? day : min), isoDay(now - (days - 1) * 86_400_000));
-  const { systems, days: entries } = await reconcileDays(db, organisationId, { integrations, from: oldest, to });
+  const { systems, days: entries } = await reconcileDays(db, organisationId, { integrations, from: oldest, to, now });
   const differing = entries.filter((e) => differenceCount(e) > 0);
   const recheck = new Set(unconfirmed);
   const firstSeen = [];

package/server/core/sending.js

@@ -1,8 +1,8 @@
 import { randomUUID } from 'node:crypto';
 import { and, asc, desc, eq, inArray, sql } from 'drizzle-orm';
-import { billingObligations, contacts, invoiceLines, invoices, people } from '../db/schema.js';
+import { billingObligations, contacts, invoiceLines, invoices, people, priceItems } from '../db/schema.js';
 import { FlowError } from './errors.js';
-import { listRules, ruleNonChargeable, rulePending, ruleSkip } from './invoice-rules.js';
+import { listRules, ruleExceptionsFor, ruleNonChargeable, rulePending, ruleSkip } from './invoice-rules.js';
 import { customerBillingByContact, effectiveSettings, readInvoicingSettings } from './invoicing-rules.js';
 import { issueInvoice } from './invoices.js';
 import { CHANGED_REASON, diffJobLines, sourceBillingProblems, STATUS_BACK_REASON } from './ledger.js';
@@ -111,9 +111,20 @@ async function checkDrafts(db, organisationId, drafts, accounting) {
   if (rules.length && jobs.length) {
     const settings = await readInvoicingSettings(db, organisationId);
     const customers = await customerBillingByContact(db, organisationId, jobs.map((j) => j.obligation.contactId));
+    const exceptions = await ruleExceptionsFor(db, organisationId, jobs.map((j) => j.obligation.id));
+    // A rule's item counts only on a charged line: an item edited to $0
+    // does not satisfy the rule; Skip, with a reason, is the way to say so.
+    const itemRows = await db.select({ invoiceId: invoiceLines.invoiceId, code: priceItems.code }).from(invoiceLines)
+      .innerJoin(priceItems, eq(priceItems.id, invoiceLines.priceItemId))
+      .where(and(inArray(invoiceLines.invoiceId, jobs.map((j) => j.obligation.invoiceId)), sql`${invoiceLines.unitAmountCents} * ${invoiceLines.quantity} > 0`));
+    const itemsOf = Map.groupBy(itemRows, (r) => r.invoiceId);
     for (const { obligation, reference, customerName } of jobs) {
       const customer = { ...effectiveSettings(settings, customers.get(obligation.contactId)), name: customerName ?? null };
-      const job = { ...obligation, reference };
+      const job = {
+        ...obligation, reference,
+        ruleExceptions: exceptions.get(obligation.id) ?? [],
+        draftItems: (itemsOf.get(obligation.invoiceId) ?? []).map((r) => r.code),
+      };
       const found = [...ruleNonChargeable(rules, job, { customer }), ...rulePending(rules, job, { customer }), ...ruleSkip(rules, job, { customer })];
       if (found.length) problems.set(obligation.invoiceId, [...(problems.get(obligation.invoiceId) ?? []), ...found]);
     }

package/server/db/migrations/0027_high_doctor_strange.sql

@@ -0,0 +1,24 @@
+CREATE TABLE IF NOT EXISTS "invoice_rule_exceptions" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"organisation_id" uuid NOT NULL,
+	"rule_id" uuid NOT NULL,
+	"obligation_id" uuid NOT NULL,
+	"reason" text NOT NULL,
+	"actor" text NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "invoice_rule_exceptions_reason_valid" CHECK (length("invoice_rule_exceptions"."reason") between 1 and 200)
+);
+--> statement-breakpoint
+DO $flow_guard$ BEGIN
+	ALTER TABLE "invoice_rule_exceptions" ADD CONSTRAINT "invoice_rule_exceptions_organisation_id_organisations_id_fk" FOREIGN KEY ("organisation_id") REFERENCES "flow"."organisations"("id") ON DELETE no action ON UPDATE no action;
+EXCEPTION WHEN duplicate_object OR duplicate_table OR invalid_table_definition THEN NULL;
+END $flow_guard$;--> statement-breakpoint
+DO $flow_guard$ BEGIN
+	ALTER TABLE "invoice_rule_exceptions" ADD CONSTRAINT "invoice_rule_exceptions_rule_id_invoice_rules_id_fk" FOREIGN KEY ("rule_id") REFERENCES "flow"."invoice_rules"("id") ON DELETE cascade ON UPDATE no action;
+EXCEPTION WHEN duplicate_object OR duplicate_table OR invalid_table_definition THEN NULL;
+END $flow_guard$;--> statement-breakpoint
+DO $flow_guard$ BEGIN
+	ALTER TABLE "invoice_rule_exceptions" ADD CONSTRAINT "invoice_rule_exceptions_obligation_id_billing_obligations_id_fk" FOREIGN KEY ("obligation_id") REFERENCES "flow"."billing_obligations"("id") ON DELETE no action ON UPDATE no action;
+EXCEPTION WHEN duplicate_object OR duplicate_table OR invalid_table_definition THEN NULL;
+END $flow_guard$;--> statement-breakpoint
+CREATE UNIQUE INDEX IF NOT EXISTS "invoice_rule_exceptions_rule_job" ON "invoice_rule_exceptions" USING btree ("rule_id","obligation_id");

package/server/db/migrations/0028_sharp_power_pack.sql

@@ -0,0 +1,2 @@
+ALTER TABLE "invoice_rule_exceptions" ADD COLUMN IF NOT EXISTS "item_code" text;--> statement-breakpoint
+ALTER TABLE "invoice_rule_exceptions" ADD COLUMN IF NOT EXISTS "line_fingerprint" text;