@arcforgelabs/flow 2026.10.47 → 2026.10.48-1

package/server/db/migrations/meta/_journal.json

@@ -148,6 +148,20 @@
       "when": 1792507133665,
       "tag": "0020_custom_field_colours",
       "breakpoints": true
+    },
+    {
+      "idx": 21,
+      "version": "7",
+      "when": 1792667751284,
+      "tag": "0021_flow_schema",
+      "breakpoints": true
+    },
+    {
+      "idx": 22,
+      "version": "7",
+      "when": 1792733287865,
+      "tag": "0022_contacts",
+      "breakpoints": true
     }
   ]
 }

package/server/db/schema.js

@@ -41,13 +41,28 @@ export const organisations = pgTable('organisations', {
   check('organisations_next_invoice_number_positive', sql`${t.nextInvoiceNumber} > 0`),
 ]);
 
+// A contact is Flow's own client or supplier (docs/CONTACTS.md). The fields
+// cover what Xero needs to bill the contact and what Seazona keeps for the
+// practice a job belongs to. Practitioners are people at the practice, never
+// patients. An integration keeps its own copy; this row does not.
 export const contacts = pgTable('contacts', {
   id: id(),
   organisationId: organisationId().references(() => organisations.id),
   kind: text('kind').notNull(),
   name: text('name').notNull(),
+  firstName: text('first_name'),
+  lastName: text('last_name'),
   email: text('email'),
+  phone: text('phone'),
+  mobile: text('mobile'),
+  accountNumber: text('account_number'),
+  taxNumber: text('tax_number'),
+  taxRate: text('tax_rate'),
+  address: jsonb('address'),
+  practitioners: jsonb('practitioners').notNull().default([]),
+  active: boolean('active').notNull().default(true),
   createdAt: createdAt(),
+  updatedAt: updatedAt(),
 }, (t) => [
   unique('contacts_org_id').on(t.organisationId, t.id),
   unique('contacts_org_kind_name').on(t.organisationId, t.kind, t.name),

package/server/integrations/port.js

@@ -15,6 +15,7 @@ export const CAPABILITIES = Object.freeze([
   'pullHistoryJobs', // past work from a history import, as ledger jobs marked historical (Seazona: its API backfill)
   'pushInvoice', // send an issued invoice; the Flow record id is the idempotency key
   'pushInvoices', // send several issued invoices in one pass (Send all ready, server/core/sending.js)
+  'deleteInvoice', // { organisationId, invoiceId, actor }: read the accounting invoice live, then delete it only while it is still a draft. Answers { state: deleted | gone | approved | unavailable, status, message? }. deleted: it was deleted now. gone: it was already deleted or voided, and nothing was written. approved: it is approved or paid; nothing was written. unavailable: it cannot be deleted. The core voids the Flow invoice only after deleted or gone.
   'checkDrafts', // the accounting system's problems with Flow drafts, from its copy; null while not connected
   'invoiceStages', // { organisationId, invoiceIds? }: Map(invoiceId -> draft | approved | sent | void | pending) for issued invoices, from its copy
   'documentFacts', // what the customer's copy of a sent invoice says (number, reference, dates), from the system's copy in Flow; never a live call
@@ -32,6 +33,7 @@ export const CAPABILITIES = Object.freeze([
   'setPersonSetting', // { personId, key, value }: change one, answers the new list
   'jobIssues', // open issues the integration holds for jobs, by job ref: a short phrase and the page where a person fixes it
   'listCustomers', // the system's customers, by id and name, for the identity map (Seazona: clients; Xero: contacts)
+  'createCustomer', // { organisationId, contactId, actor }: create the system's customer from the Flow contact. Answers { outcome, contact }. Xero, when Create missing clients is on.
   'findInvoices', // sales invoices in the accounting system's copy, for the matcher; never a live call
   'readChanges', // { state: fresh | read | unavailable }: the accounting system's latest changes into its copy now, just before Flow drafts or sends (read before act)
   'listPriceItems', // the system's own price list from its copy in Flow, for the price list's links and check; never a live call

package/server/integrations/schema.js

@@ -13,11 +13,12 @@ export function migrationsTable(adapter) {
   return `__drizzle_migrations_${adapter.id.replaceAll('-', '_')}`;
 }
 
-// The adapter's declared tables that do not exist.
+// The adapter's declared tables that do not exist where Flow's connections
+// look (FLOW_SEARCH_PATH, server/db/index.js).
 export async function missingAdapterTables(db, adapter) {
   const missing = [];
   for (const table of adapter.schema.tables) {
-    const { rows } = await db.execute(sql`select to_regclass(${`public.${table}`}) is null as missing`);
+    const { rows } = await db.execute(sql`select to_regclass(${`"${table.replaceAll('"', '""')}"`}) is null as missing`);
     if (rows[0].missing) missing.push(table);
   }
   return missing;

package/server/integrations/seazona/sweep.js

@@ -36,7 +36,7 @@ import {
 //             withdraws it, so its invoice goes to review.
 //   clients   the whole list (GET clients/?lastModified=), read on from the
 //             last row when it is full.
-//   invoices  every change since the oldest invoice Flow holds, read on the
+//   invoices  every change since the invoice lane first read, read on the
 //             same way.
 //
 // A client or invoice that Flow holds and the whole list leaves out is read
@@ -282,12 +282,15 @@ const WHOLE_LISTS = {
     list: (client, since) => client.get('invoices/', { lastModified: since }),
     // The guide: on or after lastModified (inclusive).
     stepBackMs: 0,
-    // A day before the oldest change Flow holds: an invoice older than that
-    // was never in Flow's copy, so it cannot be missing from it.
-    async firstSince(db) {
-      const [{ oldest }] = await db.select({ oldest: sql`min(${seazonaInvoices.lastModifiedText})` }).from(seazonaInvoices);
-      const oldestMs = parseUtc(oldest);
-      return Number.isFinite(oldestMs) ? new Date(floorUtcDay(oldestMs) - DAY_MS).toISOString() : null;
+    // Where the invoice lane first read: the start of the UTC day of its
+    // first run, less SEAZONA_INVOICE_LOOKBACK_DAYS (lanes.js). An invoice
+    // last changed before that was never the lane's to read, so it is not a
+    // miss (FLOW-HORIZON-K: a day's margin before it counted such invoices).
+    // The first row Flow stored marks the first run.
+    async firstSince(db, sync) {
+      const [{ first }] = await db.select({ first: sql`min(${seazonaInvoices.firstSeenAt})` }).from(seazonaInvoices);
+      const firstMs = first ? new Date(first).getTime() : NaN;
+      return Number.isFinite(firstMs) ? new Date(floorUtcDay(firstMs) - sync.invoiceLookbackDays * DAY_MS).toISOString() : null;
     },
   },
 };
@@ -416,7 +419,7 @@ async function sweepWholeList(ctx, resource, cursor, laneStates, helpers, found)
   const readsFrom = laneReadsFrom(laneStates.get(resource), sync);
   if (readsFrom === null) return;
   if (!cursor[resource]?.cycleStartedAt) {
-    const since = await spec.firstSince(db);
+    const since = await spec.firstSince(db, sync);
     if (since === null) {
       cursor[resource] = { lastFinishedAt: at.toISOString(), listed: 0 };
       return;

package/server/integrations/setup.js

@@ -81,6 +81,7 @@ export function describeSetup({ adapter, row, env, secrets, entry, unreadable =
       help: field.help ?? null,
       choices: field.choices ?? null,
       suggest: field.suggest ?? null,
+      default: field.default ?? null,
       source: fromHost ? 'host' : null,
     };
     if (field.secret) {

package/server/integrations/xero/catalogue.js

@@ -1,11 +1,13 @@
 import { sql } from 'drizzle-orm';
+import { externalIdFor } from '../../core/links.js';
 import { withXeroLane } from './governor.js';
 
-// Flow's copy of a connected organisation's Xero contacts and items. Xero
-// owns them: Flow never creates or changes a Xero contact or item. A sync
+// Flow's copy of a connected organisation's Xero contacts and items. A sync
 // reads them all (a few calls: contacts 100 a page, items in one) and
 // replaces the copy in one transaction, so invoice preview can match
-// contacts and item codes without spending Xero calls.
+// contacts and item codes without spending Xero calls. Creating a missing
+// client (create-contact.js) writes one row into this copy; it does not
+// change any other Xero contact. Flow never changes a Xero item.
 
 // Xero dates come as "/Date(1792000000000+0000)/" or ISO text.
 export function parseXeroDate(value) {
@@ -22,12 +24,45 @@ export function normaliseName(value) {
 }
 
 const toCents = (amount) => (typeof amount === 'number' && Number.isFinite(amount) ? Math.round(amount * 100) : null);
+const blank = (value) => {
+  const text = String(value ?? '').trim();
+  return text || null;
+};
+
+function phoneOf(contact, type) {
+  const phone = (contact.Phones ?? []).find((item) => item.PhoneType === type);
+  if (!phone) return null;
+  return [phone.PhoneCountryCode, phone.PhoneAreaCode, phone.PhoneNumber].map(blank).filter(Boolean).join(' ') || null;
+}
+
+function addressOf(contact) {
+  const list = contact.Addresses ?? [];
+  const raw = list.find((item) => item.AddressType === 'POBOX') ?? list.find((item) => item.AddressType === 'STREET');
+  if (!raw) return null;
+  const address = {
+    line1: blank(raw.AddressLine1),
+    line2: blank(raw.AddressLine2),
+    city: blank(raw.City),
+    region: blank(raw.Region),
+    postalCode: blank(raw.PostalCode),
+    country: blank(raw.Country),
+  };
+  const kept = Object.fromEntries(Object.entries(address).filter(([, value]) => value));
+  return Object.keys(kept).length ? kept : null;
+}
 
 export function mapContact(contact) {
   return {
     xeroContactId: contact.ContactID,
     name: String(contact.Name ?? '').trim(),
+    firstName: blank(contact.FirstName),
+    lastName: blank(contact.LastName),
     email: contact.EmailAddress || null,
+    phone: phoneOf(contact, 'DEFAULT'),
+    mobile: phoneOf(contact, 'MOBILE'),
+    accountNumber: blank(contact.AccountNumber),
+    taxNumber: blank(contact.TaxNumber),
+    address: addressOf(contact),
     status: contact.ContactStatus || 'ACTIVE',
     isCustomer: Boolean(contact.IsCustomer),
     isSupplier: Boolean(contact.IsSupplier),
@@ -50,19 +85,30 @@ export function mapItem(item) {
   };
 }
 
+export async function upsertContact(db, organisationId, contact) {
+  const address = contact.address ? JSON.stringify(contact.address) : null;
+  await db.execute(sql`
+    insert into xero_contacts (
+      organisation_id, xero_contact_id, name, first_name, last_name, email, phone, mobile,
+      account_number, tax_number, address, status, is_customer, is_supplier, sales_tracking, xero_updated_at, synced_at)
+    values (
+      ${organisationId}, ${contact.xeroContactId}, ${contact.name}, ${contact.firstName ?? null}, ${contact.lastName ?? null},
+      ${contact.email ?? null}, ${contact.phone ?? null}, ${contact.mobile ?? null}, ${contact.accountNumber ?? null},
+      ${contact.taxNumber ?? null}, ${address}::jsonb, ${contact.status}, ${contact.isCustomer}, ${contact.isSupplier},
+      ${JSON.stringify(contact.salesTracking ?? [])}::jsonb, ${contact.xeroUpdatedAt ?? null}, now())
+    on conflict (organisation_id, xero_contact_id) do update set
+      name = excluded.name, first_name = excluded.first_name, last_name = excluded.last_name, email = excluded.email,
+      phone = excluded.phone, mobile = excluded.mobile, account_number = excluded.account_number,
+      tax_number = excluded.tax_number, address = excluded.address, status = excluded.status,
+      is_customer = excluded.is_customer, is_supplier = excluded.is_supplier, sales_tracking = excluded.sales_tracking,
+      xero_updated_at = excluded.xero_updated_at, synced_at = now()`);
+}
+
 async function replaceContacts(tx, organisationId, contacts) {
   const ids = contacts.map((c) => c.xeroContactId);
   await tx.execute(sql`delete from xero_contacts where organisation_id = ${organisationId}
     and not (xero_contact_id = any(${sql.param(ids)}::text[]))`);
-  for (const c of contacts) {
-    await tx.execute(sql`
-      insert into xero_contacts (organisation_id, xero_contact_id, name, email, status, is_customer, is_supplier, sales_tracking, xero_updated_at, synced_at)
-      values (${organisationId}, ${c.xeroContactId}, ${c.name}, ${c.email}, ${c.status}, ${c.isCustomer}, ${c.isSupplier}, ${JSON.stringify(c.salesTracking)}::jsonb, ${c.xeroUpdatedAt}, now())
-      on conflict (organisation_id, xero_contact_id) do update set
-        name = excluded.name, email = excluded.email, status = excluded.status, is_customer = excluded.is_customer,
-        is_supplier = excluded.is_supplier, sales_tracking = excluded.sales_tracking,
-        xero_updated_at = excluded.xero_updated_at, synced_at = now()`);
-  }
+  for (const contact of contacts) await upsertContact(tx, organisationId, contact);
 }
 
 async function replaceItems(tx, organisationId, items) {
@@ -129,7 +175,14 @@ export async function lastSuccessfulSyncAt(db, organisationId) {
 const contactRow = (row) => ({
   xeroContactId: row.xero_contact_id,
   name: row.name,
+  firstName: row.first_name ?? null,
+  lastName: row.last_name ?? null,
   email: row.email,
+  phone: row.phone ?? null,
+  mobile: row.mobile ?? null,
+  accountNumber: row.account_number ?? null,
+  taxNumber: row.tax_number ?? null,
+  address: row.address ?? null,
   status: row.status,
   isCustomer: row.is_customer,
   isSupplier: row.is_supplier,
@@ -171,8 +224,9 @@ export async function itemsByCode(db, organisationId, codes) {
 }
 
 // The Xero contact for a Flow contact name: exactly one active contact with
-// the same name, or why not. Flow never creates a Xero contact (as before):
-// a missing or doubled name is for a person to fix in Xero, then sync.
+// the same name, or why not. A missing name can be created from the Flow
+// contact when that setting is on (create-contact.js). A doubled name is
+// still for a person to fix in Xero, then sync.
 export async function matchContact(db, organisationId, name) {
   const wanted = normaliseName(name);
   const { rows } = await db.execute(sql`select * from xero_contacts where organisation_id = ${organisationId}
@@ -182,3 +236,17 @@ export async function matchContact(db, organisationId, name) {
   if (matches.length > 1) return { state: 'ambiguous', matches };
   return { state: 'missing' };
 }
+
+// The Xero contact for a Flow contact: the identity-map link first, then the
+// name. A link Flow made stays matched after a rename on one side.
+export async function matchContactFor(db, organisationId, { contactId = null, name }) {
+  if (contactId) {
+    const linked = await externalIdFor(db, organisationId, { system: 'xero', entity: 'contact', flowId: contactId });
+    if (linked) {
+      const { rows } = await db.execute(sql`select * from xero_contacts where organisation_id = ${organisationId} and xero_contact_id = ${linked}`);
+      const contact = rows[0] ? contactRow(rows[0]) : null;
+      if (contact?.status === 'ACTIVE') return { state: 'matched', contact, by: 'link' };
+    }
+  }
+  return matchContact(db, organisationId, name);
+}

package/server/integrations/xero/client.js

@@ -292,6 +292,43 @@ export function createXeroClient({
     },
     // One invoice. `idempotencyKey` makes a retry within Xero's window
     // return the first result instead of a second invoice.
+    // Deletes one draft. The body is only the id and Status DELETED: Flow never
+    // changes any other field. The caller has already read the invoice and
+    // seen DRAFT or SUBMITTED. A result that is not DELETED is uncertain.
+    async deleteInvoice(invoiceId) {
+      if (!invoiceId) throw new TypeError('deleteInvoice: invoiceId is required');
+      const payload = await request('POST', `Invoices/${encodeURIComponent(invoiceId)}`, {
+        body: { InvoiceID: invoiceId, Status: 'DELETED' },
+      });
+      const updated = first(payload.Invoices);
+      const messages = validationMessages(updated);
+      if (!updated || updated.HasErrors || updated.StatusAttributeString === 'ERROR' || messages.length || updated.Status !== 'DELETED') {
+        throw xeroError('xero_uncertain', messages.join(' ') || 'Xero did not confirm the invoice was deleted.', {
+          status: 502,
+          details: messages.length ? { validationErrors: messages } : undefined,
+        });
+      }
+      return updated;
+    },
+    // One contact. `idempotencyKey` makes a retry within Xero's window return
+    // the first result instead of a second contact.
+    async createContact(contact, { idempotencyKey }) {
+      if (!idempotencyKey) throw new TypeError('createContact: idempotencyKey is required');
+      const payload = await request('POST', 'Contacts', {
+        query: { summarizeErrors: 'false' },
+        body: { Contacts: [contact] },
+        headers: { 'Idempotency-Key': idempotencyKey },
+      });
+      const created = first(payload.Contacts);
+      const messages = validationMessages(created);
+      if (!created?.ContactID || created.HasErrors || created.StatusAttributeString === 'ERROR' || messages.length) {
+        throw xeroError('xero_validation_failed', messages.join(' ') || 'Xero refused the contact.', {
+          status: 422,
+          details: messages.length ? { validationErrors: messages } : undefined,
+        });
+      }
+      return created;
+    },
     async createInvoice(invoice, { idempotencyKey }) {
       if (!idempotencyKey) throw new TypeError('createInvoice: idempotencyKey is required');
       const payload = await request('POST', 'Invoices', {

package/server/integrations/xero/create-contact.js

@@ -0,0 +1,126 @@
+import { createHash } from 'node:crypto';
+import { getContact } from '../../core/contacts.js';
+import { linkRecord } from '../../core/links.js';
+import { mapContact, matchContactFor, normaliseName, upsertContact } from './catalogue.js';
+import { xeroError } from './client.js';
+import { readConnection } from './connections.js';
+import { withXeroLane } from './governor.js';
+import { writesAllowed } from './settings.js';
+
+// Creates the Xero contact for one Flow contact (docs/CONTACTS.md). Flow's
+// contact stays the record. Xero gets a copy, and this file stores that copy
+// and the identity-map link. A second press for the same contact finds the
+// first and creates nothing.
+
+const PERSONS_MAX = 5;
+
+export function xeroContactBody(contact) {
+  const body = {
+    Name: contact.name,
+    IsCustomer: contact.kind === 'customer',
+    IsSupplier: contact.kind === 'supplier',
+  };
+  if (contact.firstName) body.FirstName = contact.firstName;
+  if (contact.lastName) body.LastName = contact.lastName;
+  if (contact.email) body.EmailAddress = contact.email;
+  if (contact.accountNumber) body.AccountNumber = contact.accountNumber;
+  if (contact.taxNumber) body.TaxNumber = contact.taxNumber;
+  const phones = [];
+  if (contact.phone) phones.push({ PhoneType: 'DEFAULT', PhoneNumber: contact.phone });
+  if (contact.mobile) phones.push({ PhoneType: 'MOBILE', PhoneNumber: contact.mobile });
+  if (phones.length) body.Phones = phones;
+  const address = contact.address;
+  if (address && (address.line1 || address.city || address.postalCode)) {
+    const lines = {
+      AddressLine1: address.line1 || '',
+      AddressLine2: address.line2 || '',
+      City: address.city || '',
+      Region: address.region || '',
+      PostalCode: address.postalCode || '',
+      Country: address.country || '',
+    };
+    body.Addresses = [{ AddressType: 'POBOX', ...lines }, { AddressType: 'STREET', ...lines }];
+  }
+  const people = (contact.practitioners ?? []).slice(0, PERSONS_MAX).map((person) => {
+    const [first, ...rest] = String(person.name).trim().split(/\s+/);
+    const out = { FirstName: first, IncludeInEmails: false };
+    if (rest.length) out.LastName = rest.join(' ');
+    if (person.email) out.EmailAddress = person.email;
+    return out;
+  });
+  if (people.length) body.ContactPersons = people;
+  return body;
+}
+
+function idempotencyKey(organisationId, contactId, body) {
+  const digest = createHash('sha256').update([organisationId, contactId, JSON.stringify(body)].join('\u0000')).digest('hex');
+  return `flow-xero-contact-${digest.slice(0, 40)}`;
+}
+
+async function remember(db, organisationId, flowId, xeroContact, matchedBy) {
+  const mapped = mapContact(xeroContact);
+  await upsertContact(db, organisationId, mapped);
+  const link = await linkRecord(db, organisationId, {
+    entity: 'contact', flowId, system: 'xero', externalId: mapped.xeroContactId, matchedBy,
+  });
+  return { contact: mapped, link: link.outcome };
+}
+
+function activeNamed(contacts, name) {
+  const wanted = normaliseName(name);
+  return contacts.filter((contact) => contact.ContactStatus !== 'ARCHIVED' && normaliseName(contact.Name) === wanted);
+}
+
+// What a pending invoice, or the contact page, can offer. No Xero calls.
+export async function matchCustomer(db, runtime, { organisationId, contactId }) {
+  const connection = await readConnection(db, organisationId);
+  const connected = Boolean(connection && connection.mode === runtime.settings.mode);
+  if (!connected) return { state: 'off', offerCreate: false, xeroContactId: null, name: null };
+  const contact = await getContact(db, organisationId, contactId);
+  const match = await matchContactFor(db, organisationId, { contactId, name: contact.name });
+  return {
+    state: match.state,
+    offerCreate: match.state === 'missing' && runtime.settings.createContacts && writesAllowed(runtime.settings),
+    xeroContactId: match.contact?.xeroContactId ?? null,
+    name: match.contact?.name ?? null,
+  };
+}
+
+export async function createCustomer(db, runtime, { organisationId, contactId, actor = null }) {
+  if (!runtime.settings.createContacts) {
+    throw xeroError('xero_create_contacts_off', 'Creating Xero clients is off. Add the client in Xero, then sync. Or turn Create missing clients on.', { status: 409 });
+  }
+  runtime.assertWritesAllowed();
+  const flowContact = await getContact(db, organisationId, contactId);
+  const known = await matchContactFor(db, organisationId, { contactId, name: flowContact.name });
+  if (known.state === 'ambiguous') {
+    throw xeroError('xero_contact_ambiguous', `More than one Xero contact is named "${flowContact.name}". Merge or rename them in Xero, then sync.`, { status: 409 });
+  }
+  if (known.state === 'matched') {
+    const linked = await linkRecord(db, organisationId, {
+      entity: 'contact', flowId: contactId, system: 'xero', externalId: known.contact.xeroContactId, matchedBy: known.by === 'link' ? 'created_by_flow' : 'exact_name',
+    });
+    return { outcome: 'existing', contact: known.contact, link: linked.outcome, actor };
+  }
+
+  return runtime.serial(organisationId, () => withXeroLane('writes', async () => {
+    const { client } = await runtime.clientFor(db, organisationId);
+    await runtime.assertEnvironment(client);
+    const live = await client.findContactsByName(flowContact.name);
+    const active = activeNamed(live, flowContact.name);
+    if (active.length > 1) {
+      throw xeroError('xero_contact_ambiguous', `More than one Xero contact is named "${flowContact.name}". Merge or rename them in Xero, then sync.`, { status: 409 });
+    }
+    if (!active.length && live.length) {
+      throw xeroError('xero_contact_archived', `A Xero contact named "${flowContact.name}" is archived. Restore it in Xero, then sync.`, { status: 409 });
+    }
+    if (active.length === 1) {
+      const kept = await remember(db, organisationId, contactId, active[0], 'exact_name');
+      return { outcome: 'existing', ...kept };
+    }
+    const body = xeroContactBody(flowContact);
+    const created = await client.createContact(body, { idempotencyKey: idempotencyKey(organisationId, contactId, body) });
+    const kept = await remember(db, organisationId, contactId, created, 'created_by_flow');
+    return { outcome: 'created', ...kept };
+  }));
+}

package/server/integrations/xero/delete-invoice.js

@@ -0,0 +1,104 @@
+import { and, eq, sql } from 'drizzle-orm';
+import { recordAccountingEvidence } from '../../core/ledger.js';
+import { billingObligations } from '../../db/schema.js';
+import { xeroError } from './client.js';
+import { readConnection } from './connections.js';
+import { withXeroLane } from './governor.js';
+import { ledgerState } from './ledger.js';
+import { writesAllowed } from './settings.js';
+
+// Delete the Xero draft behind an issued Flow invoice (docs/XERO.md).
+// The core calls this through the port (`deleteInvoice`) and voids in Flow
+// only after the answer is `deleted` or `gone`. This file is the only place
+// that knows Xero's statuses.
+//
+// Read first, then write. DRAFT and SUBMITTED are set to DELETED. DELETED
+// and VOIDED need no write. AUTHORISED and PAID are refused, and nothing is
+// written. A timeout or a 5xx throws, so Flow stays as it was; the next try
+// reads again and does not repeat a delete Xero already made.
+
+const DRAFTS = new Set(['DRAFT', 'SUBMITTED']);
+const GONE = new Set(['DELETED', 'VOIDED']);
+const APPROVED = new Set(['AUTHORISED', 'PAID']);
+export const APPROVED_MESSAGE = 'Approved in Xero. Void it in Xero first.';
+
+async function linkedXeroId(db, organisationId, invoiceId) {
+  const { rows: pushes } = await db.execute(sql`
+    select xero_invoice_id from xero_invoice_pushes
+    where organisation_id = ${organisationId} and invoice_id = ${invoiceId} and xero_invoice_id is not null
+    order by version desc limit 1`);
+  if (pushes[0]?.xero_invoice_id) return pushes[0].xero_invoice_id;
+  const { rows: links } = await db.execute(sql`
+    select xero_invoice_id from xero_invoice_links
+    where organisation_id = ${organisationId} and invoice_id = ${invoiceId}`);
+  return links[0]?.xero_invoice_id ?? null;
+}
+
+// Who deleted it, and the status Xero confirmed, on the push, the link and
+// Flow's copy. The ledger records deleted or voided so the job is not treated
+// as still drafted.
+async function recordDeletion(db, organisationId, invoiceId, xeroId, status, actor) {
+  await db.execute(sql`
+    update xero_invoice_pushes set
+      xero_status = ${status}, deleted_by = ${actor}, deleted_at = now(), updated_at = now()
+    where organisation_id = ${organisationId} and invoice_id = ${invoiceId} and xero_invoice_id = ${xeroId}`);
+  await db.execute(sql`
+    update xero_invoice_links set deleted_by = ${actor}, deleted_at = now()
+    where organisation_id = ${organisationId} and invoice_id = ${invoiceId}`);
+  // A new hash, so the next read of Xero replaces this row with what Xero says.
+  await db.execute(sql`
+    update xero_invoices set status = ${status}, record_hash = ${`flow-delete:${status}:${Date.now()}`}, last_changed_at = now()
+    where organisation_id = ${organisationId} and xero_invoice_id = ${xeroId}`);
+  const state = ledgerState({ Status: status });
+  if (!state || !actor) return;
+  const jobs = await db.select({ id: billingObligations.id }).from(billingObligations)
+    .where(and(eq(billingObligations.organisationId, organisationId), eq(billingObligations.invoiceId, invoiceId)));
+  for (const job of jobs) {
+    await recordAccountingEvidence(db, organisationId, job.id, {
+      state, accountingRef: xeroId, matchedBy: 'flow_invoice', actor, checkedAt: new Date().toISOString(),
+    });
+  }
+}
+
+async function readLive(client, xeroId) {
+  try {
+    return await withXeroLane('reads', () => client.getInvoice(xeroId));
+  } catch (error) {
+    if (error.status === 404) return null;
+    throw error;
+  }
+}
+
+export async function deleteXeroInvoice(db, runtime, { organisationId, invoiceId, actor = null }) {
+  // Writes off: no call at all. The core says so with the Send gate's message
+  // before it gets here; this is the same stop for a direct call.
+  if (!writesAllowed(runtime.settings)) return { state: 'unavailable', status: null };
+  const connection = await readConnection(db, organisationId);
+  if (!connection || connection.mode !== runtime.settings.mode) return { state: 'unavailable', status: null };
+  const xeroId = await linkedXeroId(db, organisationId, invoiceId);
+  if (!xeroId) return { state: 'unavailable', status: null };
+
+  return runtime.serial(organisationId, async () => {
+    const { client } = await runtime.clientFor(db, organisationId);
+    const live = await readLive(client, xeroId);
+    const status = live?.Status ?? null;
+    if (!live) {
+      await recordDeletion(db, organisationId, invoiceId, xeroId, 'DELETED', actor);
+      return { state: 'gone', status: null };
+    }
+    if (GONE.has(status)) {
+      await recordDeletion(db, organisationId, invoiceId, xeroId, status, actor);
+      return { state: 'gone', status };
+    }
+    if (APPROVED.has(status)) return { state: 'approved', status, message: APPROVED_MESSAGE };
+    if (!DRAFTS.has(status)) return { state: 'unavailable', status };
+
+    await runtime.assertEnvironment(client);
+    const updated = await withXeroLane('writes', () => client.deleteInvoice(xeroId));
+    if (updated?.Status !== 'DELETED') {
+      throw xeroError('xero_uncertain', 'Xero did not confirm the invoice was deleted. Nothing was changed in Flow.', { status: 502 });
+    }
+    await recordDeletion(db, organisationId, invoiceId, xeroId, 'DELETED', actor);
+    return { state: 'deleted', status: 'DELETED' };
+  });
+}

package/server/integrations/xero/drafts.js

@@ -5,7 +5,8 @@ import { getInvoice, listInvoiceVersions } from '../../core/invoices.js';
 import { sendModeFor } from '../../core/invoicing-rules.js';
 import { contacts as flowContacts, invoices as flowInvoices, priceItems } from '../../db/schema.js';
 import { readConnection } from './connections.js';
-import { itemsByCode, lastSuccessfulSyncAt, matchContact, normaliseName } from './catalogue.js';
+import { itemsByCode, lastSuccessfulSyncAt, matchContactFor, normaliseName } from './catalogue.js';
+import { writesAllowed } from './settings.js';
 import { xeroError } from './client.js';
 import { withXeroLane } from './governor.js';
 import { mirrorState } from './lookup.js';
@@ -24,8 +25,9 @@ import { mirrorState } from './lookup.js';
 //   version is never changed, here or in Xero: Flow never updates a Xero
 //   invoice. A revised invoice (version 2) goes to Xero only after the
 //   earlier version's Xero invoice is deleted or voided there.
-// - Flow never creates a Xero contact. The customer must match one Xero
-//   contact by name (the synced copy, catalogue.js).
+// - The customer must match one Xero contact, by the identity-map link or by
+//   name (the synced copy, catalogue.js). When Create missing clients is on,
+//   a missing contact can be created from the Flow contact (create-contact.js).
 // - Before it creates, Flow asks Xero for invoices with the same reference.
 //   One for the same contact and total is the same work: Flow records it and
 //   creates nothing. One for the same contact at another total within 90
@@ -66,6 +68,13 @@ function xeroDate(value) {
 
 const problem = (code, message, extra = {}) => ({ code, message, ...extra });
 
+function missingContact(name, { offerCreate }) {
+  const message = offerCreate
+    ? `No Xero contact is named "${name}". Create the client in Xero from this contact.`
+    : `No Xero contact is named "${name}". Add it in Xero, then sync.`;
+  return problem('xero_contact_missing', message, { short: 'Client not in Xero', ...(offerCreate ? { offerCreate: true } : {}) });
+}
+
 // ---------------------------------------------------------------------------
 // The document to send
 
@@ -288,8 +297,9 @@ async function previewOne(db, runtime, organisationId, invoiceId) {
   const problems = [];
   if (invoice.status === 'void') problems.push(problem('invoice_void', 'This invoice is void. Flow does not send it to Xero.'));
   if (invoice.status === 'draft') problems.push(problem('invoice_not_issued', 'This invoice is a draft. Issue it, then send it to Xero.'));
-  const match = await matchContact(db, organisationId, document.contact.name);
-  if (match.state === 'missing') problems.push(problem('xero_contact_missing', `No Xero contact is named "${document.contact.name}". Add it in Xero (Flow never creates Xero contacts), then sync.`, { short: 'Client not in Xero' }));
+  const match = await matchContactFor(db, organisationId, { contactId: invoice.contactId, name: document.contact.name });
+  const offerCreate = match.state === 'missing' && runtime.settings.createContacts && writesAllowed(runtime.settings);
+  if (match.state === 'missing') problems.push(missingContact(document.contact.name, { offerCreate }));
   if (match.state === 'ambiguous') problems.push(problem('xero_contact_ambiguous', `More than one Xero contact is named "${document.contact.name}". Merge or rename them in Xero, then sync.`, { short: 'Client twice in Xero' }));
   const items = await itemsByCode(db, organisationId, document.lines.map((l) => l.itemCode));
   const sendMode = await sendModeFor(db, organisationId, invoice.contactId);
@@ -389,7 +399,7 @@ export async function checkDrafts(db, runtime, { organisationId, invoiceIds }) {
     for (const preview of invoices) {
       found.set(preview.invoiceId, preview.problems
         .filter((p) => p.blocking !== false && p.code !== 'invoice_not_issued')
-        .map(({ code, message, short }) => ({ code, message, ...(short ? { short } : {}) })));
+        .map(({ code, message, short, offerCreate }) => ({ code, message, ...(short ? { short } : {}), ...(offerCreate ? { offerCreate: true } : {}) })));
     }
   }
   return found;
@@ -468,11 +478,12 @@ async function pushOne(db, runtime, client, organisationId, invoiceId, { pushedB
     }
   }
 
-  const match = await matchContact(db, organisationId, document.contact.name);
+  const match = await matchContactFor(db, organisationId, { contactId: invoice.contactId, name: document.contact.name });
   if (match.state !== 'matched') {
+    const offerCreate = match.state === 'missing' && runtime.settings.createContacts && writesAllowed(runtime.settings);
     throw xeroError(match.state === 'missing' ? 'xero_contact_missing' : 'xero_contact_ambiguous',
       match.state === 'missing'
-        ? `No Xero contact is named "${document.contact.name}". Add it in Xero (Flow never creates Xero contacts), then sync.`
+        ? missingContact(document.contact.name, { offerCreate }).message
         : `More than one Xero contact is named "${document.contact.name}". Merge or rename them in Xero, then sync.`,
       { status: 409 });
   }