@arcforgelabs/flow 2026.10.22 → 2026.10.23

package/server/integrations/setup.js

@@ -0,0 +1,234 @@
+import { eq, sql } from 'drizzle-orm';
+import express from 'express';
+import { FlowError } from '../core/errors.js';
+import { deriveKey, openSecret, sealSecret } from '../core/secrets.js';
+import { integrationSettingEvents, integrationSettings, organisations } from '../db/schema.js';
+
+// Integration setup in Settings (docs/INTEGRATIONS.md, "Set up in Flow"). An
+// owner turns an integration on and enters its settings in the app; no one
+// edits the host's secrets. Plain settings are stored by their environment
+// name; credentials are sealed with Flow's secrets key. Each adapter reads
+// the result as its environment: the host's own environment wins, then the
+// stored settings, then each derived key. A change applies at once
+// (registry.reconfigure), without a restart.
+
+const MAX_VALUE = 2000;
+const ONOFF = ['on', 'off'];
+const context = (adapterId, name) => `integration:${adapterId}:${name}`;
+
+const hostValue = (env, name) => String(env[name] ?? '').trim();
+
+export async function readStoredSettings(db) {
+  const rows = await db.select().from(integrationSettings);
+  return new Map(rows.map((row) => [row.adapterId, row]));
+}
+
+// The ids the host turns on (FLOW_INTEGRATIONS) and the ids an owner turned
+// on in Settings.
+export function hostEnabled(env) {
+  return new Set((env.FLOW_INTEGRATIONS ?? '').split(',').map((id) => id.trim().toLowerCase()).filter(Boolean));
+}
+
+// Builds the environment the adapters read: the stored settings, then the
+// host's environment over them. A credential that cannot be opened (the key
+// changed) is left out and reported. Never logs a value.
+export function settingsEnvironment({ env, stored, adapters, secrets }) {
+  const merged = {};
+  const unreadable = [];
+  for (const adapter of adapters) {
+    const row = stored.get(adapter.id);
+    if (!adapter.setup) continue;
+    for (const field of adapter.setup.fields) {
+      if (field.secret) {
+        const sealed = row?.secrets?.[field.name];
+        if (!sealed) continue;
+        try {
+          merged[field.name] = openSecret(secrets, sealed, context(adapter.id, field.name));
+        } catch {
+          unreadable.push(`${adapter.id}:${field.name}`);
+        }
+      } else if (row?.config?.[field.name] != null) {
+        merged[field.name] = String(row.config[field.name]);
+      }
+    }
+    if (secrets) {
+      for (const name of adapter.setup.derivedKeys) merged[name] = deriveKey(secrets, name).toString('hex');
+    }
+  }
+  for (const [name, value] of Object.entries(env)) {
+    if (value != null && String(value).trim() !== '') merged[name] = value;
+  }
+  return { env: merged, unreadable };
+}
+
+// The adapters an owner turned on in Settings and the host does not.
+export function storedEnabled(stored, env) {
+  const host = hostEnabled(env);
+  return [...stored.values()].filter((row) => row.enabled && !host.has(row.adapterId)).map((row) => row.adapterId);
+}
+
+// What Settings shows for one adapter. A credential shows only whether it
+// is set and where from; never its value.
+export function describeSetup({ adapter, row, env, secrets, entry, unreadable = [] }) {
+  const host = hostEnabled(env);
+  const fields = adapter.setup.fields.map((field) => {
+    const fromHost = hostValue(env, field.name) !== '';
+    const base = {
+      name: field.name,
+      label: field.label,
+      kind: field.kind ?? 'text',
+      secret: Boolean(field.secret),
+      help: field.help ?? null,
+      choices: field.choices ?? null,
+      suggest: field.suggest ?? null,
+      source: fromHost ? 'host' : null,
+    };
+    if (field.secret) {
+      const storedHere = Boolean(row?.secrets?.[field.name]);
+      return {
+        ...base,
+        set: fromHost || (storedHere && !unreadable.includes(`${adapter.id}:${field.name}`)),
+        source: fromHost ? 'host' : storedHere ? 'flow' : null,
+        unreadable: !fromHost && unreadable.includes(`${adapter.id}:${field.name}`),
+      };
+    }
+    const value = fromHost ? hostValue(env, field.name) : (row?.config?.[field.name] ?? null);
+    return { ...base, value, source: fromHost ? 'host' : value != null ? 'flow' : null };
+  });
+  return {
+    id: adapter.id,
+    name: adapter.name,
+    enabled: entry?.enabled ?? false,
+    enabledBy: host.has(adapter.id) ? 'host' : row?.enabled ? 'flow' : null,
+    state: entry?.state ?? 'disabled',
+    error: entry?.error ?? null,
+    guide: adapter.setup.guide,
+    fields,
+    updatedAt: row?.updatedAt ?? null,
+  };
+}
+
+function checkValue(field, value) {
+  if (value === null) return null;
+  if (typeof value !== 'string') throw new FlowError('invalid', `${field.label} must be text`);
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+  if (trimmed.length > MAX_VALUE) throw new FlowError('invalid', `${field.label} is too long`);
+  if (field.kind === 'choice' && !field.choices.some((c) => c.value === trimmed)) {
+    throw new FlowError('invalid', `${field.label} must be one of ${field.choices.map((c) => c.value).join(', ')}`);
+  }
+  if (field.kind === 'onoff' && !ONOFF.includes(trimmed)) throw new FlowError('invalid', `${field.label} must be on or off`);
+  if (field.kind === 'url') {
+    let url;
+    try {
+      url = new URL(trimmed);
+    } catch {
+      throw new FlowError('invalid', `${field.label} must be an address that starts with https://`);
+    }
+    if (url.protocol !== 'https:' && url.hostname !== 'localhost') throw new FlowError('invalid', `${field.label} must start with https://`);
+  }
+  if (field.secret && /\s/.test(trimmed)) throw new FlowError('invalid', `${field.label} must be one value with no spaces`);
+  return trimmed;
+}
+
+// Stores an owner's change: `enabled` (optional) and `values` by setting
+// name (null removes one). Answers the event kinds written.
+export async function saveSettings(db, { adapter, secrets, actor, enabled, values = {} }) {
+  if (!adapter.setup) throw new FlowError('invalid', `${adapter.name} has no settings here`);
+  const byName = new Map(adapter.setup.fields.map((f) => [f.name, f]));
+  const unknown = Object.keys(values).filter((name) => !byName.has(name));
+  if (unknown.length) throw new FlowError('invalid', `unknown setting: ${unknown.join(', ')}`);
+  const checked = Object.entries(values).map(([name, value]) => [byName.get(name), checkValue(byName.get(name), value)]);
+  if (checked.some(([field, value]) => field.secret && value !== null) && !secrets) {
+    throw new FlowError('secrets_key_missing', 'Flow has no secrets key. Set FLOW_SECRETS_KEY (or SESSION_SECRET) on the host, then restart.');
+  }
+  return db.transaction(async (tx) => {
+    await tx.execute(sql`select pg_advisory_xact_lock(hashtextextended(${`integration_settings:${adapter.id}`}, 0))`);
+    const [row] = await tx.select().from(integrationSettings).where(eq(integrationSettings.adapterId, adapter.id));
+    const config = { ...(row?.config ?? {}) };
+    const sealed = { ...(row?.secrets ?? {}) };
+    const events = [];
+    const changed = [];
+    for (const [field, value] of checked) {
+      if (field.secret) {
+        if (value === null) {
+          if (sealed[field.name]) { delete sealed[field.name]; events.push({ kind: 'secret_removed', settings: [field.name] }); }
+        } else {
+          sealed[field.name] = sealSecret(secrets, value, context(adapter.id, field.name));
+          events.push({ kind: 'secret_set', settings: [field.name] });
+        }
+      } else if ((config[field.name] ?? null) !== value) {
+        if (value === null) delete config[field.name];
+        else config[field.name] = value;
+        changed.push(field.name);
+      }
+    }
+    if (changed.length) events.push({ kind: 'setting_changed', settings: changed });
+    const on = enabled ?? row?.enabled ?? false;
+    if (enabled !== undefined && enabled !== (row?.enabled ?? false)) events.push({ kind: enabled ? 'turned_on' : 'turned_off', settings: [] });
+    await tx.insert(integrationSettings)
+      .values({ adapterId: adapter.id, enabled: on, config, secrets: sealed, updatedBy: actor })
+      .onConflictDoUpdate({
+        target: integrationSettings.adapterId,
+        set: { enabled: on, config, secrets: sealed, updatedBy: actor, updatedAt: sql`now()` },
+      });
+    for (const event of events) {
+      await tx.insert(integrationSettingEvents).values({ adapterId: adapter.id, actor, ...event });
+    }
+    return events.map((e) => e.kind);
+  });
+}
+
+// GET /api/integrations (owner): every adapter with settings, its state and
+// what is set. PUT /api/integrations/:id (owner): save and apply.
+export function createSetupRouter({ db, registry, personAuth, secrets, baseEnv = process.env, log = console }) {
+  const router = express.Router();
+  const owner = [personAuth.requireSession, personAuth.requireRole('owner')];
+  // A change needs a verified owner sign-in, as connecting Xero does.
+  const verifiedOwner = [personAuth.requireSession, personAuth.requireOwner];
+
+  const describeAll = async () => {
+    const stored = await readStoredSettings(db);
+    const adapters = registry.list().filter((entry) => registry.get(entry.id).setup);
+    const { unreadable } = settingsEnvironment({ env: {}, stored, adapters: adapters.map((e) => registry.get(e.id)), secrets });
+    return adapters.map((entry) => describeSetup({
+      adapter: registry.get(entry.id), row: stored.get(entry.id), env: baseEnv, secrets, entry, unreadable,
+    }));
+  };
+
+  router.get('/', ...owner, async (_req, res, next) => {
+    try {
+      const labs = await db.select({ id: organisations.id, name: organisations.name }).from(organisations);
+      res.json({ ok: true, secretsKey: secrets ? { source: secrets.source, id: secrets.id } : null, organisations: labs, integrations: await describeAll() });
+    } catch (error) { next(error); }
+  });
+
+  router.put('/:id', ...verifiedOwner, express.json({ limit: '32kb' }), async (req, res) => {
+    const adapter = registry.get(req.params.id);
+    if (!adapter?.setup) return res.status(404).json({ ok: false, code: 'not_found', error: 'No such integration' });
+    try {
+      const { enabled, values } = req.body ?? {};
+      if (enabled !== undefined && typeof enabled !== 'boolean') throw new FlowError('invalid', 'enabled must be true or false');
+      if (enabled === false && hostEnabled(baseEnv).has(adapter.id)) {
+        throw new FlowError('invalid', `${adapter.name} is turned on by the host (FLOW_INTEGRATIONS). Turn it off there.`);
+      }
+      const events = await saveSettings(db, { adapter, secrets, actor: req.person.id, enabled, values: values ?? {} });
+      const stored = await readStoredSettings(db);
+      const { env } = settingsEnvironment({ env: baseEnv, stored, adapters: [...registry.list().map((e) => registry.get(e.id))], secrets });
+      const on = hostEnabled(baseEnv).has(adapter.id) || Boolean(stored.get(adapter.id)?.enabled);
+      const state = await registry.reconfigure(adapter.id, { enabled: on, env });
+      log.info?.(`[integrations] ${adapter.id} settings changed by person ${req.person.id} (${events.join(', ') || 'no change'}); now ${state}`);
+      const entry = registry.list().find((e) => e.id === adapter.id);
+      const { unreadable } = settingsEnvironment({ env: {}, stored, adapters: [adapter], secrets });
+      return res.json({ ok: true, integration: describeSetup({ adapter, row: stored.get(adapter.id), env: baseEnv, secrets, entry, unreadable }) });
+    } catch (error) {
+      if (error instanceof FlowError) {
+        return res.status(error.code === 'secrets_key_missing' ? 409 : 400).json({ ok: false, code: error.code, error: error.message });
+      }
+      log.error?.(`[integrations] saving ${adapter.id} settings failed: ${error.message}`);
+      return res.status(500).json({ ok: false, code: 'error', error: 'Saving the settings failed.' });
+    }
+  });
+
+  return router;
+}

package/server/integrations/xero/client.js

@@ -9,6 +9,7 @@ import { XERO_ENDPOINTS } from './settings.js';
 export const DEFAULT_TIMEOUT_MS = 15_000;
 export const DEFAULT_ATTEMPTS = 2;
 export const XERO_PAGE_SIZE = 100;
+const MIRROR_PATHS = Object.freeze({ invoices: 'Invoices', credit_notes: 'CreditNotes', payments: 'Payments' });
 
 export function xeroError(code, message, { status = 502, ...extra } = {}) {
   const error = new FlowError(code, message, extra.details);
@@ -230,6 +231,18 @@ export function createXeroClient({
         headers: { 'If-Modified-Since': since.toISOString().replace(/\.\d{3}Z$/, '') },
       })).Payments, { maxPages });
     },
+    // One page of invoices, credit notes or payments changed since
+    // `modifiedSince` (a Date, or null for all), oldest change first. The
+    // mirror (mirror.js) pages by that time, so it never skips a record.
+    async listChangedPage(resource, { page = 1, pageSize = XERO_PAGE_SIZE, modifiedSince = null } = {}) {
+      const path = MIRROR_PATHS[resource];
+      if (!path) throw new TypeError(`listChangedPage: unknown resource ${resource}`);
+      const payload = await request('GET', path, {
+        query: { page, pageSize, order: 'UpdatedDateUTC ASC' },
+        headers: modifiedSince ? { 'If-Modified-Since': modifiedSince.toISOString().replace(/\.\d{3}Z$/, '') } : {},
+      });
+      return payload[path] ?? [];
+    },
     // 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/import.js

@@ -0,0 +1,116 @@
+import { randomUUID } from 'node:crypto';
+import { sql } from 'drizzle-orm';
+import { enqueueJob, runNextJob } from '../../core/queue.js';
+import { MIRROR_RESOURCES, mirrorXero } from './mirror.js';
+
+// The history import. When an owner connects Xero, Flow copies the
+// organisation's invoices, credit notes and payments into the mirror
+// (mirror.js) as a background job, so nobody runs a script by hand. The job
+// reads in slices; a slice that stops at the day's budget or its page limit
+// queues the next slice. It only reads from Xero.
+
+export const IMPORT_KIND = 'xero.import';
+const IMPORT_KEY = 'history';
+// Pages per resource in one slice, so one job stays well inside its lease.
+const SLICE_PAGES = 20;
+const LEASE_MS = 30 * 60 * 1000;
+// Xero's day limit resets on a rolling day; an hour is a cheap re-check.
+const BUDGET_WAIT_MS = 60 * 60 * 1000;
+const IDLE_MS = 30 * 1000;
+
+export async function queueHistoryImport(db, organisationId, { reason = 'connected', runAfter = null } = {}) {
+  return enqueueJob(db, organisationId, { kind: IMPORT_KIND, dedupeKey: IMPORT_KEY, payload: { reason }, runAfter });
+}
+
+// Forgets where the copy stands, so the next slice reads from the start.
+// Rows already copied stay; a re-read updates them.
+export async function resetImport(db, organisationId) {
+  await db.execute(sql`delete from xero_mirror_cursors where organisation_id = ${organisationId}`);
+}
+
+// Organisations connected in this mode whose history is not yet complete: a
+// resource with no finished pass. Start-up queues these, so an installation
+// connected before this release imports too.
+export async function organisationsToImport(db, mode) {
+  const { rows } = await db.execute(sql`
+    select c.organisation_id from xero_connections c
+    where c.mode = ${mode}
+      and (select count(*) from xero_mirror_cursors m
+           where m.organisation_id = c.organisation_id and m.passes > 0) < ${MIRROR_RESOURCES.length}`);
+  return rows.map((r) => r.organisation_id);
+}
+
+// One slice of the import for one job. Answers what it read and whether more
+// remains (`more`: 'budget' or 'max_pages').
+export async function runImportSlice(db, runtime, job, { maxPages = SLICE_PAGES } = {}) {
+  const results = await mirrorXero(db, runtime, job.organisationId, { maxPages });
+  const stopped = results.find((r) => r.stopped !== 'done')?.stopped ?? null;
+  return { results, more: stopped };
+}
+
+// Claims and runs one due import job, then queues the next slice when one is
+// needed. Answers the queue's outcome, or null when nothing was due.
+export async function runImportOnce(db, runtime, { workerId = `xero-import-${randomUUID()}`, maxPages, now = Date.now } = {}) {
+  const ran = await runNextJob(db, {
+    workerId,
+    leaseMs: LEASE_MS,
+    handlers: { [IMPORT_KIND]: (job) => runImportSlice(db, runtime, job, { maxPages }) },
+  });
+  if (ran?.outcome === 'succeeded' && ran.job.result?.more) {
+    const wait = ran.job.result.more === 'budget' ? BUDGET_WAIT_MS : 0;
+    await queueHistoryImport(db, ran.job.organisationId, { reason: ran.job.result.more, runAfter: new Date(Number(now()) + wait) });
+  }
+  return ran;
+}
+
+// The background worker: runs due slices one at a time, then waits. Started
+// by the adapter outside replay mode; stop() waits for a slice in flight.
+export function createImportWorker({ db, runtime, log = console, timers = { setTimeout, clearTimeout }, firstDelayMs = 10_000 }) {
+  const workerId = `xero-import-${randomUUID()}`;
+  let timer = null;
+  let running = null;
+  let stopped = true;
+
+  function schedule(delayMs) {
+    if (stopped) return;
+    timer = timers.setTimeout(tick, delayMs);
+    timer?.unref?.();
+  }
+
+  async function tick() {
+    timer = null;
+    if (stopped) return;
+    let busy = false;
+    running = (async () => {
+      try {
+        const ran = await runImportOnce(db, runtime, { workerId });
+        if (ran) {
+          busy = true;
+          const read = (ran.job.result?.results ?? []).map((r) => `${r.resource} ${r.read}`).join(', ');
+          log.info?.(`[xero] import ${ran.outcome} for organisation ${ran.job.organisationId}${read ? `: ${read}` : ''}${ran.job.result?.more ? `; more (${ran.job.result.more})` : ''}`);
+        }
+      } catch (error) {
+        log.error?.(`[xero] import worker: ${error?.code ?? 'error'}: ${error?.message ?? error}`);
+      }
+    })();
+    await running;
+    running = null;
+    schedule(busy ? 0 : IDLE_MS);
+  }
+
+  return {
+    async start() {
+      stopped = false;
+      for (const organisationId of await organisationsToImport(db, runtime.settings.mode)) {
+        await queueHistoryImport(db, organisationId, { reason: 'start' });
+      }
+      schedule(firstDelayMs);
+    },
+    async stop() {
+      stopped = true;
+      if (timer) timers.clearTimeout(timer);
+      timer = null;
+      await running;
+    },
+  };
+}

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 { createImportWorker } from './import.js';
 import { readPayments } from './ledger.js';
 import { createXeroRouter } from './routes.js';
 import { createXeroRuntime, requireXeroSettings } from './runtime.js';
@@ -10,14 +11,40 @@ import { writesAllowed } from './settings.js';
 // XERO_MODE says which Xero it acts on. Its tables are created only while it
 // is on (docs/INTEGRATIONS.md).
 
-export const XERO_TABLES = Object.freeze(['xero_connections', 'xero_contacts', 'xero_items', 'xero_sync_runs', 'xero_invoice_pushes', 'xero_payment_cursors']);
+export const XERO_TABLES = Object.freeze(['xero_connections', 'xero_contacts', 'xero_items', 'xero_sync_runs', 'xero_invoice_pushes', 'xero_payment_cursors', 'xero_invoices', 'xero_credit_notes', 'xero_payments', 'xero_mirror_cursors']);
 
-// `runtime` is for tests. Otherwise start() builds it from the environment,
-// so a turned-off adapter never reads its settings, and a malformed setting
-// stops boot when Xero is on.
+// What an owner enters in Settings, Integrations (server/integrations/setup.js).
+// The refresh token's key comes from Flow's secrets key.
+export const XERO_SETUP = {
+  guide: {
+    title: 'Create your own Xero app',
+    link: 'https://developer.xero.com/app/manage',
+    steps: [
+      'Sign in at developer.xero.com with a Xero login that can manage the organisation, and open My Apps.',
+      'Press New app. Name it, for example "Flow". Choose Web app.',
+      'Company or application URL: this installation\'s address.',
+      'Redirect URI: copy it from below, exactly.',
+      'Open the app\'s Configuration. Copy the client id. Generate a secret and copy it: Xero shows it once.',
+      'Paste both below, choose the mode, name your Xero organisation, and turn Xero on.',
+    ],
+  },
+  fields: [
+    { name: 'XERO_MODE', label: 'Mode', kind: 'choice', choices: [{ value: 'live', label: 'Live: your Xero organisation' }, { value: 'sandbox', label: 'Sandbox: a Xero Demo Company' }] },
+    { name: 'XERO_REDIRECT_URI', label: 'Redirect URI', kind: 'url', suggest: 'callback', help: 'This installation\'s address plus /api/xero/oauth/callback. Register the same address on the Xero app.' },
+    { name: 'XERO_CLIENT_ID', label: 'Client id', help: 'From the Xero app\'s Configuration.' },
+    { name: 'XERO_CLIENT_SECRET', label: 'Client secret', secret: true, help: 'Stored encrypted. Flow never shows it again.' },
+    { name: 'XERO_TENANT_NAME', label: 'Xero organisation name', help: 'Live mode connects only the organisation with this exact name.' },
+    { name: 'XERO_ALLOW_LIVE_WRITES', label: 'Create draft invoices in live Xero', kind: 'onoff', help: 'Off: Flow only reads from Xero.' },
+  ],
+  derivedKeys: ['XERO_TOKEN_KEY'],
+};
+
+// `runtime` is for tests. Otherwise start() builds it from its settings, so a
+// turned-off adapter never reads them, and a malformed setting stops it.
 export function createXeroAdapter({ runtime: given = null } = {}) {
   let runtime = given;
   let database = null;
+  let importer = null;
   const current = () => {
     runtime ??= createXeroRuntime({ settings: requireXeroSettings(process.env) });
     return runtime;
@@ -31,10 +58,23 @@ export function createXeroAdapter({ runtime: given = null } = {}) {
       migrationsFolder: fileURLToPath(new URL('./migrations', import.meta.url)),
       tables: [...XERO_TABLES],
     },
-    async start({ db, log }) {
+    setup: XERO_SETUP,
+    async start({ db, log, env }) {
       database = db;
+      if (!given) runtime = createXeroRuntime({ settings: requireXeroSettings(env ?? process.env) });
       const { settings } = current();
       log.info?.(`[xero] mode ${settings.mode}; writes ${writesAllowed(settings) ? 'on' : 'off (XERO_ALLOW_LIVE_WRITES)'}; redirect URI ${settings.redirectUri ?? 'not set (FLOW_PUBLIC_ORIGIN)'}`);
+      // The history import (import.js) runs in the background outside replay
+      // mode. Replay tests run its slices directly.
+      if (settings.mode !== 'replay') {
+        importer = createImportWorker({ db, runtime: current(), log });
+        await importer.start();
+      }
+    },
+    async stop() {
+      await importer?.stop();
+      importer = null;
+      runtime = given;
     },
     capabilities: {
       async health() {

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

@@ -0,0 +1,96 @@
+-- Flow's copy of the connected organisation's Xero invoices, credit notes and
+-- payments (docs/DATA_SPINE.md, issue 54). Xero owns these records; Flow keeps
+-- them so it can report on years of history and link them to its own records
+-- 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" (
+	"organisation_id" uuid NOT NULL REFERENCES "organisations"("id"),
+	"xero_invoice_id" text NOT NULL,
+	"type" text NOT NULL,
+	"invoice_number" text,
+	"reference" text,
+	"xero_contact_id" text,
+	"status" text NOT NULL,
+	"issued_on" date,
+	"due_on" date,
+	"fully_paid_on" date,
+	"currency" text,
+	"subtotal_cents" bigint,
+	"tax_cents" bigint,
+	"total_cents" bigint,
+	"amount_due_cents" bigint,
+	"amount_paid_cents" bigint,
+	"amount_credited_cents" bigint,
+	"lines" jsonb DEFAULT '[]'::jsonb NOT NULL,
+	"xero_updated_at" timestamp with time zone,
+	"record_hash" text NOT NULL,
+	"first_seen_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"last_changed_at" timestamp with time zone DEFAULT now() NOT NULL,
+	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");
+--> statement-breakpoint
+CREATE INDEX "xero_invoices_contact" ON "xero_invoices" ("organisation_id", "xero_contact_id", "issued_on");
+--> statement-breakpoint
+CREATE TABLE "xero_credit_notes" (
+	"organisation_id" uuid NOT NULL REFERENCES "organisations"("id"),
+	"xero_credit_note_id" text NOT NULL,
+	"type" text NOT NULL,
+	"credit_note_number" text,
+	"reference" text,
+	"xero_contact_id" text,
+	"status" text NOT NULL,
+	"issued_on" date,
+	"currency" text,
+	"subtotal_cents" bigint,
+	"tax_cents" bigint,
+	"total_cents" bigint,
+	"remaining_credit_cents" bigint,
+	"allocations" jsonb DEFAULT '[]'::jsonb NOT NULL,
+	"lines" jsonb DEFAULT '[]'::jsonb NOT NULL,
+	"xero_updated_at" timestamp with time zone,
+	"record_hash" text NOT NULL,
+	"first_seen_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"last_changed_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "xero_credit_notes_pk" PRIMARY KEY("organisation_id", "xero_credit_note_id")
+);
+--> statement-breakpoint
+CREATE TABLE "xero_payments" (
+	"organisation_id" uuid NOT NULL REFERENCES "organisations"("id"),
+	"xero_payment_id" text NOT NULL,
+	"payment_type" text,
+	"status" text NOT NULL,
+	"xero_invoice_id" text,
+	"xero_credit_note_id" text,
+	"paid_on" date,
+	"amount_cents" bigint,
+	"reference" text,
+	"is_reconciled" boolean,
+	"xero_updated_at" timestamp with time zone,
+	"record_hash" text NOT NULL,
+	"first_seen_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"last_changed_at" timestamp with time zone DEFAULT now() NOT NULL,
+	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");
+--> 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" (
+	"organisation_id" uuid NOT NULL REFERENCES "organisations"("id"),
+	"resource" text NOT NULL,
+	"modified_since" timestamp with time zone,
+	"page" integer DEFAULT 1 NOT NULL,
+	"passes" integer DEFAULT 0 NOT NULL,
+	"rows_read" bigint DEFAULT 0 NOT NULL,
+	"last_read_at" timestamp with time zone,
+	"last_pass_finished_at" timestamp with time zone,
+	"last_error" text,
+	CONSTRAINT "xero_mirror_cursors_pk" PRIMARY KEY("organisation_id", "resource"),
+	CONSTRAINT "xero_mirror_cursors_resource_valid" CHECK ("resource" in ('invoices', 'credit_notes', 'payments')),
+	CONSTRAINT "xero_mirror_cursors_page_positive" CHECK ("page" > 0)
+);

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

@@ -29,6 +29,13 @@
       "when": 1792368180000,
       "tag": "0003_xero_payment_cursors",
       "breakpoints": true
+    },
+    {
+      "idx": 4,
+      "version": "7",
+      "when": 1792388000000,
+      "tag": "0004_xero_mirror",
+      "breakpoints": true
     }
   ]
 }