@arcforgelabs/flow 2026.10.46 → 2026.10.48

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/sentry/index.js

@@ -9,13 +9,17 @@ import { scrubSpan } from '../../ui/monitoring.js';
 // the host setting SENTRY_DSN. It has no tables.
 
 // The browser SDK, loaded from Sentry's CDN only while this adapter is on
-// (server/ui/monitoring.js). Pinned, with its integrity hash. With traces on,
-// the bundle that also traces; Sentry ships it only with session replay in
-// it too, which Flow never turns on.
+// (server/ui/monitoring.js). Pinned, with its integrity hash. With replay on,
+// the bundle with session replay; with traces on, the bundle that also traces
+// (Sentry ships it only with replay in it).
 export const SENTRY_BROWSER = Object.freeze({
   src: 'https://browser.sentry-cdn.com/11.4.0/bundle.feedback.min.js',
   integrity: 'sha384-H9RmZ/VaqOPZrUezgCSqHp4t3LoQMd/5+0Y4oEGUB2bddZzSnwZiOYoWneK4diWt',
 });
+export const SENTRY_BROWSER_REPLAY = Object.freeze({
+  src: 'https://browser.sentry-cdn.com/11.4.0/bundle.replay.feedback.min.js',
+  integrity: 'sha384-9Iyc17wHvpK0bqZe+cuAedQDHoWwenMrxXR+HgLLkQ3rHM4zQD+amLzBnmrQgowj',
+});
 export const SENTRY_BROWSER_TRACING = Object.freeze({
   src: 'https://browser.sentry-cdn.com/11.4.0/bundle.tracing.replay.feedback.min.js',
   integrity: 'sha384-LjwHQKAojcITl6Q7innDSAFjziFnqV9ovZBNXnXnQwub1VXIdBMJnYrQNihtxSa6',
@@ -44,6 +48,7 @@ export const SENTRY_SETUP = {
     { name: 'SENTRY_ENVIRONMENT', label: 'Environment', help: 'How Sentry labels this installation, for example production. Empty: production, or workspace in a Replit workspace.' },
     { name: 'SENTRY_CLIENT', label: 'Client', help: 'The name your support desk files this installation\'s reports under. Sent as the client tag. Empty: no client tag.' },
     { name: 'SENTRY_FEEDBACK', label: 'Report a problem button', kind: 'onoff', help: 'On: everyone signed in can send a report, with a screenshot, to this Sentry project.' },
+    { name: 'SENTRY_REPLAY', label: 'Replay with reports', kind: 'onoff', help: 'On: each report and each browser error keeps up to the last minute of the page, as a replay with every word hidden.' },
     { name: 'SENTRY_TRACES_SAMPLE_RATE', label: 'Traces', help: 'The share of clicks, page loads and requests timed, from 0 (off) to 1 (all). Empty: 0.2.' },
   ],
 };
@@ -56,6 +61,7 @@ export function readSentrySettings(env) {
   // labelled apart so they never read as the live app's.
   const environment = String(env.SENTRY_ENVIRONMENT ?? '').trim() || (isReplitWorkspace(env) ? 'workspace' : 'production');
   const feedback = String(env.SENTRY_FEEDBACK ?? 'on').trim() !== 'off';
+  const replay = String(env.SENTRY_REPLAY ?? 'on').trim() !== 'off';
   const rate = String(env.SENTRY_TRACES_SAMPLE_RATE ?? '').trim();
   const tracesSampleRate = rate === '' ? DEFAULT_TRACES_SAMPLE_RATE : Number(rate);
   if (!/^\d*\.?\d+$/.test(rate || '0') || !(tracesSampleRate >= 0 && tracesSampleRate <= 1)) {
@@ -66,7 +72,7 @@ export function readSentrySettings(env) {
   // Every event says which product and, when set, which client it is from,
   // so one support desk can serve many installations.
   const tags = client ? { product: 'flow', client } : { product: 'flow' };
-  return { dsn, environment, feedback, tracesSampleRate, tags };
+  return { dsn, environment, feedback, replay, tracesSampleRate, tags };
 }
 
 // No trace for the host's health check: it is not a person waiting.
@@ -108,7 +114,7 @@ export function createSentryAdapter({ sdk = SentryNode, env: hostEnv = process.e
         ),
         beforeSendSpan: scrubSpan,
       });
-      log.info?.(`[sentry] on: environment ${settings.environment}; report button ${settings.feedback ? 'on' : 'off'}; traces ${settings.tracesSampleRate > 0 ? settings.tracesSampleRate : 'off'}`);
+      log.info?.(`[sentry] on: environment ${settings.environment}; report button ${settings.feedback ? 'on' : 'off'}; replay ${settings.replay ? 'on' : 'off'}; traces ${settings.tracesSampleRate > 0 ? settings.tracesSampleRate : 'off'}`);
     },
     async stop() {
       if (settings) await sdk.close(2000);
@@ -133,15 +139,16 @@ export function createSentryAdapter({ sdk = SentryNode, env: hostEnv = process.e
       // meant for browsers.
       browserMonitoring() {
         if (!settings) return null;
-        const { tracesSampleRate } = settings;
+        const { tracesSampleRate, replay } = settings;
         return {
           dsn: settings.dsn,
           environment: settings.environment,
           release,
           feedback: settings.feedback,
+          replay,
           tags: settings.tags,
           tracesSampleRate,
-          script: tracesSampleRate > 0 ? SENTRY_BROWSER_TRACING : SENTRY_BROWSER,
+          script: tracesSampleRate > 0 ? SENTRY_BROWSER_TRACING : replay ? SENTRY_BROWSER_REPLAY : SENTRY_BROWSER,
         };
       },
       // Runs `work` in a span of the current trace (server/core/tracing.js).

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' };
+  });
+}