@arcforgelabs/flow 2026.11.8 → 2026.11.10

package/server/core/pipeline.js

@@ -1,5 +1,5 @@
 import { randomUUID } from 'node:crypto';
-import { and, eq, inArray, sql } from 'drizzle-orm';
+import { and, eq, inArray, isNull, sql } from 'drizzle-orm';
 import {
   billingObligations, contacts, externalLinks, linkRejections, linkSuggestions, obligationEvents, organisations, pipelineCursors,
 } from '../db/schema.js';
@@ -10,7 +10,7 @@ import { observeJob, observeWithdrawn, recordAccountingEvidence, setHold } from
 import { loadMappingContext, mapLines } from './line-mapping.js';
 import { checkPrices, readCatalogues } from './price-list.js';
 import { linkRecord, priorLinkFor } from './links.js';
-import { createContact, readContact } from './contacts.js';
+import { billedBy, createContact, payersOf, readContact } from './contacts.js';
 import { HISTORY_ACTOR, HISTORY_HOLD_REASON, isHistoryHeld } from './history.js';
 import { deadHoldSince, deadSince, enqueueJob, runNextJob } from './queue.js';
 
@@ -111,7 +111,10 @@ function byName(records) {
   for (const record of records) {
     const key = normaliseName(record.name);
     if (!key) continue;
-    map.set(key, [...(map.get(key) ?? []), record]);
+    const same = map.get(key) ?? [];
+    // A name and an alias of one contact are one record.
+    if (same.some((r) => r.id === record.id)) continue;
+    map.set(key, [...same, record]);
   }
   return map;
 }
@@ -122,8 +125,11 @@ function byName(records) {
 // contact, linked to it (`imported`), so its jobs find their customer
 // (docs/CONTACTS.md). Two customers of one name stay for a person.
 export async function linkCustomers(db, organisationId, { system, customers, adopt = false }) {
-  const flow = await db.select({ id: contacts.id, name: contacts.name }).from(contacts)
-    .where(and(eq(contacts.organisationId, organisationId), eq(contacts.kind, 'customer')));
+  // A merged contact is gone from the names; the kept one answers to its
+  // aliases too (docs/CONTACTS.md, "Merge two contacts").
+  const flow = (await db.select({ id: contacts.id, name: contacts.name, aliases: contacts.aliases }).from(contacts)
+    .where(and(eq(contacts.organisationId, organisationId), eq(contacts.kind, 'customer'), isNull(contacts.mergedIntoId))))
+    .flatMap((c) => [{ id: c.id, name: c.name }, ...(c.aliases ?? []).map((name) => ({ id: c.id, name }))]);
   const links = await activeLinks(db, organisationId, { system, entity: 'contact' });
   const linkedFlow = new Set(links.map((l) => l.flowId));
   const linkedExternal = new Set(links.map((l) => l.externalId));
@@ -183,6 +189,52 @@ async function adoptCustomer(db, organisationId, { system, customer }) {
   });
 }
 
+// Hidden contacts (docs/CONTACTS.md). A Flow customer that Flow made from an
+// accounting contact (`imported`) is a client only when something says so: the
+// accounting system marks that contact a customer (`customer`), a work system
+// has the client, or Flow holds a job or an invoice for it. `customers` is the
+// accounting system's list.
+//
+// - Each pass shows a hidden contact that has become a client.
+// - One time for an organisation, it hides the contacts that are none. After
+//   that only a person hides or shows one, so a person's choice stays.
+// - It waits while the work system (`workSystem`) has no client linked yet,
+//   so a client known only there is not hidden.
+// - An accounting contact that is not in the list (archived there) is not
+//   known to be no customer, so its Flow contact stays.
+const HIDDEN_CURSOR = 'contacts:hidden';
+export async function hideNonClients(db, organisationId, { system, customers, workSystem = null }) {
+  const marked = customers.filter((c) => c.customer).map((c) => String(c.id));
+  const listed = customers.map((c) => String(c.id));
+  const client = sql`(
+    exists (select 1 from billing_obligations o where o.organisation_id = c.organisation_id and o.contact_id = c.id)
+    or exists (select 1 from invoices i where i.organisation_id = c.organisation_id and i.contact_id = c.id)
+    or exists (select 1 from customer_billing_settings s where s.organisation_id = c.organisation_id
+      and (s.contact_id = c.id or s.bill_to_contact_id = c.id))
+    or exists (select 1 from external_links l where l.organisation_id = c.organisation_id and l.entity = 'contact'
+      and l.flow_id = c.id and l.state = 'active'
+      and (l.system <> ${system} or l.external_id = any(${sql.param(marked)}::text[]))))`;
+  const { rows: shown } = await db.execute(sql`update contacts c set hidden = false
+    where c.organisation_id = ${organisationId} and c.hidden and c.merged_into_id is null and ${client} returning c.id`);
+  const result = { shown: shown.length, hidden: 0 };
+  // An empty list proves nothing: the accounting copy has no contacts yet.
+  if (!customers.length || await readCursor(db, organisationId, HIDDEN_CURSOR)) return result;
+  if (workSystem) {
+    const { rows: [work] } = await db.execute(sql`select 1 as one from external_links where organisation_id = ${organisationId}
+      and system = ${workSystem} and entity = 'contact' and state = 'active' limit 1`);
+    if (!work) return result;
+  }
+  const { rows: hidden } = await db.execute(sql`update contacts c set hidden = true
+    where c.organisation_id = ${organisationId} and c.kind = 'customer' and not c.hidden
+      and exists (select 1 from external_links l where l.organisation_id = c.organisation_id and l.entity = 'contact'
+        and l.flow_id = c.id and l.state = 'active' and l.system = ${system} and l.matched_by = 'imported'
+        and l.external_id = any(${sql.param(listed)}::text[]))
+      and not ${client} returning c.id`);
+  await writeCursor(db, organisationId, HIDDEN_CURSOR, 'done');
+  result.hidden = hidden.length;
+  return result;
+}
+
 async function readCursor(db, organisationId, name) {
   const [row] = await db.select().from(pipelineCursors)
     .where(and(eq(pipelineCursors.organisationId, organisationId), eq(pipelineCursors.name, name)));
@@ -515,9 +567,16 @@ export async function matchJobs(db, organisationId, { accounting, work = null, n
     select accounting_ref, sum(total_cents)::bigint as cents from billing_obligations
     where organisation_id = ${organisationId} and accounting_ref is not null group by accounting_ref`);
   const taken = new Map(linked.map((r) => [r.accounting_ref, Number(r.cents)]));
-  // Each customer's unlinked jobs, so two jobs at the same price share out
+  // Bill to (docs/CONTACTS.md): a customer with a payer is billed under the
+  // payer's accounting contact, so its jobs look there, with the jobs of every
+  // other customer of that payer as one pool.
+  const payerOf = await payersOf(db, organisationId, due.map((o) => o.contactId));
+  const pools = await billedBy(db, organisationId, [...payerOf.values()]);
+  const poolOf = new Map();
+  for (const [payer, members] of pools) for (const member of members) poolOf.set(member, payer);
+  // Each pool's unlinked jobs, so two jobs at the same price share out
   // their invoices by date.
-  const contactIds = [...new Set(due.map((o) => o.contactId).filter(Boolean))];
+  const contactIds = [...poolOf.keys()];
   const open = contactIds.length
     ? await db.select({
       id: billingObligations.id, contactId: billingObligations.contactId, jobDate: billingObligations.jobDate,
@@ -529,7 +588,10 @@ export async function matchJobs(db, organisationId, { accounting, work = null, n
     ))
     : [];
   const rivalsOf = new Map();
-  for (const o of open) rivalsOf.set(o.contactId, [...(rivalsOf.get(o.contactId) ?? []), o]);
+  for (const o of open) {
+    const pool = poolOf.get(o.contactId);
+    rivalsOf.set(pool, [...(rivalsOf.get(pool) ?? []), o]);
+  }
   // The patient name the work system gives a job, read from its copy; only
   // PATIENT_READS jobs a pass may ask the work system itself.
   let reads = 0;
@@ -545,13 +607,14 @@ export async function matchJobs(db, organisationId, { accounting, work = null, n
 
   for (const obligation of due) {
     result.checked += 1;
+    const payer = obligation.contactId ? payerOf.get(obligation.contactId) : null;
     const { evidence, ranked, decision, reason } = await matchJob(db, organisationId, obligation, {
       accounting,
-      xeroContactId: obligation.contactId ? xeroContactOf.get(obligation.contactId) ?? null : null,
+      xeroContactId: payer ? xeroContactOf.get(payer) ?? null : null,
       mirror,
       rejected: rejectedFor.get(obligation.id) ?? new Set(),
       taken,
-      rivals: rivalsOf.get(obligation.contactId) ?? [],
+      rivals: payer ? rivalsOf.get(payer) ?? [] : [],
       patientOf,
     });
     await saveSuggestions(db, organisationId, obligation.id, accounting.id, ranked);
@@ -611,9 +674,10 @@ export async function runPipelineOnce(db, integrations, { now = new Date() } = {
   if (accounting) {
     if (typeof accounting.capabilities.listCustomers === 'function') {
       const adding = (await listAutomations(db, organisationId)).find((a) => a.key === 'add_xero_contacts');
-      summary.accountingCustomers = await linkCustomers(db, organisationId, {
-        system: accounting.id, customers: await accounting.capabilities.listCustomers({ organisationId }), adopt: Boolean(adding?.enabled),
-      });
+      const customers = await accounting.capabilities.listCustomers({ organisationId });
+      summary.accountingCustomers = await linkCustomers(db, organisationId, { system: accounting.id, customers, adopt: Boolean(adding?.enabled) });
+      // After the work system's clients are linked, so a real client stays.
+      summary.contacts = await hideNonClients(db, organisationId, { system: accounting.id, customers, workSystem: work?.id ?? null });
     }
     const settings = await readInvoicingSettings(db, organisationId);
     summary.matching = await matchJobs(db, organisationId, { accounting, work: work ?? null, now, staleDays: settings.staleDays });

package/server/db/migrations/0030_contact_hidden.sql

@@ -0,0 +1 @@
+ALTER TABLE "contacts" ADD COLUMN IF NOT EXISTS "hidden" boolean DEFAULT false NOT NULL;

package/server/db/migrations/0031_bill_to.sql

@@ -0,0 +1,10 @@
+ALTER TABLE "customer_billing_settings" ADD COLUMN IF NOT EXISTS "bill_to_contact_id" uuid;--> statement-breakpoint
+DO $flow_guard$ BEGIN
+	ALTER TABLE "customer_billing_settings" ADD CONSTRAINT "customer_billing_settings_bill_to_same_org" FOREIGN KEY ("organisation_id","bill_to_contact_id") REFERENCES "flow"."contacts"("organisation_id","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 INDEX IF NOT EXISTS "customer_billing_settings_bill_to" ON "customer_billing_settings" USING btree ("organisation_id","bill_to_contact_id");--> statement-breakpoint
+DO $flow_guard$ BEGIN
+	ALTER TABLE "customer_billing_settings" ADD CONSTRAINT "customer_billing_settings_bill_to_other" CHECK ("customer_billing_settings"."bill_to_contact_id" is null or "customer_billing_settings"."bill_to_contact_id" <> "customer_billing_settings"."contact_id");
+EXCEPTION WHEN duplicate_object OR duplicate_table OR invalid_table_definition THEN NULL;
+END $flow_guard$;

package/server/db/migrations/0032_contact_merge.sql

@@ -0,0 +1,12 @@
+ALTER TABLE "contacts" ADD COLUMN IF NOT EXISTS "merged_into_id" uuid;--> statement-breakpoint
+ALTER TABLE "contacts" ADD COLUMN IF NOT EXISTS "merged_at" timestamp with time zone;--> statement-breakpoint
+ALTER TABLE "contacts" ADD COLUMN IF NOT EXISTS "merged_by" text;--> statement-breakpoint
+ALTER TABLE "contacts" ADD COLUMN IF NOT EXISTS "aliases" jsonb DEFAULT '[]'::jsonb NOT NULL;--> statement-breakpoint
+DO $flow_guard$ BEGIN
+	ALTER TABLE "contacts" ADD CONSTRAINT "contacts_merged_into_same_org" FOREIGN KEY ("organisation_id","merged_into_id") REFERENCES "flow"."contacts"("organisation_id","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 "contacts" ADD CONSTRAINT "contacts_merged_into_other" CHECK ("contacts"."merged_into_id" is null or "contacts"."merged_into_id" <> "contacts"."id");
+EXCEPTION WHEN duplicate_object OR duplicate_table OR invalid_table_definition THEN NULL;
+END $flow_guard$;