@arcforgelabs/flow 2026.10.18 → 2026.10.19

package/server/integrations/port.js

@@ -2,6 +2,12 @@
 // adapter (Seazona, Xero, and later ones). The core calls only the
 // capabilities an adapter declares, and never imports an adapter directly.
 // VISION.md, "The core and its integrations".
+//
+// An adapter owns its tables. It declares them in `schema` with its own
+// migrations, and Flow creates them only while the adapter is enabled
+// (server/integrations/schema.js). docs/INTEGRATIONS.md has the rules.
+
+import { isMissingTable, migrateAdapterSchema } from './schema.js';
 
 export const CAPABILITIES = Object.freeze([
   'pullWorkItems', // billable work since a cursor (Seazona: completed cases)
@@ -12,12 +18,50 @@ export const CAPABILITIES = Object.freeze([
 ]);
 
 const ID_PATTERN = /^[a-z][a-z0-9-]{1,31}$/;
+const TABLE_PATTERN = /^[a-z][a-z0-9_]{0,62}$/;
+
+// An adapter's tables start with its id (dashes become underscores), so they
+// can never collide with the core's or another adapter's.
+export function tablePrefix(id) {
+  return `${id.replaceAll('-', '_')}_`;
+}
+
+function defineSchema(id, schema) {
+  if (schema === undefined || schema === null) return null;
+  const { migrationsFolder, tables } = schema;
+  if (typeof migrationsFolder !== 'string' || migrationsFolder === '') {
+    throw new TypeError(`Adapter ${id} schema needs a migrationsFolder`);
+  }
+  if (!Array.isArray(tables) || tables.length === 0) {
+    throw new TypeError(`Adapter ${id} schema must list its tables`);
+  }
+  const prefix = tablePrefix(id);
+  for (const table of tables) {
+    if (typeof table !== 'string' || !TABLE_PATTERN.test(table) || !table.startsWith(prefix)) {
+      throw new TypeError(`Adapter ${id} table ${table} must be a lower-case name that starts with ${prefix}`);
+    }
+  }
+  return Object.freeze({ migrationsFolder, tables: Object.freeze([...new Set(tables)]) });
+}
+
+// What code gets when it asks for an adapter that is off, instead of an error
+// from a table that does not exist. `reason` is `disabled` (turned off),
+// `restart_needed` (turned on after this start: its tables come at the next
+// start) or `tables_missing` (its tables were removed by hand).
+export function turnedOff(adapter, reason = 'disabled') {
+  const error = {
+    disabled: `${adapter.name} is turned off on this installation.`,
+    restart_needed: `${adapter.name} was turned on after Flow started. Restart Flow to finish turning it on.`,
+    tables_missing: `${adapter.name} has no tables on this installation. Restart Flow to create them.`,
+  }[reason];
+  return { ok: false, code: 'integration_off', integration: adapter.id, reason, error };
+}
 
 export function defineAdapter(adapter) {
   if (!adapter || typeof adapter !== 'object') {
     throw new TypeError('An adapter must be an object');
   }
-  const { id, name, bundled = false, capabilities } = adapter;
+  const { id, name, bundled = false, capabilities, schema, start, stop, routes } = adapter;
   if (typeof id !== 'string' || !ID_PATTERN.test(id)) {
     throw new TypeError(`Adapter id must match ${ID_PATTERN}`);
   }
@@ -38,12 +82,47 @@ export function defineAdapter(adapter) {
   if (typeof capabilities.health !== 'function') {
     throw new TypeError(`Adapter ${id} must declare health`);
   }
-  return Object.freeze({ id, name, bundled: Boolean(bundled), capabilities: Object.freeze({ ...capabilities }) });
+  for (const [hook, fn] of Object.entries({ start, stop })) {
+    if (fn !== undefined && typeof fn !== 'function') {
+      throw new TypeError(`Adapter ${id} ${hook} must be a function`);
+    }
+  }
+  if (routes !== undefined && typeof routes !== 'function') {
+    throw new TypeError(`Adapter ${id} routes must be a function that returns a router`);
+  }
+  return Object.freeze({
+    id,
+    name,
+    bundled: Boolean(bundled),
+    capabilities: Object.freeze({ ...capabilities }),
+    schema: defineSchema(id, schema),
+    // Optional lifecycle: start({ db, log }) runs once at server start, after
+    // the adapter's tables are in place, and only while it is enabled; it is
+    // where an adapter keeps its database handle and starts background work.
+    // stop() ends that work (tests, shutdown).
+    start: start ?? null,
+    stop: stop ?? null,
+    // Optional HTTP routes: routes({ db, personAuth, log }) returns a router
+    // mounted at /api/<id> (registry.routes).
+    routes: routes ?? null,
+  });
 }
 
-export function createRegistry() {
+export function createRegistry({ log = console } = {}) {
   const adapters = new Map();
   const enabled = new Set();
+  // Adapters whose tables this process created or found at start. An adapter
+  // without a schema needs none, so it is ready as soon as it is enabled.
+  const tablesReady = new Set();
+  let started = false;
+  const running = []; // adapters whose start() ran, in start order
+
+  const state = (adapter) => {
+    if (!enabled.has(adapter.id)) return 'disabled';
+    if (!adapter.schema || tablesReady.has(adapter.id)) return 'ready';
+    return started ? 'restart_needed' : 'not_started';
+  };
+  const ready = (adapter) => state(adapter) === 'ready';
 
   return {
     register(adapter) {
@@ -58,27 +137,96 @@ export function createRegistry() {
       if (!adapters.has(id)) throw new Error(`No adapter ${id}`);
       enabled.add(id);
     },
+    // Turning an adapter off never drops its tables. Removing them is a
+    // separate step (removeAdapterTables in server/integrations/schema.js).
     disable(id) {
       enabled.delete(id);
     },
+    // Runs once at server start, after the core migrations: creates the
+    // tables of every enabled adapter and nothing else, then calls each
+    // enabled adapter's start({ db, log }). An adapter turned on later gets
+    // its tables at the next start. Returns the ids it migrated.
+    async start(db) {
+      if (started) throw new Error('The integration registry has already started');
+      started = true;
+      const migrated = [];
+      for (const id of enabled) {
+        const adapter = adapters.get(id);
+        if (!adapter.schema) continue;
+        await migrateAdapterSchema(db, adapter);
+        tablesReady.add(id);
+        migrated.push(id);
+      }
+      for (const id of enabled) {
+        const adapter = adapters.get(id);
+        if (!adapter.start) continue;
+        await adapter.start({ db, log });
+        running.push(adapter);
+      }
+      return migrated;
+    },
+    // Calls stop() on every adapter whose start() ran, newest first.
+    async stop() {
+      while (running.length) {
+        const adapter = running.pop();
+        await adapter.stop?.();
+      }
+    },
     list() {
       return [...adapters.values()].map((a) => ({
         id: a.id,
         name: a.name,
         bundled: a.bundled,
         enabled: enabled.has(a.id),
+        state: state(a),
+        tables: a.schema ? [...a.schema.tables] : [],
         capabilities: Object.keys(a.capabilities),
       }));
     },
-    // The enabled adapters that declare one capability. The core fans out to
-    // these and nothing else, so a disabled adapter changes nothing.
+    // The enabled adapters, with their tables in place, that declare one
+    // capability. The core fans out to these and nothing else, so a disabled
+    // adapter changes nothing.
     with(capability) {
       if (!CAPABILITIES.includes(capability)) {
         throw new TypeError(`Unknown capability ${capability}`);
       }
       return [...enabled]
         .map((id) => adapters.get(id))
-        .filter((a) => typeof a.capabilities[capability] === 'function');
+        .filter((a) => ready(a) && typeof a.capabilities[capability] === 'function');
+    },
+    // The adapters' own HTTP routes, each under /api/<id>. `context` is
+    // { db, personAuth, log }. An enabled, ready adapter's router is built
+    // once, here; a request to an adapter that is off gets its turned-off
+    // answer (503), so a turned-off adapter never reads its settings or
+    // tables.
+    routes(context) {
+      return [...adapters.values()].filter((a) => a.routes).map((adapter) => {
+        const path = `/api/${adapter.id}`;
+        if (!ready(adapter)) {
+          return { path, handler: (_req, res) => res.status(503).json(turnedOff(adapter, state(adapter) === 'disabled' ? 'disabled' : 'restart_needed')) };
+        }
+        return { path, handler: adapter.routes(context) };
+      });
+    },
+    // The one way to read or write an adapter's tables: runs fn(adapter) when
+    // the adapter is enabled and its tables are in place, and otherwise
+    // returns the adapter's turned-off answer. A table removed by hand gives
+    // the same answer rather than an error.
+    async whenEnabled(id, fn) {
+      const adapter = adapters.get(id);
+      if (!adapter) throw new Error(`No adapter ${id}`);
+      const now = state(adapter);
+      if (now === 'disabled') return turnedOff(adapter, 'disabled');
+      if (now !== 'ready') return turnedOff(adapter, 'restart_needed');
+      try {
+        return await fn(adapter);
+      } catch (error) {
+        if (adapter.schema && isMissingTable(error)) {
+          log.error?.(`[integrations] ${id}: ${error.message}`);
+          return turnedOff(adapter, 'tables_missing');
+        }
+        throw error;
+      }
     },
   };
 }

package/server/integrations/remove-tables.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+// Removes a turned-off integration's tables: the separate, explicit step that
+// turning an integration off never takes. It refuses while the integration is
+// in FLOW_INTEGRATIONS and while any of its tables holds a row.
+//
+//   DATABASE_URL=postgres://… node server/integrations/remove-tables.js <id>
+import { openDatabase } from '../db/index.js';
+import { adapters } from './adapters.js';
+import { resolveEnabledIntegrations } from './index.js';
+import { defineAdapter } from './port.js';
+import { removeAdapterTables } from './schema.js';
+
+const id = process.argv[2];
+const found = adapters.find((a) => a.id === id);
+if (!found) {
+  console.error(`Usage: remove-tables.js <id>. Known: ${adapters.map((a) => a.id).join(', ') || 'none'}.`);
+  process.exit(2);
+}
+
+const database = openDatabase({ max: 1 });
+try {
+  const adapter = defineAdapter(found);
+  const enabled = resolveEnabledIntegrations().includes(id);
+  const { removed } = await removeAdapterTables(database.db, adapter, { enabled });
+  console.log(removed.length ? `Removed ${removed.join(', ')}` : `${adapter.name} had no tables`);
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = 1;
+} finally {
+  await database.close();
+}

package/server/integrations/schema.js

@@ -0,0 +1,62 @@
+import { sql } from 'drizzle-orm';
+import { migrate } from 'drizzle-orm/node-postgres/migrator';
+
+// An adapter's tables: created from its own migrations while it is enabled,
+// never dropped by turning it off. Each adapter keeps its own migration
+// journal (drizzle.__drizzle_migrations_<id>), so the core's journal and
+// every other adapter's stay independent. docs/INTEGRATIONS.md.
+
+const MISSING_TABLE = '42P01'; // PostgreSQL undefined_table
+
+export function migrationsTable(adapter) {
+  return `__drizzle_migrations_${adapter.id.replaceAll('-', '_')}`;
+}
+
+// The adapter's declared tables that do not exist.
+export async function missingAdapterTables(db, adapter) {
+  const missing = [];
+  for (const table of adapter.schema.tables) {
+    const { rows } = await db.execute(sql`select to_regclass(${`public.${table}`}) is null as missing`);
+    if (rows[0].missing) missing.push(table);
+  }
+  return missing;
+}
+
+// Runs the adapter's pending migrations, then checks they created every table
+// it declares, so the declaration stays true.
+export async function migrateAdapterSchema(db, adapter) {
+  await migrate(db, { migrationsFolder: adapter.schema.migrationsFolder, migrationsTable: migrationsTable(adapter) });
+  const missing = await missingAdapterTables(db, adapter);
+  if (missing.length) {
+    throw new Error(`Adapter ${adapter.id} migrations did not create ${missing.join(', ')}`);
+  }
+}
+
+export function isMissingTable(error) {
+  return error?.code === MISSING_TABLE || error?.cause?.code === MISSING_TABLE;
+}
+
+// The separate, explicit step that removes a turned-off adapter's tables. It
+// refuses while the adapter is enabled and while any of its tables holds a
+// row, so it never removes data. Everything goes in one transaction.
+export async function removeAdapterTables(db, adapter, { enabled }) {
+  if (!adapter.schema) return { removed: [] };
+  if (enabled) throw new Error(`Turn ${adapter.name} off before removing its tables`);
+  const missing = new Set(await missingAdapterTables(db, adapter));
+  const present = adapter.schema.tables.filter((table) => !missing.has(table));
+  return db.transaction(async (tx) => {
+    const holding = [];
+    for (const table of present) {
+      const { rows } = await tx.execute(sql`select exists (select 1 from ${sql.identifier(table)}) as holding`);
+      if (rows[0].holding) holding.push(table);
+    }
+    if (holding.length) {
+      throw new Error(`${adapter.name} tables still hold rows: ${holding.join(', ')}. Nothing was removed.`);
+    }
+    if (present.length) {
+      await tx.execute(sql`drop table ${sql.join(present.map((t) => sql.identifier(t)), sql`, `)}`);
+    }
+    await tx.execute(sql`drop table if exists ${sql.identifier('drizzle')}.${sql.identifier(migrationsTable(adapter))}`);
+    return { removed: present };
+  });
+}

package/server/integrations/seazona/client.js

@@ -0,0 +1,196 @@
+import { createHash } from 'node:crypto';
+import { createSeazonaGovernor, normaliseRequestPath } from './governor.js';
+import { createReplayFetch } from './replay.js';
+
+// The Seazona REST client. It only reads: Flow's billing needs invoices,
+// orders, clients, products and users, and none of that writes to Seazona.
+//
+// Every request goes through the rate governor (governor.js). In live and
+// sandbox mode a client without a governor refuses to start, so no code path
+// can call Seazona ungoverned. Replay mode answers from a file and never
+// reaches a network.
+
+const MAX_RETRY_AFTER_MS = 60_000;
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, Math.max(0, ms)));
+
+// A failed Seazona request. The message names the method, the path and the
+// status or failure kind; never the host, the query or a credential.
+// kind: http, timeout, network, invalid_json, replay_miss, governor_timeout.
+export class SeazonaApiError extends Error {
+  constructor(message, { statusCode = null, kind = 'http', path = null, retryAfterMs = null } = {}) {
+    super(message);
+    this.name = 'SeazonaApiError';
+    this.code = 'seazona_api_request_failed';
+    this.statusCode = statusCode;
+    this.kind = kind;
+    this.path = path;
+    this.retryAfterMs = retryAfterMs;
+  }
+}
+
+export function parseRetryAfterMs(value, nowMs = Date.now()) {
+  const text = typeof value === 'string' ? value.trim() : '';
+  if (!text) return null;
+  const seconds = Number(text);
+  if (Number.isFinite(seconds) && seconds >= 0) return Math.ceil(seconds * 1000);
+  const at = Date.parse(text);
+  return Number.isFinite(at) ? Math.max(0, at - nowMs) : null;
+}
+
+// A stable, non-secret name for one API client, so processes that share the
+// database share one rate limit without storing the client id.
+export function deriveClientKey(settings) {
+  if (settings.mode === 'replay') return 'replay';
+  return createHash('sha256')
+    .update(`${settings.credentials?.clientId || ''}@${settings.baseUrl}`)
+    .digest('hex')
+    .slice(0, 24);
+}
+
+function buildUrl(baseUrl, path, query) {
+  const url = new URL(`${baseUrl.replace(/\/+$/, '')}/${String(path || '').replace(/^\/+/, '')}`);
+  for (const [key, value] of Object.entries(query || {})) {
+    if (value !== undefined && value !== null && value !== '') url.searchParams.set(key, String(value));
+  }
+  return url;
+}
+
+function describeFailure(error) {
+  if (error?.name === 'AbortError') return 'timeout';
+  if (error?.kind === 'replay_miss') return 'replay_miss';
+  return 'network';
+}
+
+export function createSeazonaClient({
+  settings,
+  db = null,
+  governor = null,
+  fetchImpl = null,
+  workflow = 'seazona',
+  now = Date.now,
+  sleepFn = sleep,
+  random = Math.random,
+} = {}) {
+  if (!settings?.mode) throw new TypeError('The Seazona client needs a mode (SEAZONA_MODE)');
+  const { mode, baseUrl, credentials, rate } = settings;
+
+  let transport = fetchImpl;
+  if (mode === 'replay') {
+    // Replay never falls back to a real fetch.
+    transport ??= createReplayFetch(settings.replayFile);
+  } else {
+    transport ??= globalThis.fetch;
+    if (!credentials) throw new TypeError(`The Seazona client needs credentials in ${mode} mode`);
+  }
+  if (typeof transport !== 'function') throw new TypeError('A fetch implementation is required');
+
+  let gate = governor;
+  if (!gate && db) {
+    gate = createSeazonaGovernor({
+      db,
+      clientKey: deriveClientKey(settings),
+      requestsPerMinute: rate.requestsPerMinute,
+      maxWaitMs: rate.maxWaitMs,
+      telemetryRetentionMs: rate.telemetryRetentionMs,
+      now,
+      sleepFn,
+    });
+  }
+  if (!gate && mode !== 'replay') {
+    throw new TypeError(`The Seazona client needs the rate governor in ${mode} mode`);
+  }
+
+  const authorization = credentials
+    ? `Basic ${Buffer.from(`${credentials.clientId}:${credentials.clientSecret}`).toString('base64')}`
+    : null;
+  const stats = { requests: 0, retries: 0, rateLimited: 0 };
+
+  // One request at a time from this process; the governor spaces them out
+  // across processes.
+  let tail = Promise.resolve();
+  function serialise(work) {
+    const run = tail.catch(() => {}).then(work);
+    tail = run.catch(() => {});
+    return run;
+  }
+
+  async function attempt(url, isRetry) {
+    const path = normaliseRequestPath(url.pathname);
+    const admission = gate ? await gate.reserve({ workflow, isRetry }) : null;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), rate.timeoutMs);
+    const startedAt = Number(now());
+    stats.requests += 1;
+    try {
+      const headers = { Accept: 'application/json' };
+      if (authorization) headers.Authorization = authorization;
+      const response = await transport(url, { method: 'GET', headers, signal: controller.signal });
+      const body = await response.text();
+      const retryAfterMs = parseRetryAfterMs(response.headers?.get?.('retry-after'), Number(now()));
+      if (admission) {
+        await gate.recordResponse({
+          requestId: admission.requestId,
+          path,
+          statusCode: response.status,
+          durationMs: Number(now()) - startedAt,
+          retryAfterMs: response.status === 429 && retryAfterMs !== null ? Math.min(retryAfterMs, MAX_RETRY_AFTER_MS) : null,
+        });
+      }
+      return { status: response.status, ok: response.ok, body, retryAfterMs };
+    } catch (error) {
+      const kind = describeFailure(error);
+      if (admission) {
+        await gate.recordResponse({ requestId: admission.requestId, path, failureKind: kind, durationMs: Number(now()) - startedAt });
+      }
+      return { failure: kind, path };
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  // GET a resource path relative to the API root. Returns the parsed JSON, or
+  // null for an empty body; the caller decides whether empty is a failure.
+  async function get(path, query = {}) {
+    const url = buildUrl(baseUrl, path, query);
+    const label = `GET ${url.pathname}`;
+    for (let tryNumber = 0; ; tryNumber += 1) {
+      const result = await serialise(() => attempt(url, tryNumber > 0));
+      if (result.failure) {
+        throw new SeazonaApiError(`Seazona ${label} failed (${result.failure})`, { kind: result.failure, path: url.pathname });
+      }
+      const retryable = result.status === 429 || result.status >= 500;
+      if (retryable && tryNumber < rate.maxRetries) {
+        if (result.status === 429) stats.rateLimited += 1;
+        stats.retries += 1;
+        const backoffMs = Math.min(MAX_RETRY_AFTER_MS, 1_000 * (2 ** tryNumber));
+        const delayMs = Math.min(MAX_RETRY_AFTER_MS, Math.max(result.retryAfterMs ?? 0, backoffMs) + Math.floor(random() * 250));
+        await sleepFn(delayMs);
+        continue;
+      }
+      if (!result.ok) {
+        throw new SeazonaApiError(`Seazona ${label} failed with HTTP ${result.status}`, {
+          statusCode: result.status,
+          kind: 'http',
+          path: url.pathname,
+          retryAfterMs: result.retryAfterMs === null ? null : Math.min(result.retryAfterMs, MAX_RETRY_AFTER_MS),
+        });
+      }
+      if (!result.body.trim()) return null;
+      try {
+        return JSON.parse(result.body);
+      } catch {
+        throw new SeazonaApiError(`Seazona ${label} returned invalid JSON`, { kind: 'invalid_json', path: url.pathname });
+      }
+    }
+  }
+
+  return {
+    mode,
+    stats,
+    governor: gate,
+    get,
+    // A request count per run, for lane results.
+    requestCount: () => stats.requests,
+  };
+}

package/server/integrations/seazona/drizzle.config.js

@@ -0,0 +1,9 @@
+import { defineConfig } from 'drizzle-kit';
+
+// The Seazona adapter's own migrations (docs/SEAZONA.md, "Tables"). Generate
+// with: npx drizzle-kit generate --config server/integrations/seazona/drizzle.config.js
+export default defineConfig({
+  dialect: 'postgresql',
+  schema: './server/integrations/seazona/schema.js',
+  out: './server/integrations/seazona/migrations',
+});

package/server/integrations/seazona/feed.js

@@ -0,0 +1,104 @@
+import { eq, sql } from 'drizzle-orm';
+import { ledgerLinesFor, toLedgerHold, toLedgerJob } from './ledger.js';
+import { orderStatusLabel, parseSeazonaDate } from './map.js';
+import { seazonaClients, seazonaInvoices, seazonaOrders } from './schema.js';
+
+// The billing feed behind the port's pullWorkItems: every order that changed
+// since a cursor, oldest change first. A complete or shipped order is an
+// item, with the Seazona invoice that carries it and its client. Any other
+// changed order comes back in `withdrawn`, so invoice preparation can drop
+// work it holds: an order deleted in Seazona is never an item (issue #12).
+//
+// The cursor is opaque; pass back `cursor` from the last page. A change to
+// the order or to its invoice moves the order to the end of the feed.
+
+const BILLABLE = /\b(complete|completed|shipped|delivered)\b/i;
+const SHIPPED = /\b(shipped|delivered)\b/i;
+
+function decodeCursor(cursor) {
+  if (!cursor) return null;
+  try {
+    const { at, id } = JSON.parse(Buffer.from(String(cursor), 'base64url').toString('utf8'));
+    if (typeof id === 'string' && typeof at === 'string' && at) return { at, id };
+  } catch { /* fall through */ }
+  throw new TypeError('Not a Seazona feed cursor');
+}
+
+// `at` is PostgreSQL's own text for the time, so no precision is lost.
+function encodeCursor(at, id) {
+  return Buffer.from(JSON.stringify({ at, id })).toString('base64url');
+}
+
+export async function readBillableWork(db, { cursor = null, limit = 200 } = {}) {
+  const after = decodeCursor(cursor);
+  const changedAt = sql`greatest(${seazonaOrders.lastChangedAt}, coalesce(${seazonaInvoices.lastChangedAt}, ${seazonaOrders.lastChangedAt}))`;
+  const pageSize = Math.max(1, Math.min(1000, limit));
+  const rows = await db.select({
+    order: seazonaOrders,
+    invoice: seazonaInvoices,
+    client: { accountNumber: seazonaClients.accountNumber, company: seazonaClients.company, email: seazonaClients.email },
+    // How many orders carry the same Seazona invoice (ledger.js, ledgerLinesFor).
+    invoiceOrderCount: sql`(select count(*)::int from ${seazonaOrders} as same where same.invoice_number = ${seazonaOrders.invoiceNumber} and same.deleted_in_source_at is null)`,
+    changedAt: sql`to_char(${changedAt} at time zone 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.US"Z"')`,
+  })
+    .from(seazonaOrders)
+    .leftJoin(seazonaInvoices, eq(seazonaInvoices.invoiceNumber, seazonaOrders.invoiceNumber))
+    .leftJoin(seazonaClients, eq(seazonaClients.id, seazonaOrders.clientId))
+    .where(after ? sql`(${changedAt}, ${seazonaOrders.id}) > (${after.at}::timestamptz, ${after.id})` : undefined)
+    .orderBy(changedAt, seazonaOrders.id)
+    .limit(pageSize);
+
+  const items = [];
+  const withdrawn = [];
+  for (const { order, invoice, client, invoiceOrderCount } of rows) {
+    const billable = !order.deletedInSourceAt && BILLABLE.test(order.status ?? '');
+    if (!billable) {
+      const entry = {
+        sourceId: order.id,
+        status: orderStatusLabel(order),
+        reason: order.deletedInSourceAt ? 'deleted_in_seazona' : 'not_billable',
+      };
+      withdrawn.push({ ...entry, ledgerHold: toLedgerHold(entry) });
+      continue;
+    }
+    const item = {
+      source: 'seazona',
+      sourceId: order.id,
+      invoiceNumber: order.invoiceNumber,
+      status: order.status,
+      shipped: SHIPPED.test(order.status ?? ''),
+      clientId: order.clientId,
+      company: order.company,
+      doctorName: order.doctorName,
+      orderedOn: parseSeazonaDate(order.orderedText),
+      dueOn: parseSeazonaDate(order.dueText),
+      lines: order.lines,
+      subtotalCents: order.subtotalCents,
+      patientReference: order.patientReference,
+      syncedAt: order.lastSyncedAt.toISOString(),
+      invoice: invoice ? {
+        invoiceNumber: invoice.invoiceNumber,
+        status: invoice.status,
+        accountNumber: invoice.accountNumber,
+        invoiceDate: parseSeazonaDate(invoice.invoiceDateText),
+        dueDate: parseSeazonaDate(invoice.dueText),
+        lines: invoice.lines,
+        subtotalCents: invoice.subtotalCents,
+        taxCents: invoice.taxCents,
+        totalCents: invoice.totalCents,
+        discountCents: invoice.discountCents,
+        patientReference: invoice.patientReference,
+      } : null,
+      client: client?.accountNumber || client?.company || client?.email ? client : null,
+      invoiceOrderCount: order.invoiceNumber ? Number(invoiceOrderCount) : 0,
+    };
+    items.push({ ...item, linesFrom: ledgerLinesFor(item).linesFrom, ledgerJob: toLedgerJob(item) });
+  }
+  const lastRow = rows.at(-1);
+  return {
+    items,
+    withdrawn,
+    cursor: lastRow ? encodeCursor(lastRow.changedAt, lastRow.order.id) : cursor,
+    more: rows.length === pageSize,
+  };
+}