@arcforgelabs/flow 2026.10.26 → 2026.10.27

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

@@ -71,6 +71,27 @@
       "when": 1792404377371,
       "tag": "0009_pipeline_matcher",
       "breakpoints": true
+    },
+    {
+      "idx": 10,
+      "version": "7",
+      "when": 1792407554981,
+      "tag": "0010_invoicing_rules",
+      "breakpoints": true
+    },
+    {
+      "idx": 11,
+      "version": "7",
+      "when": 1792411008479,
+      "tag": "0011_invoice_rules",
+      "breakpoints": true
+    },
+    {
+      "idx": 12,
+      "version": "7",
+      "when": 1792414436676,
+      "tag": "0012_invoice_sending",
+      "breakpoints": true
     }
   ]
 }

package/server/db/schema.js

@@ -85,6 +85,16 @@ export const invoices = pgTable('invoices', {
   subtotalCents: integer('subtotal_cents').notNull().default(0),
   taxCents: integer('tax_cents').notNull().default(0),
   totalCents: integer('total_cents').notNull().default(0),
+  // When a person marked the draft ready to send, and who. Any change to the
+  // draft clears it (server/core/sending.js).
+  readyAt: timestamp('ready_at', { withTimezone: true }),
+  readyBy: uuid('ready_by').references(() => people.id, { onDelete: 'set null' }),
+  // Sending to the accounting system (server/core/sending.js): queued by a
+  // person, then sent or failed. `sendError` is { code, message } while failed.
+  sendState: text('send_state'),
+  sendError: jsonb('send_error'),
+  sendRequestedBy: uuid('send_requested_by').references(() => people.id, { onDelete: 'set null' }),
+  sendUpdatedAt: timestamp('send_updated_at', { withTimezone: true }),
   createdAt: createdAt(),
   updatedAt: updatedAt(),
 }, (t) => [
@@ -97,6 +107,7 @@ export const invoices = pgTable('invoices', {
   }),
   check('invoices_status_valid', sql`${t.status} in ('draft', 'issued', 'void')`),
   check('invoices_issued_has_number', sql`${t.status} = 'draft' or ${t.number} is not null`),
+  check('invoices_send_state_valid', sql`${t.sendState} is null or ${t.sendState} in ('queued', 'sent', 'failed')`),
 ]);
 
 export const invoiceLines = pgTable('invoice_lines', {
@@ -209,6 +220,13 @@ export const billingObligations = pgTable('billing_obligations', {
   // The day of the work, for matching it to an accounting invoice: the work
   // system's invoice date, else its due date, else its order date.
   jobDate: date('job_date'),
+  // The work system's status for the job, as it reported it (for example
+  // "Shipped"). The draft rules read it.
+  sourceStatus: text('source_status'),
+  // Flow's own stage: the job is ready to invoice, since when and by whom (a
+  // person, or an automation such as one that reads the work system status).
+  readyAt: timestamp('ready_at', { withTimezone: true }),
+  readyBy: text('ready_by'),
   // The lines as the work system reported them, normalised.
   lines: jsonb('lines').notNull().default(sql`'[]'::jsonb`),
   lineFingerprint: text('line_fingerprint').notNull(),
@@ -559,3 +577,100 @@ export const linkRejections = pgTable('link_rejections', {
     foreignColumns: [billingObligations.organisationId, billingObligations.id],
   }),
 ]);
+
+// Invoicing rules (server/core/invoicing-rules.js). One row for each
+// organisation: the checks a job passes before Flow drafts its invoice, and
+// how a checked draft goes to the accounting system. No row means the
+// defaults. When Flow drafts is an automation (`automations`).
+export const SEND_MODES = ['accounting_draft', 'approve_and_email'];
+
+export const invoicingSettings = pgTable('invoicing_settings', {
+  organisationId: uuid('organisation_id').primaryKey().references(() => organisations.id),
+  // accounting_draft: a person checks the draft in Flow, Flow sends it as an
+  // accounting draft, and a person approves and sends it there.
+  // approve_and_email: a person approves the draft in Flow, Flow sends it
+  // approved, and the accounting system emails it to the customer.
+  sendMode: text('send_mode').notNull().default('accounting_draft'),
+  // A job whose date is more than this many days ago waits for a person.
+  staleDays: integer('stale_days').notNull().default(90),
+  // The days from the invoice date to its due date.
+  paymentTermsDays: integer('payment_terms_days').notNull().default(30),
+  // A job needs a practitioner, its own or its customer's default one.
+  requirePractitioner: boolean('require_practitioner').notNull().default(false),
+  // The price item code of a rush charge, and its share of the other lines.
+  rushItemCode: text('rush_item_code'),
+  rushPercent: integer('rush_percent').notNull().default(20),
+  // The fixed checks above became invoice rules (invoice_rules). True once
+  // this organisation's starter rules were made from them.
+  rulesSeeded: boolean('rules_seeded').notNull().default(false),
+  updatedBy: uuid('updated_by').references(() => people.id, { onDelete: 'set null' }),
+  updatedAt: updatedAt(),
+}, (t) => [
+  check('invoicing_settings_send_mode_valid', inList('send_mode', SEND_MODES)),
+  check('invoicing_settings_stale_days_valid', sql`${t.staleDays} between 1 and 3650`),
+  check('invoicing_settings_terms_valid', sql`${t.paymentTermsDays} between 0 and 365`),
+  check('invoicing_settings_rush_valid', sql`${t.rushPercent} between 0 and 100`),
+]);
+
+// One customer's own invoicing settings. A null value takes the
+// organisation's setting.
+export const customerBillingSettings = pgTable('customer_billing_settings', {
+  organisationId: organisationId().references(() => organisations.id),
+  contactId: uuid('contact_id').notNull(),
+  // A customer that is not billable never gets an invoice from a rule, and
+  // `autoDraft` false keeps the draft automation off for this customer.
+  billable: boolean('billable').notNull().default(true),
+  defaultPractitioner: text('default_practitioner'),
+  autoDraft: boolean('auto_draft'),
+  sendMode: text('send_mode'),
+  paymentTermsDays: integer('payment_terms_days'),
+  updatedBy: uuid('updated_by').references(() => people.id, { onDelete: 'set null' }),
+  updatedAt: updatedAt(),
+}, (t) => [
+  primaryKey({ name: 'customer_billing_settings_pk', columns: [t.organisationId, t.contactId] }),
+  foreignKey({
+    name: 'customer_billing_settings_contact_same_org',
+    columns: [t.organisationId, t.contactId],
+    foreignColumns: [contacts.organisationId, contacts.id],
+  }),
+  check('customer_billing_settings_send_mode_valid', sql`${t.sendMode} is null or ${t.sendMode} in ('accounting_draft', 'approve_and_email')`),
+  check('customer_billing_settings_terms_valid', sql`${t.paymentTermsDays} is null or ${t.paymentTermsDays} between 0 and 365`),
+]);
+
+// Invoice rules (server/core/invoice-rules.js, docs/INVOICE_RULES.md): a lab's
+// own checks on a job before Flow drafts its invoice. Each rule is When, If and
+// Then: `conditions` is a list of { field, test, value, item? } that must all
+// match, and `action` is { kind: 'wait' | 'skip' }. `starter_key` marks a rule
+// Flow made from the earlier fixed settings, once per organisation.
+export const invoiceRules = pgTable('invoice_rules', {
+  id: id(),
+  organisationId: organisationId().references(() => organisations.id),
+  name: text('name').notNull(),
+  position: integer('position').notNull(),
+  enabled: boolean('enabled').notNull().default(true),
+  trigger: text('trigger').notNull().default('job_ready'),
+  conditions: jsonb('conditions').notNull().default(sql`'[]'::jsonb`),
+  action: jsonb('action').notNull(),
+  starterKey: text('starter_key'),
+  updatedBy: uuid('updated_by').references(() => people.id, { onDelete: 'set null' }),
+  createdAt: createdAt(),
+  updatedAt: updatedAt(),
+}, (t) => [
+  uniqueIndex('invoice_rules_starter_key').on(t.organisationId, t.starterKey),
+  check('invoice_rules_trigger_valid', sql`${t.trigger} in ('job_ready')`),
+  check('invoice_rules_name_valid', sql`length(${t.name}) between 1 and 120`),
+]);
+
+// Automations (server/core/automations.js): Flow's routines, each on or off,
+// with its own settings. The routines are defined in code; a row holds an
+// organisation's choice. No row means the routine's default.
+export const automations = pgTable('automations', {
+  organisationId: organisationId().references(() => organisations.id),
+  key: text('key').notNull(),
+  enabled: boolean('enabled').notNull(),
+  config: jsonb('config').notNull().default(sql`'{}'::jsonb`),
+  updatedBy: uuid('updated_by').references(() => people.id, { onDelete: 'set null' }),
+  updatedAt: updatedAt(),
+}, (t) => [
+  primaryKey({ name: 'automations_pk', columns: [t.organisationId, t.key] }),
+]);

package/server/index.js

@@ -6,7 +6,9 @@ import { createPersonAuth } from './auth/session.js';
 import { resolveSignInSettings } from './auth/settings.js';
 import { migrateDatabase, openDatabase } from './db/index.js';
 import { importEarlierAtStart, importEarlierLinksAtStart, resolveImportAtStart } from './import/at-start.js';
+import { createMonitoredLog } from './core/monitoring.js';
 import { createPipelineWorker } from './core/pipeline.js';
+import { createSendWorker } from './core/sending.js';
 import { resolveSecretsKey } from './core/secrets.js';
 import { adapters as shippedAdapters } from './integrations/adapters.js';
 import { createIntegrations, resolveEnabledIntegrations } from './integrations/index.js';
@@ -66,12 +68,15 @@ await importEarlierLinksAtStart({ db: database.db, pool: database.pool, settings
   .catch((error) => console.error(`[import] ${error.message}`));
 // What an owner set in Settings, Integrations, with the host's own
 // environment over it (server/integrations/setup.js).
+// Every part of Flow logs here: each error also goes to the installation's
+// own error service while one is on (docs/SENTRY.md).
 let integrations;
+const log = createMonitoredLog({ log: console, reporters: () => integrations?.with('captureError') ?? [] });
 try {
   const stored = await readStoredSettings(database.db);
   const { env: settingsEnv, unreadable } = settingsEnvironment({ env: process.env, stored, adapters: shippedAdapters, secrets });
   if (unreadable.length) console.warn(`[integrations] stored credentials Flow cannot read with this secrets key: ${unreadable.join(', ')}. An owner enters them again in Settings.`);
-  integrations = createIntegrations({ turnedOnInFlow: storedEnabled(stored, process.env), settingsEnv });
+  integrations = createIntegrations({ turnedOnInFlow: storedEnabled(stored, process.env), settingsEnv, log });
   await integrations.start(database.db);
 } catch (error) {
   console.error(`[integrations] ${error.message}`);
@@ -85,14 +90,17 @@ console.log(`[integrations] on: ${integrationsOn.join(', ') || 'none'}; secrets
 // only while an integration that feeds it is on, and writes to no other
 // system. FLOW_PIPELINE=off stops it.
 if (process.env.FLOW_PIPELINE !== 'off') {
-  createPipelineWorker({ db: database.db, integrations }).start();
+  createPipelineWorker({ db: database.db, integrations, log }).start();
 }
+// The send worker (server/core/sending.js) sends only what a person queued
+// with Send all ready, to the accounting integration that is on.
+createSendWorker({ db: database.db, integrations, log }).start();
 
 let auth = null;
 if (settings.mode === 'clerk') {
   const { keys } = settings;
   const clerk = await loadClerkAdapter({ ...keys, authorizedParties: settings.authorizedParties });
-  const personAuth = createPersonAuth({ db: database.db, clerk, ...settings });
+  const personAuth = createPersonAuth({ db: database.db, clerk, ...settings, log });
   let clerkProxy = null;
   const proxyPath = resolveClerkProxyPath(keys.proxyUrl);
   if (proxyPath) {
@@ -129,7 +137,7 @@ const trustProxy = process.env.REPL_ID || process.env.REPLIT_DEPLOYMENT ? 1 : fa
 
 const updates = createUpdateChecker();
 
-createApp({ database, auth, trustProxy, updates, integrations, secrets, defaultFamily }).listen(port, () => {
+createApp({ database, auth, trustProxy, updates, integrations, secrets, defaultFamily, log }).listen(port, () => {
   console.log(`[flow] listening on ${port}; design system ${defaultFamily} (FLOW_THEME)`);
 });
 

package/server/integrations/adapters.js

@@ -1,6 +1,7 @@
 // The adapters this build of Flow ships. server/index.js registers each one;
 // FLOW_INTEGRATIONS chooses which are on (server/integrations/index.js).
 import { seazonaAdapter } from './seazona/index.js';
+import { sentryAdapter } from './sentry/index.js';
 import { xeroAdapter } from './xero/index.js';
 
-export const adapters = [seazonaAdapter, xeroAdapter];
+export const adapters = [seazonaAdapter, sentryAdapter, xeroAdapter];

package/server/integrations/port.js

@@ -12,12 +12,17 @@ import { isMissingTable, migrateAdapterSchema } from './schema.js';
 export const CAPABILITIES = Object.freeze([
   'pullWorkItems', // billable work since a cursor (Seazona: completed cases)
   '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)
+  'checkDrafts', // the accounting system's problems with Flow drafts, from its copy; null while not connected
+  'sendStatus', // { connected, writesAllowed }: may Flow send invoices now?
   'pushBill', // send an approved bill; the Flow record id is the idempotency key
   'pullPayments', // payments since a cursor, matched to invoices and bills
   'checkInvoice', // does the accounting system hold an invoice for a billable job? (the ledger's liveCheck)
   'listCustomers', // the system's customers, by id and name, for the identity map (Seazona: clients; Xero: contacts)
   'findInvoices', // sales invoices in the accounting system's copy, for the matcher; never a live call
   'health', // connection state for Settings
+  'captureError', // an error Flow logged, sent to the installation's own error service (Sentry)
+  'browserMonitoring', // the public settings a browser needs to report errors and problems to that service
 ]);
 
 const ID_PATTERN = /^[a-z][a-z0-9-]{1,31}$/;

package/server/integrations/seazona/ledger.js

@@ -48,6 +48,8 @@ export function toLedgerJob(item) {
     shippedOn: null,
     // The day of the work, for matching it to its accounting invoice.
     jobDate: item.invoice?.invoiceDate ?? item.dueOn ?? item.orderedOn ?? null,
+    // The draft rules bill only the statuses the lab chose (for example Shipped).
+    sourceStatus: item.status ?? null,
     lines: ledgerLinesFor(item).lines,
     observedAt: item.syncedAt,
     actor: SEAZONA_SOURCE_SYSTEM,

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
@@ -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/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) }),