@arcforgelabs/flow 2026.10.26 → 2026.10.29

package/server/integrations/sentry/index.js

@@ -0,0 +1,105 @@
+import * as SentryNode from '@sentry/node';
+
+// The Sentry adapter (docs/SENTRY.md). It sends the errors Flow logs, and the
+// browser's errors and problem reports, to the installation's own Sentry
+// project. Flow ships no DSN: each installation enters its own, here or as
+// 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.
+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',
+});
+
+// A DSN is https://<public key>@<host>/<project id>.
+const DSN_PATTERN = /^https:\/\/[0-9a-f]{16,64}@[a-z0-9.-]+(:\d+)?\/(\d+)$/i;
+
+export const SENTRY_SETUP = {
+  guide: {
+    title: 'Connect your own Sentry project',
+    link: 'https://sentry.io/signup/',
+    steps: [
+      'Sign in to your organisation\'s own Sentry account, or create one.',
+      'Create a project. Choose Express as the platform.',
+      'Open the project\'s Settings, Client Keys (DSN), and copy the DSN.',
+      'Paste it below, or set SENTRY_DSN where Flow is hosted. Then turn Sentry on.',
+      'Optional: in Sentry, Settings, Integrations, add your issue tracker to turn a report into a task.',
+    ],
+  },
+  fields: [
+    { name: 'SENTRY_DSN', label: 'DSN', kind: 'url', help: 'From the Sentry project\'s Client Keys. Browsers see it, so it is not a secret.' },
+    { name: 'SENTRY_ENVIRONMENT', label: 'Environment', help: 'How Sentry labels this installation, for example production. Empty: production.' },
+    { 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.' },
+  ],
+};
+
+export function readSentrySettings(env) {
+  const dsn = String(env.SENTRY_DSN ?? '').trim();
+  if (!dsn) throw new Error('SENTRY_DSN is not set. Enter the Sentry project\'s DSN in Settings, Integrations.');
+  if (!DSN_PATTERN.test(dsn)) throw new Error('SENTRY_DSN is not a Sentry DSN (https://<key>@<host>/<project id>).');
+  const environment = String(env.SENTRY_ENVIRONMENT ?? '').trim() || 'production';
+  const feedback = String(env.SENTRY_FEEDBACK ?? 'on').trim() !== 'off';
+  return { dsn, environment, feedback };
+}
+
+// The release Sentry groups events by: Flow's release tag, else its commit.
+export function sentryRelease(env) {
+  const read = (value) => String(value ?? '').trim() || null;
+  const release = read(env.FLOW_DEPLOYED_RELEASE) ?? read(env.FLOW_RELEASE);
+  const revision = read(env.FLOW_REVISION);
+  return release ? `flow@${release.replace(/^v/, '')}` : revision ? `flow@${revision.slice(0, 12)}` : null;
+}
+
+// `sdk` is for tests: anything with init, captureMessage, captureException
+// and close, as @sentry/node has.
+export function createSentryAdapter({ sdk = SentryNode, env: hostEnv = process.env } = {}) {
+  let settings = null;
+  let release = null;
+
+  return {
+    id: 'sentry',
+    name: 'Sentry',
+    bundled: false,
+    setup: SENTRY_SETUP,
+    async start({ log, env }) {
+      settings = readSentrySettings(env ?? hostEnv);
+      release = sentryRelease(hostEnv);
+      sdk.init({
+        dsn: settings.dsn,
+        environment: settings.environment,
+        release: release ?? undefined,
+        // Flow sends what it logs; no request bodies, cookies or IP addresses.
+        sendDefaultPii: false,
+        tracesSampleRate: 0,
+        skipOpenTelemetrySetup: true,
+      });
+      log.info?.(`[sentry] on: environment ${settings.environment}; report button ${settings.feedback ? 'on' : 'off'}`);
+    },
+    async stop() {
+      if (settings) await sdk.close(2000);
+      settings = null;
+    },
+    capabilities: {
+      async health() {
+        return { ok: Boolean(settings), environment: settings?.environment ?? null, feedback: settings?.feedback ?? false };
+      },
+      // One error Flow logged: `source` is its "[tag]", `error` the Error when
+      // there is one.
+      captureError({ message, source = 'server', error = null }) {
+        if (!settings) return;
+        const scope = { level: 'error', tags: { source } };
+        if (error instanceof Error) sdk.captureException(error, { ...scope, extra: { log: message } });
+        else sdk.captureMessage(message, scope);
+      },
+      // What the browser needs to report to the same project. The DSN is
+      // meant for browsers.
+      browserMonitoring() {
+        if (!settings) return null;
+        return { dsn: settings.dsn, environment: settings.environment, release, feedback: settings.feedback, script: SENTRY_BROWSER };
+      },
+    },
+  };
+}
+
+export const sentryAdapter = createSentryAdapter();

package/server/integrations/xero/client.js

@@ -243,6 +243,11 @@ export function createXeroClient({
       });
       return payload[path] ?? [];
     },
+    // Xero emails one approved invoice to its contact, with the organisation's
+    // own template, and marks it sent. Not idempotent: a repeat sends again.
+    async emailInvoice(invoiceId) {
+      await request('POST', `Invoices/${encodeURIComponent(invoiceId)}/Email`, { body: {} });
+    },
     // One invoice. `idempotencyKey` makes a retry within Xero's window
     // return the first result instead of a second invoice.
     async createInvoice(invoice, { idempotencyKey }) {

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
@@ -80,7 +94,7 @@ async function documentFor(db, organisationId, invoiceId) {
       currency: invoice.currency,
       contact: { id: contact.id, name: contact.name, email: contact.email },
       lines: invoice.lines.map((l) => ({
-        position: l.position, itemCode: codes.get(l.priceItemId) ?? null, description: l.description, quantity: l.quantity,
+        position: l.position, itemCode: codes.get(l.priceItemId) ?? null, ...(l.accountCode ? { accountCode: l.accountCode } : {}), description: l.description, quantity: l.quantity,
         unitAmountCents: l.unitAmountCents, taxCode: l.taxCode, lineAmountCents: l.lineAmountCents, taxCents: l.taxCents,
       })),
       subtotalCents: invoice.subtotalCents,
@@ -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) => {
@@ -117,6 +131,9 @@ export function buildDraft(document, { settings, contact, items }) {
     if (line.itemCode) {
       if (items.has(line.itemCode)) out.ItemCode = line.itemCode;
       else problems.push(problem('xero_item_missing', `Line ${line.position}: item ${line.itemCode} is not in Xero. Add it in Xero, then sync.`, { itemCode: line.itemCode }));
+    } else if (line.accountCode) {
+      // A line with no item books to its own account, such as a surcharge.
+      out.AccountCode = line.accountCode;
     }
     if (tracking) out.Tracking = [tracking];
     return out;
@@ -124,7 +141,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 +185,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 +259,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 +282,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 +322,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 +376,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 +409,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 +440,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 +473,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 +548,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/index.js

@@ -1,6 +1,7 @@
 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, xeroLiveCheck } from './ledger.js';
 import { findInvoices, listCustomers } from './lookup.js';
@@ -86,6 +87,15 @@ 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) }),

package/server/integrations/xero/lookup.js

@@ -1,6 +1,5 @@
 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
@@ -10,6 +9,11 @@ import { MIRROR_RESOURCES } from './mirror.js';
 // stops counting as proof.
 export const MIRROR_FRESH_MS = 24 * 60 * 60 * 1000;
 
+// The copies that prove whether Xero holds an invoice for a job. Payments do
+// not: a connection without a payments scope (the default) never copies them,
+// and must still match jobs.
+export const PROOF_RESOURCES = Object.freeze(['invoices', 'credit_notes']);
+
 export async function listCustomers(db, organisationId) {
   const { rows } = await db.execute(sql`
     select xero_contact_id, name, status from xero_contacts
@@ -26,7 +30,7 @@ export async function mirrorState(db, organisationId, { now = new Date() } = {})
     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 finished = PROOF_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}`);

package/server/integrations/xero/migrations/0000_xero_connections.sql

@@ -1,6 +1,6 @@
 -- The Xero connection of each Flow organisation. The refresh token is
 -- AES-256-GCM ciphertext (XERO_TOKEN_KEY); the plain token is never stored.
-CREATE TABLE "xero_connections" (
+CREATE TABLE IF NOT EXISTS "xero_connections" (
 	"organisation_id" uuid PRIMARY KEY NOT NULL REFERENCES "organisations"("id"),
 	"mode" text NOT NULL,
 	"tenant_id" text NOT NULL,

package/server/integrations/xero/migrations/0001_xero_catalogue.sql

@@ -1,6 +1,6 @@
 -- Flow's copy of the Xero contacts and items of each connected organisation,
 -- and a record of each sync. Xero owns these records; a sync replaces the copy.
-CREATE TABLE "xero_contacts" (
+CREATE TABLE IF NOT EXISTS "xero_contacts" (
 	"organisation_id" uuid NOT NULL REFERENCES "organisations"("id"),
 	"xero_contact_id" text NOT NULL,
 	"name" text NOT NULL,
@@ -14,9 +14,9 @@ CREATE TABLE "xero_contacts" (
 	CONSTRAINT "xero_contacts_pk" PRIMARY KEY("organisation_id", "xero_contact_id")
 );
 --> statement-breakpoint
-CREATE INDEX "xero_contacts_org_name" ON "xero_contacts" ("organisation_id", lower("name"));
+CREATE INDEX IF NOT EXISTS "xero_contacts_org_name" ON "xero_contacts" ("organisation_id", lower("name"));
 --> statement-breakpoint
-CREATE TABLE "xero_items" (
+CREATE TABLE IF NOT EXISTS "xero_items" (
 	"organisation_id" uuid NOT NULL REFERENCES "organisations"("id"),
 	"xero_item_id" text NOT NULL,
 	"code" text NOT NULL,
@@ -32,7 +32,7 @@ CREATE TABLE "xero_items" (
 	CONSTRAINT "xero_items_org_code" UNIQUE("organisation_id", "code")
 );
 --> statement-breakpoint
-CREATE TABLE "xero_sync_runs" (
+CREATE TABLE IF NOT EXISTS "xero_sync_runs" (
 	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
 	"organisation_id" uuid NOT NULL REFERENCES "organisations"("id"),
 	"status" text DEFAULT 'running' NOT NULL,
@@ -46,4 +46,4 @@ CREATE TABLE "xero_sync_runs" (
 	CONSTRAINT "xero_sync_runs_status_valid" CHECK ("status" in ('running', 'succeeded', 'failed'))
 );
 --> statement-breakpoint
-CREATE INDEX "xero_sync_runs_org_started" ON "xero_sync_runs" ("organisation_id", "started_at");
+CREATE INDEX IF NOT EXISTS "xero_sync_runs_org_started" ON "xero_sync_runs" ("organisation_id", "started_at");

package/server/integrations/xero/migrations/0002_xero_invoice_pushes.sql

@@ -1,7 +1,7 @@
 -- One row for each issued Flow invoice version sent to Xero as a draft. It
 -- holds the exact request and its Idempotency-Key from before the request
 -- leaves, so an uncertain outcome is resolved without a second invoice.
-CREATE TABLE "xero_invoice_pushes" (
+CREATE TABLE IF NOT EXISTS "xero_invoice_pushes" (
 	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
 	"organisation_id" uuid NOT NULL,
 	"invoice_id" uuid NOT NULL,
@@ -29,4 +29,4 @@ CREATE TABLE "xero_invoice_pushes" (
 	CONSTRAINT "xero_invoice_pushes_settled_has_id" CHECK ("state" in ('dispatching', 'ambiguous') or "xero_invoice_id" is not null)
 );
 --> statement-breakpoint
-CREATE INDEX "xero_invoice_pushes_org_invoice" ON "xero_invoice_pushes" ("organisation_id", "invoice_id");
+CREATE INDEX IF NOT EXISTS "xero_invoice_pushes_org_invoice" ON "xero_invoice_pushes" ("organisation_id", "invoice_id");

package/server/integrations/xero/migrations/0003_xero_payment_cursors.sql

@@ -1,6 +1,6 @@
 -- Where the next read of Xero payments starts, for each Flow organisation.
 -- (This is the Xero adapter's own migration journal, not the core's.)
-CREATE TABLE "xero_payment_cursors" (
+CREATE TABLE IF NOT EXISTS "xero_payment_cursors" (
 	"organisation_id" uuid PRIMARY KEY NOT NULL REFERENCES "organisations"("id"),
 	"payments_since" timestamp with time zone NOT NULL,
 	"updated_at" timestamp with time zone DEFAULT now() NOT NULL

package/server/integrations/xero/migrations/0004_xero_mirror.sql

@@ -4,7 +4,7 @@
 -- without spending Xero calls. A row is upserted by its Xero id, and changes
 -- only when its content hash changes. Free text (references, line
 -- descriptions) is kept only with XERO_KEEP_REFERENCE=on.
-CREATE TABLE "xero_invoices" (
+CREATE TABLE IF NOT EXISTS "xero_invoices" (
 	"organisation_id" uuid NOT NULL REFERENCES "organisations"("id"),
 	"xero_invoice_id" text NOT NULL,
 	"type" text NOT NULL,
@@ -30,11 +30,11 @@ CREATE TABLE "xero_invoices" (
 	CONSTRAINT "xero_invoices_pk" PRIMARY KEY("organisation_id", "xero_invoice_id")
 );
 --> statement-breakpoint
-CREATE INDEX "xero_invoices_number" ON "xero_invoices" ("organisation_id", "invoice_number");
+CREATE INDEX IF NOT EXISTS "xero_invoices_number" ON "xero_invoices" ("organisation_id", "invoice_number");
 --> statement-breakpoint
-CREATE INDEX "xero_invoices_contact" ON "xero_invoices" ("organisation_id", "xero_contact_id", "issued_on");
+CREATE INDEX IF NOT EXISTS "xero_invoices_contact" ON "xero_invoices" ("organisation_id", "xero_contact_id", "issued_on");
 --> statement-breakpoint
-CREATE TABLE "xero_credit_notes" (
+CREATE TABLE IF NOT EXISTS "xero_credit_notes" (
 	"organisation_id" uuid NOT NULL REFERENCES "organisations"("id"),
 	"xero_credit_note_id" text NOT NULL,
 	"type" text NOT NULL,
@@ -57,7 +57,7 @@ CREATE TABLE "xero_credit_notes" (
 	CONSTRAINT "xero_credit_notes_pk" PRIMARY KEY("organisation_id", "xero_credit_note_id")
 );
 --> statement-breakpoint
-CREATE TABLE "xero_payments" (
+CREATE TABLE IF NOT EXISTS "xero_payments" (
 	"organisation_id" uuid NOT NULL REFERENCES "organisations"("id"),
 	"xero_payment_id" text NOT NULL,
 	"payment_type" text,
@@ -75,12 +75,12 @@ CREATE TABLE "xero_payments" (
 	CONSTRAINT "xero_payments_pk" PRIMARY KEY("organisation_id", "xero_payment_id")
 );
 --> statement-breakpoint
-CREATE INDEX "xero_payments_invoice" ON "xero_payments" ("organisation_id", "xero_invoice_id");
+CREATE INDEX IF NOT EXISTS "xero_payments_invoice" ON "xero_payments" ("organisation_id", "xero_invoice_id");
 --> statement-breakpoint
 -- Where the next read of each resource starts. `modified_since` is the
 -- keyset: the next read asks Xero for records changed since then, oldest
 -- change first. `page` moves on only when one second holds a full page.
-CREATE TABLE "xero_mirror_cursors" (
+CREATE TABLE IF NOT EXISTS "xero_mirror_cursors" (
 	"organisation_id" uuid NOT NULL REFERENCES "organisations"("id"),
 	"resource" text NOT NULL,
 	"modified_since" timestamp with time zone,

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

@@ -0,0 +1,16 @@
+-- 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 IF NOT EXISTS "send_mode" text DEFAULT 'accounting_draft' NOT NULL;--> statement-breakpoint
+ALTER TABLE "xero_invoice_pushes" ADD COLUMN IF NOT EXISTS "email_state" text;--> statement-breakpoint
+ALTER TABLE "xero_invoice_pushes" ADD COLUMN IF NOT EXISTS "email_error" text;--> statement-breakpoint
+ALTER TABLE "xero_invoice_pushes" ADD COLUMN IF NOT EXISTS "emailed_at" timestamp with time zone;--> statement-breakpoint
+DO $flow_guard$ BEGIN
+	ALTER TABLE "xero_invoice_pushes" ADD CONSTRAINT "xero_invoice_pushes_send_mode_valid" CHECK ("send_mode" in ('accounting_draft', 'approve_and_email'));
+EXCEPTION WHEN duplicate_object OR duplicate_table OR invalid_table_definition THEN NULL;
+END $flow_guard$;--> statement-breakpoint
+DO $flow_guard$ BEGIN
+	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'));
+EXCEPTION WHEN duplicate_object OR duplicate_table OR invalid_table_definition THEN NULL;
+END $flow_guard$;

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/ui/app-page.js

@@ -34,13 +34,16 @@ const BODY = `<div class="fx-app">
     <div class="fx-card fx-message__card fx-state-no-access" id="no-access"></div>
   </section>
 
-  <div class="fx-state-signed-in fx-shell">
+  <div class="fx-state-signed-in fx-shell" id="shell">
     <aside class="fx-side">
-      <a class="fx-brand" href="/">${FLOW_MARK}<span>Flow</span></a>
+      <div class="fx-side__head">
+        <a class="fx-brand" href="/">${FLOW_MARK}<span>Flow</span></a>
+        <button type="button" class="fx-btn fx-btn--ghost fx-btn--icon" id="menu-toggle" aria-controls="nav" aria-label="Menu"></button>
+      </div>
       <nav class="fx-nav" id="nav" aria-label="Flow"></nav>
       <div class="fx-side__end">
         <div id="user-button" class="fx-side__user"></div>
-        <button type="button" class="fx-btn fx-btn--ghost fx-btn--icon fx-mode-toggle" data-mode-toggle>Light or dark</button>
+        <button type="button" class="fx-btn fx-btn--ghost fx-btn--icon" id="search" title="Search (Ctrl+K)" aria-label="Search" aria-keyshortcuts="Control+K Meta+K"></button>
       </div>
     </aside>
     <main id="main" class="fx-main" tabindex="-1"></main>
@@ -48,7 +51,7 @@ const BODY = `<div class="fx-app">
   <div id="toasts" class="fx-toasts" aria-live="polite"></div>
 </div>`;
 
-export const APP_PATHS = ['/sign-in', '/jobs', '/invoices', '/invoices/:id', '/people', '/integrations', '/integrations/:id', '/account', '/appearance'];
+export const APP_PATHS = ['/sign-in', '/jobs', '/invoices', '/invoices/:id', '/people', '/integrations', '/integrations/:id', '/account', '/appearance', '/invoicing-settings'];
 
 export function appPage({ defaultFamily }) {
   return renderPage({