@arcforgelabs/flow 2026.10.25 → 2026.10.27

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

@@ -57,6 +57,41 @@
       "when": 1792391146736,
       "tag": "0007_integration_settings",
       "breakpoints": true
+    },
+    {
+      "idx": 8,
+      "version": "7",
+      "when": 1792396463612,
+      "tag": "0008_people_appearance",
+      "breakpoints": true
+    },
+    {
+      "idx": 9,
+      "version": "7",
+      "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

@@ -9,6 +9,7 @@ import {
   integer,
   jsonb,
   pgTable,
+  primaryKey,
   text,
   timestamp,
   unique,
@@ -84,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) => [
@@ -96,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', {
@@ -153,7 +165,9 @@ export const PERSON_STATUSES = ['active', 'pending', 'disabled'];
 // someone is; this table decides what they may do. One installation serves one
 // lab, so people are installation-wide and carry no organisation_id. Emails
 // are stored lower-case. `clerk_user_id` is set on the person's first verified
-// sign-in; until then the row is an invitation.
+// sign-in; until then the row is an invitation. `appearance` is the person's
+// own design system, light or dark and accent (server/auth/people.js,
+// normaliseAppearance); null until they first choose.
 export const people = pgTable('people', {
   id: id(),
   email: text('email').notNull(),
@@ -163,6 +177,7 @@ export const people = pgTable('people', {
   clerkUserId: text('clerk_user_id'),
   invitedBy: uuid('invited_by').references(() => people.id, { onDelete: 'set null' }),
   linkedAt: timestamp('linked_at', { withTimezone: true }),
+  appearance: jsonb('appearance'),
   createdAt: createdAt(),
   updatedAt: updatedAt(),
 }, (t) => [
@@ -202,6 +217,16 @@ export const billingObligations = pgTable('billing_obligations', {
   contactId: uuid('contact_id'),
   practitioner: text('practitioner'),
   shippedOn: date('shipped_on'),
+  // 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(),
@@ -316,7 +341,9 @@ export const obligationWritebacks = pgTable('obligation_writebacks', {
 // one active link per external record and per Flow record, in each system. A
 // link that is not exact stays `proposed` until a person confirms it.
 export const LINK_ENTITIES = ['contact', 'price_item', 'obligation', 'invoice', 'payment', 'credit_note'];
-export const LINK_MATCHES = ['created_by_flow', 'exact_id', 'imported', 'name', 'person'];
+// `exact_name`: the same name, after spacing and case are evened out, held by
+// exactly one record on each side.
+export const LINK_MATCHES = ['created_by_flow', 'exact_id', 'exact_name', 'imported', 'name', 'person'];
 export const LINK_STATES = ['active', 'proposed', 'superseded'];
 
 export const externalLinks = pgTable('external_links', {
@@ -490,3 +517,160 @@ export const integrationSettingEvents = pgTable('integration_setting_events', {
   index('integration_setting_events_adapter').on(t.adapterId, t.createdAt),
   check('integration_setting_events_kind_valid', inList('kind', INTEGRATION_SETTING_EVENTS)),
 ]);
+
+// The pipeline (server/core/pipeline.js, issue 58). Where each step that reads
+// another system's records stands, by name, so a restart goes on from there.
+export const pipelineCursors = pgTable('pipeline_cursors', {
+  organisationId: organisationId().references(() => organisations.id),
+  name: text('name').notNull(),
+  cursor: text('cursor'),
+  updatedAt: updatedAt(),
+}, (t) => [
+  primaryKey({ name: 'pipeline_cursors_pk', columns: [t.organisationId, t.name] }),
+]);
+
+// The matcher's suggestions: accounting invoices that could bill a job, with
+// the signals that agreed. Only exact evidence links a job by itself; a
+// suggestion waits for a person. A newer run marks the ones it no longer
+// makes `stale`.
+export const LINK_SUGGESTION_STATES = ['open', 'accepted', 'rejected', 'stale'];
+
+export const linkSuggestions = pgTable('link_suggestions', {
+  id: id(),
+  organisationId: organisationId().references(() => organisations.id),
+  obligationId: uuid('obligation_id').notNull(),
+  system: text('system').notNull(),
+  externalId: text('external_id').notNull(),
+  externalNumber: text('external_number'),
+  score: integer('score').notNull(),
+  rank: integer('rank').notNull(),
+  signals: jsonb('signals').notNull().default(sql`'[]'::jsonb`),
+  state: text('state').notNull().default('open'),
+  decidedBy: text('decided_by'),
+  decidedAt: timestamp('decided_at', { withTimezone: true }),
+  createdAt: createdAt(),
+  updatedAt: updatedAt(),
+}, (t) => [
+  unique('link_suggestions_pair').on(t.organisationId, t.obligationId, t.system, t.externalId),
+  index('link_suggestions_open').on(t.organisationId, t.state, t.obligationId),
+  foreignKey({
+    name: 'link_suggestions_obligation_same_org',
+    columns: [t.organisationId, t.obligationId],
+    foreignColumns: [billingObligations.organisationId, billingObligations.id],
+  }),
+  check('link_suggestions_state_valid', inList('state', LINK_SUGGESTION_STATES)),
+]);
+
+// A person's "not this one": the matcher never suggests the pair again.
+export const linkRejections = pgTable('link_rejections', {
+  organisationId: organisationId().references(() => organisations.id),
+  obligationId: uuid('obligation_id').notNull(),
+  system: text('system').notNull(),
+  externalId: text('external_id').notNull(),
+  actor: text('actor').notNull(),
+  createdAt: createdAt(),
+}, (t) => [
+  primaryKey({ name: 'link_rejections_pk', columns: [t.organisationId, t.obligationId, t.system, t.externalId] }),
+  foreignKey({
+    name: 'link_rejections_obligation_same_org',
+    columns: [t.organisationId, t.obligationId],
+    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,6 +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';
@@ -65,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}`);
@@ -79,11 +85,22 @@ try {
 const integrationsOn = integrations.list().filter((a) => a.enabled).map((a) => `${a.id}${a.state === 'ready' ? '' : ` (${a.state})`}`);
 console.log(`[integrations] on: ${integrationsOn.join(', ') || 'none'}; secrets key ${secrets ? `from ${secrets.source}` : 'not set (FLOW_SECRETS_KEY)'}`);
 
+// The pipeline (server/core/pipeline.js) joins what the integrations copy into
+// Flow: jobs into the ledger, and each job to its accounting invoice. It runs
+// 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, 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) {
@@ -120,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,9 +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/feed.js

@@ -102,3 +102,14 @@ export async function readBillableWork(db, { cursor = null, limit = 200 } = {})
     more: rows.length === pageSize,
   };
 }
+
+// Seazona clients, by id and the company name an invoice bills. A client
+// with no company name is listed by its full name.
+export async function listClients(db) {
+  const rows = await db.select({ id: seazonaClients.id, company: seazonaClients.company, fullName: seazonaClients.fullName, active: seazonaClients.active })
+    .from(seazonaClients);
+  return rows
+    .filter((r) => r.active !== false)
+    .map((r) => ({ id: r.id, name: (r.company || r.fullName || '').trim() }))
+    .filter((r) => r.name);
+}

package/server/integrations/seazona/index.js

@@ -1,5 +1,5 @@
 import { createSeazonaClient } from './client.js';
-import { readBillableWork } from './feed.js';
+import { listClients, readBillableWork } from './feed.js';
 import { readSeazonaSyncHealth, runSeazonaSync } from './lanes.js';
 import { createSeazonaScheduler } from './scheduler.js';
 import { describeSeazonaSettings, resolveSeazonaSettings } from './settings.js';
@@ -99,6 +99,12 @@ export function createSeazonaAdapter({ env = null, fetchImpl = null, now = Date.
       async pullWorkItems(cursor = null, options = {}) {
         return readBillableWork(current().db, { cursor, ...options });
       },
+
+      // Seazona clients by id and company name, for the identity map. Reads
+      // Flow's copy only.
+      async listCustomers() {
+        return listClients(current().db);
+      },
     },
   };
 }

package/server/integrations/seazona/ledger.js

@@ -46,6 +46,10 @@ export function toLedgerJob(item) {
     practitioner: item.doctorName ?? null,
     // The Seazona API gives a shipped status but no shipped date.
     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 }) {