@arcforgelabs/flow 2026.10.25 → 2026.10.27

package/server/integrations/xero/drafts.js

@@ -1,13 +1,22 @@
 import { createHash } from 'node:crypto';
 import { and, eq, inArray, sql } from 'drizzle-orm';
 import { getInvoice, listInvoiceVersions } from '../../core/invoices.js';
-import { contacts as flowContacts, priceItems } from '../../db/schema.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 { xeroError } from './client.js';
 import { withXeroLane } from './governor.js';
-
-// Issued Flow invoices become Xero draft invoices (ACCREC, DRAFT). The lab
-// checks and approves them in Xero.
+import { mirrorState } from './lookup.js';
+
+// Issued Flow invoices go to Xero. How depends on the customer's send mode
+// (server/core/invoicing-rules.js):
+// - accounting_draft (the default): a Xero draft (ACCREC, DRAFT). The lab
+//   approves and sends it in Xero.
+// - approve_and_email: issuing in Flow was the approval. Flow sends it
+//   approved (AUTHORISED), then asks Xero to email it to the contact with the
+//   organisation's own template.
+// Either way the mirror (mirror.js) reads Xero's status back to Flow.
 //
 // The rules, as in the earlier codebase:
 // - What Flow sends is the issued version's document, exactly. A sent
@@ -19,7 +28,12 @@ import { withXeroLane } from './governor.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
-//   days is held for a person, unless they chose to send it anyway.
+//   days is held for a person, unless they chose to send it anyway. Flow skips
+//   this call for an invoice it drafted from a job when its complete, fresh
+//   copy of Xero showed no invoice for that job (docs/JOB_INVOICE_LINKS.md).
+// - Xero's email action is not idempotent. Flow records `sending` before it
+//   calls, and calls again only after Xero refused (`failed`), never after an
+//   unknown outcome: a person checks Xero then.
 // - The request, with its Idempotency-Key, is stored before it leaves. An
 //   uncertain outcome (timeout, 5xx) is resolved later: within Xero's
 //   six-minute idempotency window Flow repeats the same request with the same
@@ -103,7 +117,7 @@ function trackingFor(settings, contact) {
 }
 
 // The Xero draft for a document, and what stops it.
-export function buildDraft(document, { settings, contact, items }) {
+export function buildDraft(document, { settings, contact, items, sendMode = 'accounting_draft' }) {
   const problems = [];
   const tracking = trackingFor(settings, contact);
   const lines = document.lines.map((line) => {
@@ -124,7 +138,7 @@ export function buildDraft(document, { settings, contact, items }) {
   const issueDate = document.issueDate;
   const draft = {
     Type: 'ACCREC',
-    Status: 'DRAFT',
+    Status: sendMode === 'approve_and_email' ? 'AUTHORISED' : 'DRAFT',
     Contact: contact ? { ContactID: contact.xeroContactId } : { Name: document.contact.name },
     ...(issueDate ? { Date: issueDate, DueDate: document.dueDate ?? addDays(issueDate, settings.defaultDueDays) } : {}),
     Reference: xeroReference(document),
@@ -168,6 +182,8 @@ function mapPush(row) {
     verified: row.verified,
     error: row.error_code ? { code: row.error_code, message: row.error_message } : null,
     attempts: row.attempts,
+    sendMode: row.send_mode ?? 'accounting_draft',
+    email: row.email_state ? { state: row.email_state, error: row.email_error ?? null, at: row.emailed_at ?? null } : null,
     pushedBy: row.pushed_by,
     firstDispatchedAt: row.first_dispatched_at,
     lastDispatchedAt: row.last_dispatched_at,
@@ -240,8 +256,12 @@ async function previewOne(db, runtime, organisationId, invoiceId) {
   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.`));
   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.`));
   const items = await itemsByCode(db, organisationId, document.lines.map((l) => l.itemCode));
-  const { draft, problems: lineProblems } = buildDraft(document, { settings: runtime.settings, contact: match.contact, items });
+  const sendMode = await sendModeFor(db, organisationId, invoice.contactId);
+  const { draft, problems: lineProblems } = buildDraft(document, { settings: runtime.settings, contact: match.contact, items, sendMode });
   problems.push(...lineProblems);
+  if (sendMode === 'approve_and_email' && match.state === 'matched' && !match.contact.email) {
+    problems.push(problem('xero_contact_no_email', `The Xero contact "${match.contact.name}" has no email address, so Xero cannot email the invoice. Add one in Xero, then sync.`, { blocking: false }));
+  }
 
   const pushes = await listPushes(db, organisationId, invoiceId);
   const current = version ? pushes.find((p) => p.version === version) : null;
@@ -259,6 +279,7 @@ async function previewOne(db, runtime, organisationId, invoiceId) {
     invoiceId,
     number: document.number,
     version,
+    sendMode,
     state,
     problems,
     contact: { state: match.state, xeroContactId: match.contact?.xeroContactId ?? null, name: match.contact?.name ?? null },
@@ -298,10 +319,46 @@ export async function pushDrafts(db, runtime, organisationId, invoiceIds, { push
         results.push(failed(invoiceId, error));
       }
     }
+    await keepSendState(db, organisationId, results);
     return summarise(results);
   }));
 }
 
+// Flow's Problem view (server/core/sending.js) shows an issued invoice that
+// failed to send. Once Xero holds it, by any path, that problem is gone.
+async function keepSendState(db, organisationId, results) {
+  const held = results.filter((r) => ['created', 'reconciled', 'existing', 'already_in_xero'].includes(r.outcome)).map((r) => r.invoiceId);
+  if (!held.length) return;
+  await db.update(flowInvoices).set({ sendState: 'sent', sendError: null, sendUpdatedAt: sql`now()` })
+    .where(and(eq(flowInvoices.organisationId, organisationId), inArray(flowInvoices.id, held), sql`${flowInvoices.sendState} is not null`));
+}
+
+// Send all ready (server/core/sending.js): issued invoices in batches.
+export async function pushInvoices(db, runtime, { organisationId, invoiceIds, pushedBy = null }) {
+  const invoices = [];
+  for (let at = 0; at < invoiceIds.length; at += MAX_BATCH) {
+    invoices.push(...(await pushDrafts(db, runtime, organisationId, invoiceIds.slice(at, at + MAX_BATCH), { pushedBy })).invoices);
+  }
+  return { invoices };
+}
+
+// What would stop each Flow draft in Xero, from Flow's copy of Xero (no
+// calls). Null while Xero is not connected: then Flow's own checks decide.
+export async function checkDrafts(db, runtime, { organisationId, invoiceIds }) {
+  const connection = await readConnection(db, organisationId);
+  if (!connection || connection.mode !== runtime.settings.mode) return null;
+  const found = new Map();
+  for (let at = 0; at < invoiceIds.length; at += MAX_BATCH) {
+    const { invoices } = await previewDrafts(db, runtime, organisationId, invoiceIds.slice(at, at + MAX_BATCH));
+    for (const preview of invoices) {
+      found.set(preview.invoiceId, preview.problems
+        .filter((p) => p.blocking !== false && p.code !== 'invoice_not_issued')
+        .map(({ code, message }) => ({ code, message })));
+    }
+  }
+  return found;
+}
+
 function failed(invoiceId, error, outcome = 'failed') {
   return { invoiceId, outcome, error: { code: error.code ?? 'xero_push_failed', message: error.message, ...(error.details ? { details: error.details } : {}) } };
 }
@@ -316,6 +373,8 @@ function summarise(results) {
       mismatched: count('mismatch'),
       ambiguous: count('ambiguous'),
       failed: count('failed') + count('not_tried'),
+      emailed: results.filter((r) => r.email?.state === 'sent').length,
+      emailProblems: results.filter((r) => r.email && ['failed', 'unknown'].includes(r.email.state)).length,
     },
     invoices: results,
   };
@@ -347,7 +406,8 @@ async function pushOne(db, runtime, client, organisationId, invoiceId, { pushedB
   const pushes = await listPushes(db, organisationId, invoiceId);
   const current = pushes.find((p) => p.version === version);
   if (current && SETTLED.has(current.state)) {
-    return { invoiceId, version, outcome: 'already_in_xero', xero: current.xero };
+    const email = await emailIfDue(db, client, current);
+    return { invoiceId, version, outcome: 'already_in_xero', xero: current.xero, ...(email ? { email } : {}) };
   }
   if (current?.state === 'mismatch') {
     return { invoiceId, version, outcome: 'mismatch', xero: current.xero, error: current.error };
@@ -377,14 +437,18 @@ async function pushOne(db, runtime, client, organisationId, invoiceId, { pushedB
       { status: 409 });
   }
   const items = await itemsByCode(db, organisationId, document.lines.map((l) => l.itemCode));
-  const { draft, problems } = buildDraft(document, { settings: runtime.settings, contact: match.contact, items });
+  const sendMode = await sendModeFor(db, organisationId, invoice.contactId);
+  const { draft, problems } = buildDraft(document, { settings: runtime.settings, contact: match.contact, items, sendMode });
   if (problems.length) throw xeroError(problems[0].code, problems.map((p) => p.message).join(' '), { status: 409 });
 
   // Live duplicate check: invoices in Xero with this reference, made by Flow
-  // or by hand.
+  // or by hand. Not needed when Flow's own copy of Xero already answered it
+  // for the job this invoice bills.
   const earlierIds = new Set(pushes.map((p) => p.xero?.invoiceId).filter(Boolean));
-  const sameReference = (await client.findInvoicesByReference(draft.Reference))
-    .filter((inv) => !GONE.has(inv.Status) && !earlierIds.has(inv.InvoiceID));
+  const sameReference = (await copyShowsNoInvoice(db, runtime, organisationId, invoiceId))
+    ? []
+    : (await client.findInvoicesByReference(draft.Reference))
+      .filter((inv) => !GONE.has(inv.Status) && !earlierIds.has(inv.InvoiceID));
   const sameContact = sameReference.filter((inv) => inv.Contact?.ContactID === match.contact.xeroContactId);
   if (!allowExisting) {
     const same = sameContact.find((inv) => cents(inv.Total) === document.totalCents);
@@ -406,9 +470,9 @@ async function pushOne(db, runtime, client, organisationId, invoiceId, { pushedB
   const preExisting = sameReference.map((inv) => inv.InvoiceID);
   const { rows } = await db.execute(sql`
     insert into xero_invoice_pushes (organisation_id, invoice_id, version, state, idempotency_key, request_body, body_hash, pre_existing_ids, pushed_by,
-      first_dispatched_at, last_dispatched_at)
+      first_dispatched_at, last_dispatched_at, send_mode, email_state)
     values (${organisationId}, ${invoiceId}, ${version}, 'dispatching', ${key}, ${body}, ${bodyHash}, ${JSON.stringify(preExisting)}::jsonb, ${pushedBy},
-      ${new Date(runtime.now())}, ${new Date(runtime.now())})
+      ${new Date(runtime.now())}, ${new Date(runtime.now())}, ${sendMode}, ${sendMode === 'approve_and_email' ? 'pending' : null})
     on conflict (invoice_id, version) do nothing returning *`);
   if (!rows.length) throw xeroError('xero_push_in_progress', 'This invoice is being sent to Xero already. Check again shortly.', { status: 409 });
   return dispatch(db, client, mapPush(rows[0]), document, { fresh: true });
@@ -481,7 +545,50 @@ async function verify(db, client, push, draft, document, created, outcome) {
     return { invoiceId: push.invoiceId, version: push.version, outcome: 'mismatch', xero: settled.xero, error: settled.error };
   }
   const settled = await settle(db, push.id, { state: 'created', xeroInvoiceId: live.InvoiceID, xeroNumber: live.InvoiceNumber, xeroStatus: live.Status, verified: true });
-  return { invoiceId: push.invoiceId, version: push.version, outcome, verified: true, xero: settled.xero };
+  const email = await emailIfDue(db, client, settled);
+  return { invoiceId: push.invoiceId, version: push.version, outcome, verified: true, xero: settled.xero, ...(email ? { email } : {}) };
+}
+
+// ---------------------------------------------------------------------------
+// Email
+
+// Xero errors that prove it sent no email: it refused the request.
+const emailRefused = (error) => error.code === 'xero_validation_failed'
+  || (error.code === 'xero_api_error' && error.status >= 400 && error.status < 500);
+
+// Asks Xero to email an approved invoice that Flow sent and checked, once.
+// Answers the email's state, or null when the push sends no email.
+async function emailIfDue(db, client, push) {
+  if (push.sendMode !== 'approve_and_email' || !push.email) return null;
+  if (!push.verified || !push.xero?.invoiceId || !['pending', 'failed'].includes(push.email.state)) return push.email;
+  // Claim the email, so two pushes never both send it.
+  const { rows } = await db.execute(sql`update xero_invoice_pushes set email_state = 'sending', updated_at = now()
+    where id = ${push.id} and email_state in ('pending', 'failed') returning id`);
+  if (!rows.length) return { state: 'sending', error: null, at: null };
+  try {
+    await client.emailInvoice(push.xero.invoiceId);
+  } catch (error) {
+    const state = emailRefused(error) ? 'failed' : 'unknown';
+    const message = state === 'failed'
+      ? `Xero did not email the invoice: ${error.message}`
+      : 'Flow does not know whether Xero emailed the invoice. Check the invoice in Xero before you send it again.';
+    await db.execute(sql`update xero_invoice_pushes set email_state = ${state}, email_error = ${message}, updated_at = now() where id = ${push.id}`);
+    if (error.code === 'xero_rate_limited' || error.code === 'xero_reconnect_needed') throw error;
+    return { state, error: message, at: null };
+  }
+  const { rows: [done] } = await db.execute(sql`update xero_invoice_pushes set email_state = 'sent', email_error = null, emailed_at = now(), updated_at = now()
+    where id = ${push.id} returning emailed_at`);
+  return { state: 'sent', error: null, at: done.emailed_at };
+}
+
+// Flow drafted this invoice from a job, and its complete, fresh copy of Xero
+// showed no invoice for that job: Xero needs no live duplicate check.
+async function copyShowsNoInvoice(db, runtime, organisationId, invoiceId) {
+  const { rows: [job] } = await db.execute(sql`select accounting_state from billing_obligations
+    where organisation_id = ${organisationId} and invoice_id = ${invoiceId}`);
+  if (job?.accounting_state !== 'not_found') return false;
+  const mirror = await mirrorState(db, organisationId, { now: new Date(runtime.now()) });
+  return mirror.complete && mirror.fresh;
 }
 
 // An earlier attempt whose outcome is unknown.

package/server/integrations/xero/import.js

@@ -1,6 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { sql } from 'drizzle-orm';
 import { enqueueJob, runNextJob } from '../../core/queue.js';
+import { lastSync, syncCatalogue } from './catalogue.js';
 import { MIRROR_RESOURCES, mirrorXero } from './mirror.js';
 
 // The history import. When an owner connects Xero, Flow copies the
@@ -17,6 +18,9 @@ const LEASE_MS = 30 * 60 * 1000;
 // Xero's day limit resets on a rolling day; an hour is a cheap re-check.
 const BUDGET_WAIT_MS = 60 * 60 * 1000;
 const IDLE_MS = 30 * 1000;
+// Contacts and items are read again once a day, so the matcher can link each
+// customer (server/core/pipeline.js) without a person pressing Sync.
+const CATALOGUE_EVERY_MS = 24 * 60 * 60 * 1000;
 
 export async function queueHistoryImport(db, organisationId, { reason = 'connected', runAfter = null } = {}) {
   return enqueueJob(db, organisationId, { kind: IMPORT_KIND, dedupeKey: IMPORT_KEY, payload: { reason }, runAfter });
@@ -63,6 +67,23 @@ export async function runImportOnce(db, runtime, { workerId = `xero-import-${ran
   return ran;
 }
 
+// Reads the contacts and items of each connected organisation whose last good
+// read is older than a day. A failure is logged and tried again next hour.
+export async function refreshStaleCatalogues(db, runtime, { now = Date.now, log = console } = {}) {
+  const { rows } = await db.execute(sql`select organisation_id from xero_connections where mode = ${runtime.settings.mode}`);
+  for (const { organisation_id: organisationId } of rows) {
+    const last = await lastSync(db, organisationId);
+    const at = last?.finishedAt ?? last?.startedAt;
+    if (last && at && Number(now()) - new Date(at) < (last.status === 'succeeded' ? CATALOGUE_EVERY_MS : BUDGET_WAIT_MS)) continue;
+    try {
+      const run = await syncCatalogue(db, runtime, organisationId);
+      log.info?.(`[xero] contacts and items read for organisation ${organisationId}: ${run.contactCount} contacts, ${run.itemCount} items`);
+    } catch (error) {
+      log.error?.(`[xero] reading contacts and items for organisation ${organisationId} failed: ${error?.code ?? 'error'}`);
+    }
+  }
+}
+
 // The background worker: runs due slices one at a time, then waits. Started
 // by the adapter outside replay mode; stop() waits for a slice in flight.
 export function createImportWorker({ db, runtime, log = console, timers = { setTimeout, clearTimeout }, firstDelayMs = 10_000 }) {
@@ -83,6 +104,7 @@ export function createImportWorker({ db, runtime, log = console, timers = { setT
     let busy = false;
     running = (async () => {
       try {
+        await refreshStaleCatalogues(db, runtime, { log });
         const ran = await runImportOnce(db, runtime, { workerId });
         if (ran) {
           busy = true;

package/server/integrations/xero/index.js

@@ -1,8 +1,10 @@
 import { fileURLToPath } from 'node:url';
 import { sql } from 'drizzle-orm';
-import { pushInvoice } from './drafts.js';
+import { checkDrafts, pushInvoice, pushInvoices } from './drafts.js';
+import { readConnection } from './connections.js';
 import { createImportWorker } from './import.js';
-import { readPayments } from './ledger.js';
+import { readPayments, xeroLiveCheck } from './ledger.js';
+import { findInvoices, listCustomers } from './lookup.js';
 import { createXeroRouter } from './routes.js';
 import { createXeroRuntime, requireXeroSettings } from './runtime.js';
 import { writesAllowed } from './settings.js';
@@ -30,7 +32,7 @@ export const XERO_SETUP = {
   },
   fields: [
     { name: 'XERO_MODE', label: 'Mode', kind: 'choice', choices: [{ value: 'live', label: 'Live: your Xero organisation' }, { value: 'sandbox', label: 'Sandbox: a Xero Demo Company' }] },
-    { name: 'XERO_REDIRECT_URI', label: 'Redirect URI', kind: 'url', suggest: 'callback', help: 'This installation\'s address plus /api/xero/oauth/callback. Register the same address on the Xero app.' },
+    { name: 'XERO_REDIRECT_URI', label: 'Redirect URI', kind: 'url', suggest: 'callback', help: 'Register the same address on the Xero app.' },
     { name: 'XERO_CLIENT_ID', label: 'Client id', help: 'From the Xero app\'s Configuration.' },
     { name: 'XERO_CLIENT_SECRET', label: 'Client secret', secret: true, help: 'Stored encrypted. Flow never shows it again.' },
     { name: 'XERO_TENANT_NAME', label: 'Xero organisation name', help: 'Live mode connects only the organisation with this exact name.' },
@@ -85,9 +87,25 @@ export function createXeroAdapter({ runtime: given = null } = {}) {
       // One issued invoice to a Xero draft (drafts.js). The Flow invoice id
       // and version are the idempotency key.
       pushInvoice: ({ organisationId, invoiceId, pushedBy = null }) => pushInvoice(database, current(), { organisationId, invoiceId, pushedBy }),
+      // Several issued invoices, in batches of MAX_BATCH (drafts.js).
+      pushInvoices: ({ organisationId, invoiceIds, pushedBy = null }) => pushInvoices(database, current(), { organisationId, invoiceIds, pushedBy }),
+      // What would stop each Flow draft in Xero, from Flow's copy (no calls).
+      checkDrafts: ({ organisationId, invoiceIds }) => checkDrafts(database, current(), { organisationId, invoiceIds }),
+      sendStatus: async ({ organisationId }) => {
+        const { settings } = current();
+        const connection = await readConnection(database, organisationId);
+        return { connected: Boolean(connection && connection.mode === settings.mode), writesAllowed: writesAllowed(settings) };
+      },
       // Sales invoice payments changed since `since` (ledger.js). The answer's
       // cursor is the next `since`.
       pullPayments: ({ organisationId, since }) => readPayments(database, current(), organisationId, { since: new Date(since) }),
+      // Xero's invoice for one billable job, looked up live (ledger.js): the
+      // `liveCheck` for draftInvoiceForObligation.
+      checkInvoice: ({ organisationId, obligation }) => xeroLiveCheck(database, current(), organisationId)(obligation),
+      // Active Xero contacts, from Flow's copy (lookup.js).
+      listCustomers: ({ organisationId }) => listCustomers(database, organisationId),
+      // Sales invoices from the mirror, with the mirror's state (lookup.js).
+      findInvoices: ({ organisationId, ...query }) => findInvoices(database, organisationId, query),
     },
     routes: ({ db, personAuth, log, messagePage }) => createXeroRouter({ db, personAuth, runtime: current(), log, messagePage }),
   };

package/server/integrations/xero/lookup.js

@@ -0,0 +1,94 @@
+import { sql } from 'drizzle-orm';
+import { ledgerState } from './ledger.js';
+import { MIRROR_RESOURCES } from './mirror.js';
+
+// What the core's matcher (server/core/pipeline.js) reads from Xero: the
+// customers and the sales invoices in Flow's own copy. It never calls Xero, so
+// matching a whole history costs no API calls.
+
+// How old the mirror's last finished pass may be before "no invoice found"
+// stops counting as proof.
+export const MIRROR_FRESH_MS = 24 * 60 * 60 * 1000;
+
+export async function listCustomers(db, organisationId) {
+  const { rows } = await db.execute(sql`
+    select xero_contact_id, name, status from xero_contacts
+    where organisation_id = ${organisationId} and status = 'ACTIVE'
+    order by name`);
+  return rows.map((r) => ({ id: r.xero_contact_id, name: r.name }));
+}
+
+// Whether the mirror holds the whole history and was read lately. Until then a
+// search that finds nothing proves nothing.
+export async function mirrorState(db, organisationId, { now = new Date() } = {}) {
+  const { rows } = await db.execute(sql`
+    select resource, passes, last_pass_finished_at from xero_mirror_cursors
+    where organisation_id = ${organisationId}`);
+  const byResource = new Map(rows.map((r) => [r.resource, r]));
+  const invoices = byResource.get('invoices');
+  const finished = MIRROR_RESOURCES.every((r) => (byResource.get(r)?.passes ?? 0) > 0);
+  const lastPass = invoices?.last_pass_finished_at ? new Date(invoices.last_pass_finished_at) : null;
+  const { rows: [changed] } = await db.execute(sql`
+    select max(last_changed_at) as at from xero_invoices where organisation_id = ${organisationId}`);
+  return {
+    complete: finished,
+    fresh: Boolean(lastPass && now - lastPass <= MIRROR_FRESH_MS),
+    lastPassAt: lastPass,
+    // The latest change the mirror copied, so the matcher looks at a job again
+    // only when the mirror moved on.
+    changedAt: changed?.at ? new Date(changed.at) : null,
+  };
+}
+
+const ids = (list) => sql.param([...new Set(list.map(String))]);
+
+function invoiceRow(r) {
+  return {
+    id: r.xero_invoice_id,
+    number: r.invoice_number,
+    contactId: r.xero_contact_id,
+    status: r.status,
+    // The ledger's accounting state for this invoice.
+    state: ledgerState({ Status: r.status, AmountPaid: Number(r.amount_paid_cents ?? 0), AmountCredited: Number(r.amount_credited_cents ?? 0) }),
+    issuedOn: r.issued_on instanceof Date ? r.issued_on.toISOString().slice(0, 10) : r.issued_on,
+    subtotalCents: r.subtotal_cents === null ? null : Number(r.subtotal_cents),
+    totalCents: r.total_cents === null ? null : Number(r.total_cents),
+    amountDueCents: r.amount_due_cents === null ? null : Number(r.amount_due_cents),
+    amountPaidCents: r.amount_paid_cents === null ? null : Number(r.amount_paid_cents),
+    amountCreditedCents: r.amount_credited_cents === null ? null : Number(r.amount_credited_cents),
+    itemCodes: [...new Set((r.lines ?? []).map((l) => l.itemCode).filter(Boolean))],
+    flowInvoiceId: r.flow_invoice_id ?? null,
+    changedAt: r.last_changed_at,
+  };
+}
+
+// Sales invoices from the mirror, by any of: Xero ids, invoice numbers, the
+// Flow invoices Flow sent, or one customer within a date range. Answers the
+// mirror's state with them, and the latest change time it holds.
+export async function findInvoices(db, organisationId, query = {}) {
+  const { invoiceIds = [], numbers = [], flowInvoiceIds = [], contactId = null, from = null, to = null } = query;
+  const where = [];
+  if (invoiceIds.length) where.push(sql`i.xero_invoice_id = any(${ids(invoiceIds)}::text[])`);
+  if (numbers.length) where.push(sql`upper(i.invoice_number) = any(${sql.param([...new Set(numbers.map((n) => String(n).toUpperCase()))])}::text[])`);
+  if (flowInvoiceIds.length) where.push(sql`p.invoice_id = any(${ids(flowInvoiceIds)}::uuid[])`);
+  if (contactId) {
+    where.push(sql`(i.xero_contact_id = ${contactId}
+      ${from ? sql`and i.issued_on >= ${from}::date` : sql``}
+      ${to ? sql`and i.issued_on <= ${to}::date` : sql``})`);
+  }
+  const state = await mirrorState(db, organisationId);
+  if (!where.length) return { ...state, invoices: [] };
+  const { rows } = await db.execute(sql`
+    select i.*, p.invoice_id as flow_invoice_id
+    from xero_invoices i
+    left join lateral (
+      select invoice_id from xero_invoice_pushes
+      where organisation_id = i.organisation_id and xero_invoice_id = i.xero_invoice_id
+      order by version desc limit 1
+    ) p on true
+    where i.organisation_id = ${organisationId} and i.type = 'ACCREC'
+      and (${sql.join(where, sql` or `)})
+    order by i.issued_on, i.xero_invoice_id
+    limit 500`);
+  return { ...state, invoices: rows.map(invoiceRow) };
+}

package/server/integrations/xero/migrations/0005_xero_send_modes.sql

@@ -0,0 +1,10 @@
+-- How each push was sent (invoicing_settings.send_mode) and, for an invoice
+-- sent approved, whether Xero emailed it to the customer. Xero's email action
+-- is not idempotent, so Flow records `sending` before the call and retries
+-- only a refusal (`failed`), never an unknown outcome.
+ALTER TABLE "xero_invoice_pushes" ADD COLUMN "send_mode" text DEFAULT 'accounting_draft' NOT NULL;--> statement-breakpoint
+ALTER TABLE "xero_invoice_pushes" ADD COLUMN "email_state" text;--> statement-breakpoint
+ALTER TABLE "xero_invoice_pushes" ADD COLUMN "email_error" text;--> statement-breakpoint
+ALTER TABLE "xero_invoice_pushes" ADD COLUMN "emailed_at" timestamp with time zone;--> statement-breakpoint
+ALTER TABLE "xero_invoice_pushes" ADD CONSTRAINT "xero_invoice_pushes_send_mode_valid" CHECK ("send_mode" in ('accounting_draft', 'approve_and_email'));--> statement-breakpoint
+ALTER TABLE "xero_invoice_pushes" ADD CONSTRAINT "xero_invoice_pushes_email_state_valid" CHECK ("email_state" is null or "email_state" in ('pending', 'sending', 'sent', 'failed', 'unknown'));

package/server/integrations/xero/migrations/meta/_journal.json

@@ -36,6 +36,13 @@
       "when": 1792388000000,
       "tag": "0004_xero_mirror",
       "breakpoints": true
+    },
+    {
+      "idx": 5,
+      "version": "7",
+      "when": 1792406000000,
+      "tag": "0005_xero_send_modes",
+      "breakpoints": true
     }
   ]
 }

package/server/theme/color-contrast.js

@@ -1,5 +1,6 @@
-// WCAG 2.1 contrast helpers for theme tokens (server/theme/themes.js and
-// scripts/port-openclaw-themes.mjs). Colours are #rrggbb.
+// WCAG 2.1 contrast helpers for theme tokens (server/theme/themes.js,
+// server/theme/contrast-audit.js and scripts/port-openclaw-themes.mjs).
+// Colours are #rrggbb, except where parseColor reads a translucent one.
 
 export const HEX = /^#[0-9a-f]{6}$/i;
 
@@ -37,6 +38,16 @@ export function readableOn(color, bg, target = 4.5) {
   return toward[0] ? '#ffffff' : '#000000';
 }
 
+/** readableOn for every surface in turn, until the colour reads on all of them. */
+export function readableOnEvery(color, surfaces, target = 4.5) {
+  let out = color;
+  for (let pass = 0; pass < 3; pass += 1) {
+    for (const bg of surfaces) out = readableOn(out, bg, target);
+    if (surfaces.every((bg) => !HEX.test(out) || !HEX.test(bg) || contrast(out, bg) >= target)) break;
+  }
+  return out;
+}
+
 /**
  * A boundary colour for controls on `bg` (an input's or an outlined button's
  * edge): `bg` mixed toward `ink` just enough to stand out at `target`
@@ -52,3 +63,29 @@ export function boundaryOn(bg, ink, target = 3) {
   }
   return ink;
 }
+
+/** [r, g, b, a] (0-255, alpha 0-1) for #rrggbb, rgb()/rgba() or color-mix(in srgb, X N%, transparent). */
+export function parseColor(value) {
+  const v = String(value).trim();
+  let m = v.match(/^#([0-9a-f]{6})$/i);
+  if (m) return [0, 2, 4].map((i) => Number.parseInt(m[1].slice(i, i + 2), 16)).concat(1);
+  m = v.match(/^rgba?\(\s*([\d.]+)[\s,]+([\d.]+)[\s,]+([\d.]+)(?:[\s,/]+([\d.]+%?))?\s*\)$/i);
+  if (m) {
+    const a = m[4] === undefined ? 1 : m[4].endsWith('%') ? Number.parseFloat(m[4]) / 100 : Number(m[4]);
+    return [Number(m[1]), Number(m[2]), Number(m[3]), a];
+  }
+  m = v.match(/^color-mix\(in srgb,\s*(.+?)\s+([\d.]+)%,\s*transparent\)$/i);
+  if (m) {
+    const [r, g, b, a] = parseColor(m[1]);
+    return [r, g, b, a * Number(m[2]) / 100];
+  }
+  throw new Error(`contrast audit cannot read colour "${value}"`);
+}
+
+/** `top` painted over `under` (each a colour string), as an opaque #rrggbb. */
+export function over(top, under) {
+  const [r, g, b, a] = parseColor(top);
+  const base = parseColor(under);
+  if (base[3] < 1) throw new Error(`contrast audit needs an opaque surface, got "${under}"`);
+  return `#${[r, g, b].map((c, i) => Math.round(c * a + base[i] * (1 - a)).toString(16).padStart(2, '0')).join('')}`;
+}

package/server/theme/contrast-audit.js

@@ -0,0 +1,63 @@
+// The WCAG AA contrast audit for every design system (server/theme/themes.js).
+// Each pair is a foreground a screen really draws on a surface it really sits
+// on: Flow's components (server/ui/flow.css) and Clerk's account and sign-in
+// screens (server/ui/clerk-appearance.js). Translucent tokens (rgba() and
+// color-mix() toward transparent) are laid over the surface they sit on before
+// the ratio is taken, the way a browser paints them. test/theme-contrast.test.js
+// runs it in CI; `npm run theme:contrast` prints the table.
+import { contrast, over, parseColor } from './color-contrast.js';
+
+// WCAG 2.1: 4.5:1 for text (1.4.3), 3:1 for the edge or fill that shows a
+// control or its state (1.4.11).
+export const TEXT = 4.5;
+export const UI = 3;
+
+function withAlpha(color, alpha) {
+  const [r, g, b, a] = parseColor(color);
+  return `rgba(${r}, ${g}, ${b}, ${a * alpha})`;
+}
+
+// [id, what it is, minimum, (tokens) => [foreground, surface]]. A surface
+// given as an array is laid bottom first, so a tinted badge on a card is
+// [paper, tint].
+const PAIRS = [
+  ['text/bg', 'Body text on the page', TEXT, (k) => [k['--t-text'], k['--t-bg']]],
+  ['text/paper', 'Body text on a card', TEXT, (k) => [k['--t-text'], k['--t-paper']]],
+  ['strong/paper', 'Headings and names on a card', TEXT, (k) => [k['--t-strong'], k['--t-paper']]],
+  ['strong/bg', 'Page titles on the page', TEXT, (k) => [k['--t-strong'], k['--t-bg']]],
+  ['dim/bg', 'Secondary text on the page', TEXT, (k) => [k['--t-dim'], k['--t-bg']]],
+  ['dim/paper', 'Secondary text on a card (Clerk muted text)', TEXT, (k) => [k['--t-dim'], k['--t-paper']]],
+  ['dim/s1', 'Table headings, Clerk side menu', TEXT, (k) => [k['--t-dim'], k['--t-s1']]],
+  ['dim/s2', 'Segmented control labels', TEXT, (k) => [k['--t-dim'], k['--t-s2']]],
+  ['mute/paper', 'Muted text on a card', TEXT, (k) => [k['--t-mute'], k['--t-paper']]],
+  ['accent/bg', 'Links on the page', TEXT, (k) => [k['--t-accent'], k['--t-bg']]],
+  ['accent/paper', 'Links on a card', TEXT, (k) => [k['--t-accent'], k['--t-paper']]],
+  ['accent/accent-bg', 'Status and role badges', TEXT, (k) => [k['--t-accent'], [k['--t-paper'], k['--t-accent-bg']]]],
+  ['strong/accent-bg', 'Current page in the menu', TEXT, (k) => [k['--t-strong'], [k['--t-bg'], k['--t-accent-bg']]]],
+  ['text/accent-bg', 'Notices', TEXT, (k) => [k['--t-text'], [k['--t-paper'], k['--t-accent-bg']]]],
+  ['on-primary/primary', 'Primary buttons', TEXT, (k) => [k['--t-on-primary'], k['--t-primary']]],
+  ['brand-ink/brand', 'Text on the brand colour', TEXT, (k) => [k['--t-brand-ink'], k['--t-brand']]],
+  ['success/success-bg', 'Success badges', TEXT, (k) => [k['--t-success'], [k['--t-paper'], k['--t-success-bg']]]],
+  ['warn/warn-bg', 'Warning badges', TEXT, (k) => [k['--t-warn'], [k['--t-paper'], k['--t-warn-bg']]]],
+  ['danger/danger-bg', 'Error notices', TEXT, (k) => [k['--t-danger'], [k['--t-paper'], k['--t-danger-bg']]]],
+  ['paper/danger', 'Danger buttons and error toasts', TEXT, (k) => [k['--t-paper'], k['--t-danger']]],
+  ['bg/strong', 'Toasts', TEXT, (k) => [k['--t-bg'], k['--t-strong']]],
+  // server/ui/clerk-appearance.js: badge.
+  ['clerk-badge', 'Clerk "Primary" badge by an email', TEXT, (k) => [k['--t-dim'], [k['--t-paper'], withAlpha(k['--t-text'], 0.05)]]],
+  ['control/paper', 'Input and outlined button edges', UI, (k) => [k['--t-control'], k['--t-paper']]],
+  ['ring/paper', 'Focus ring', UI, (k) => [k['--t-ring'], k['--t-paper']]],
+  ['brand/paper', 'Selected theme card ring', UI, (k) => [k['--t-brand'], k['--t-paper']]],
+  ['primary/paper', 'Primary button edge on a card', UI, (k) => [k['--t-primary'], k['--t-paper']]],
+];
+
+/** Every pair for one family and mode: { id, label, min, fg, bg, ratio, pass }. */
+export function auditTokens(tokens) {
+  return PAIRS.map(([id, label, min, pick]) => {
+    const [fgRaw, surface] = pick(tokens);
+    const layers = Array.isArray(surface) ? surface : [surface];
+    const bg = layers.slice(1).reduce((under, top) => over(top, under), over(layers[0], '#ffffff'));
+    const fg = over(fgRaw, bg);
+    const ratio = contrast(fg, bg);
+    return { id, label, min, fg, bg, ratio: Math.round(ratio * 100) / 100, pass: ratio >= min };
+  });
+}

package/server/theme/themes.js

@@ -9,7 +9,7 @@
  * ./openclaw-palettes.js (docs/DESIGN.md). The engine is Arc Forge Labs'
  * Field's, so a family looks the same in both apps.
  */
-import { boundaryOn, HEX, inkOn, readableOn } from './color-contrast.js';
+import { boundaryOn, contrast, HEX, inkOn, over, readableOn, readableOnEvery } from './color-contrast.js';
 import { OPENCLAW_FAMILIES } from './openclaw-palettes.js';
 
 export { boundaryOn, contrast, inkOn, readableOn } from './color-contrast.js';
@@ -125,12 +125,20 @@ const MERIDIAN = {
 const { beacon, tide, claw, knot, dash, ...otherOpenclaw } = OPENCLAW_FAMILIES;
 const FAMILIES = { harbour: HARBOUR, meridian: MERIDIAN, beacon, tide, claw, knot, dash, ...otherOpenclaw };
 
+// Every family keeps WCAG AA (test/theme-contrast.test.js). A ported palette
+// that misses it on a surface Flow uses is nudged here, just far enough:
+// secondary text on every surface, accent text on the page, cards and its own
+// tint, and the ink on the brand colour. Harbour and Meridian already pass.
 // --t-control: the edge of an input or an outlined button on --t-paper, the
 // text colour faded toward the paper only as far as it still reads at 3:1.
 for (const family of Object.values(FAMILIES)) {
   for (const mode of ['light', 'dark']) {
     const tokens = family[mode];
-    tokens['--t-control'] = boundaryOn(tokens['--t-paper'], tokens['--t-text']);
+    const { '--t-bg': bg, '--t-paper': paper, '--t-s1': s1, '--t-s2': s2 } = tokens;
+    tokens['--t-dim'] = readableOnEvery(tokens['--t-dim'], [bg, paper, s1, s2]);
+    tokens['--t-accent'] = readableOnEvery(tokens['--t-accent'], [bg, paper, over(tokens['--t-accent-bg'], paper)]);
+    if (contrast(tokens['--t-brand-ink'], tokens['--t-brand']) < 4.5) tokens['--t-brand-ink'] = inkOn(tokens['--t-brand']);
+    tokens['--t-control'] = boundaryOn(paper, tokens['--t-text']);
   }
 }