@arcforgelabs/flow 2026.10.18 → 2026.10.19

package/server/integrations/seazona/store.js

@@ -0,0 +1,219 @@
+import { and, eq, getTableColumns, gt, inArray, isNotNull, isNull, lt, ne, or, sql } from 'drizzle-orm';
+import { hashOf } from './map.js';
+import {
+  seazonaClients,
+  seazonaInvoices,
+  seazonaLaneState,
+  seazonaOrderReadFailures,
+  seazonaOrders,
+  seazonaReference,
+} from './schema.js';
+
+// Reads and writes of the Seazona mirror. Every write takes `at`, the lane's
+// clock, so one run uses one time throughout.
+
+export const MIRRORS = Object.freeze({
+  orders: { table: seazonaOrders, key: 'id' },
+  invoices: { table: seazonaInvoices, key: 'invoiceNumber' },
+  clients: { table: seazonaClients, key: 'id' },
+});
+
+function excludedSet(table, fields) {
+  const columns = getTableColumns(table);
+  return Object.fromEntries(fields.map((field) => [field, sql.raw(`excluded."${columns[field].name}"`)]));
+}
+
+// Stored list signatures and deleted marks for a set of keys.
+export async function readKnown(db, mirror, keys) {
+  const { table, key } = MIRRORS[mirror];
+  if (!keys.length) return new Map();
+  const columns = { key: table[key], listSignature: table.listSignature, recordHash: table.recordHash };
+  if (mirror === 'orders') columns.deletedInSourceAt = table.deletedInSourceAt;
+  const rows = await db.select(columns).from(table).where(inArray(table[key], keys));
+  return new Map(rows.map((row) => [row.key, row]));
+}
+
+// Upserts mapped records. `last_changed_at` moves only when the record
+// differs from what was stored. Returns { created, changed, unchanged }.
+export async function upsertRecords(db, mirror, records, { at, listSignatures = new Map() } = {}) {
+  const { table, key } = MIRRORS[mirror];
+  const summary = { created: 0, changed: 0, unchanged: 0 };
+  if (!records.length) return summary;
+  const known = await readKnown(db, mirror, records.map((record) => record[key]));
+  const values = records.map((record) => {
+    const row = { ...record };
+    if (mirror === 'orders') row.deletedInSourceAt = null; // a successful read clears the 404 mark
+    const recordHash = hashOf(row);
+    const before = known.get(record[key]);
+    if (!before) summary.created += 1;
+    else if (before.recordHash !== recordHash || before.deletedInSourceAt) summary.changed += 1;
+    else summary.unchanged += 1;
+    return {
+      ...row,
+      listSignature: listSignatures.get(record[key]) ?? null,
+      recordHash,
+      firstSeenAt: at,
+      lastSyncedAt: at,
+      lastChangedAt: at,
+    };
+  });
+  // A detail-only read (no list row) keeps the stored list signature.
+  const keep = new Set([key, 'firstSeenAt', 'lastChangedAt', ...(listSignatures.size ? [] : ['listSignature'])]);
+  const updatable = Object.keys(values[0]).filter((field) => !keep.has(field));
+  await db.insert(table).values(values).onConflictDoUpdate({
+    target: table[key],
+    set: {
+      ...excludedSet(table, updatable),
+      // An order that comes back after a 404 counts as changed.
+      lastChangedAt: mirror === 'orders'
+        ? sql`case when ${table.recordHash} = excluded.record_hash and ${seazonaOrders.deletedInSourceAt} is null then ${table.lastChangedAt} else excluded.last_changed_at end`
+        : sql`case when ${table.recordHash} = excluded.record_hash then ${table.lastChangedAt} else excluded.last_changed_at end`,
+    },
+  });
+  return summary;
+}
+
+// A list row that did not change since the last read: only its sync time moves.
+export async function touchSynced(db, mirror, keys, { at }) {
+  const { table, key } = MIRRORS[mirror];
+  if (!keys.length) return;
+  await db.update(table).set({ lastSyncedAt: at }).where(inArray(table[key], keys));
+}
+
+// Issue #12: Seazona answered 404. Keep the row and its history, mark it, and
+// refresh its sync time so it never comes first in the rotation again. An
+// order seen in a list but never stored is kept from that list row.
+export async function markOrderDeleted(db, id, { at, fallback = null }) {
+  const [row] = await db.update(seazonaOrders)
+    .set({
+      deletedInSourceAt: sql`coalesce(${seazonaOrders.deletedInSourceAt}, ${at})`,
+      lastChangedAt: sql`case when ${seazonaOrders.deletedInSourceAt} is null then ${at} else ${seazonaOrders.lastChangedAt} end`,
+      lastSyncedAt: at,
+    })
+    .where(eq(seazonaOrders.id, id))
+    .returning({ id: seazonaOrders.id });
+  if (row || !fallback) return;
+  await db.insert(seazonaOrders).values({
+    ...fallback,
+    recordHash: hashOf(fallback),
+    deletedInSourceAt: at,
+    firstSeenAt: at,
+    lastSyncedAt: at,
+    lastChangedAt: at,
+  }).onConflictDoNothing();
+}
+
+export async function upsertReference(db, resource, records, { at }) {
+  if (!records.length) return { stored: 0 };
+  const values = records.map((record) => ({ ...record, resource, recordHash: hashOf(record), lastSyncedAt: at }));
+  await db.insert(seazonaReference).values(values).onConflictDoUpdate({
+    target: [seazonaReference.resource, seazonaReference.id],
+    set: excludedSet(seazonaReference, ['name', 'code', 'kind', 'priceCents', 'taxable', 'recordHash', 'lastSyncedAt']),
+  });
+  return { stored: values.length };
+}
+
+// Open orders for the active-order lane: not final, not deleted in Seazona,
+// not quarantined, oldest observation first. A failed read never refreshes
+// last_synced_at, so the rotation uses whichever is later, the last success
+// or the last failed attempt: a failed order goes to the back. Complete
+// orders win only an equal-age tie.
+export async function selectActiveOrders(db, { at, limit, finalStatusPattern }) {
+  const rotationAt = sql`greatest(${seazonaOrders.lastSyncedAt}, coalesce(${seazonaOrderReadFailures.lastAttemptAt}, ${seazonaOrders.lastSyncedAt}))`;
+  const open = and(
+    isNull(seazonaOrders.deletedInSourceAt),
+    or(isNull(seazonaOrders.status), sql`${seazonaOrders.status} !~* ${finalStatusPattern}`),
+  );
+  const notQuarantined = or(isNull(seazonaOrderReadFailures.quarantinedUntil), lt(seazonaOrderReadFailures.quarantinedUntil, at));
+  const targets = await db.select({
+    id: seazonaOrders.id,
+    failureCount: seazonaOrderReadFailures.failureCount,
+  })
+    .from(seazonaOrders)
+    .leftJoin(seazonaOrderReadFailures, eq(seazonaOrderReadFailures.orderId, seazonaOrders.id))
+    .where(and(open, notQuarantined))
+    .orderBy(rotationAt, sql`(${seazonaOrders.status} ~* '\\mcomplete') desc nulls last`, seazonaOrders.id)
+    .limit(limit);
+  const [{ candidates }] = await db.select({ candidates: sql`count(*)::int` })
+    .from(seazonaOrders)
+    .where(open);
+  return { targets, candidates };
+}
+
+export async function readOrderFailures(db, ids) {
+  if (!ids.length) return new Map();
+  const rows = await db.select().from(seazonaOrderReadFailures).where(inArray(seazonaOrderReadFailures.orderId, ids));
+  return new Map(rows.map((row) => [row.orderId, row]));
+}
+
+export async function clearOrderFailure(db, id) {
+  await db.delete(seazonaOrderReadFailures).where(eq(seazonaOrderReadFailures.orderId, id));
+}
+
+// Records one failed read. After `quarantineFailures` failures in a row the
+// order waits `quarantineMs`; when that ends it gets one more read, and a
+// failure then quarantines it again.
+export async function recordOrderFailure(db, id, failure, { at, quarantineFailures, quarantineMs }) {
+  const [row] = await db.insert(seazonaOrderReadFailures).values({
+    orderId: id,
+    failureCount: 1,
+    lastAttemptAt: at,
+    lastHttpStatus: failure.httpStatus,
+    lastFailureKind: failure.kind,
+    lastError: failure.error.slice(0, 300),
+    quarantinedUntil: quarantineFailures <= 1 ? new Date(at.getTime() + quarantineMs) : null,
+  }).onConflictDoUpdate({
+    target: seazonaOrderReadFailures.orderId,
+    set: {
+      failureCount: sql`${seazonaOrderReadFailures.failureCount} + 1`,
+      lastAttemptAt: at,
+      lastHttpStatus: failure.httpStatus,
+      lastFailureKind: failure.kind,
+      lastError: failure.error.slice(0, 300),
+      quarantinedUntil: sql`case when ${seazonaOrderReadFailures.failureCount} + 1 >= ${quarantineFailures}
+        then ${new Date(at.getTime() + quarantineMs)}::timestamptz else null end`,
+    },
+  }).returning();
+  return { failureCount: row.failureCount, quarantinedUntil: row.quarantinedUntil?.toISOString() ?? null };
+}
+
+export async function readQuarantinedOrders(db, { at, limit = 25 }) {
+  const rows = await db.select().from(seazonaOrderReadFailures)
+    .where(and(isNotNull(seazonaOrderReadFailures.quarantinedUntil), gt(seazonaOrderReadFailures.quarantinedUntil, at)))
+    .orderBy(seazonaOrderReadFailures.orderId)
+    .limit(limit);
+  return rows.map((row) => ({
+    id: row.orderId,
+    httpStatus: row.lastHttpStatus,
+    kind: row.lastFailureKind,
+    failureCount: row.failureCount,
+    lastAttemptAt: row.lastAttemptAt.toISOString(),
+    quarantinedUntil: row.quarantinedUntil.toISOString(),
+  }));
+}
+
+// Lane state.
+
+export async function readLaneStates(db) {
+  const rows = await db.select().from(seazonaLaneState);
+  return new Map(rows.map((row) => [row.lane, row]));
+}
+
+// Claims a lane for this run. Returns false when another run holds it and has
+// not been running longer than `stuckMs`, so two processes never run one lane
+// at once.
+export async function claimLane(db, lane, { at, stuckMs }) {
+  await db.insert(seazonaLaneState).values({ lane }).onConflictDoNothing();
+  const claimed = await db.update(seazonaLaneState)
+    .set({ status: 'processing', lastAttemptAt: at, updatedAt: at })
+    .where(and(
+      eq(seazonaLaneState.lane, lane),
+      or(ne(seazonaLaneState.status, 'processing'), lt(seazonaLaneState.lastAttemptAt, new Date(at.getTime() - stuckMs))),
+    ))
+    .returning({ lane: seazonaLaneState.lane });
+  return claimed.length > 0;
+}
+
+export async function finishLane(db, lane, patch) {
+  await db.update(seazonaLaneState).set({ ...patch, updatedAt: patch.lastAttemptAt ?? new Date() }).where(eq(seazonaLaneState.lane, lane));
+}

package/server/integrations/seazona/sync-once.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+// Runs the Seazona sync lanes once, now, and prints what each did. This is
+// how a sandbox or replay installation syncs, since only live mode runs on a
+// timer. Every request still goes through the rate governor.
+//
+//   DATABASE_URL=postgres://… FLOW_INTEGRATIONS=seazona SEAZONA_MODE=sandbox … \
+//     node server/integrations/seazona/sync-once.js [lane …]
+//
+// Lanes: invoices, orders_recent, orders_active, clients, products, users.
+// None named: all of them.
+import { openDatabase } from '../../db/index.js';
+import { resolveEnabledIntegrations } from '../index.js';
+import { migrateAdapterSchema } from '../schema.js';
+import { createSeazonaClient } from './client.js';
+import { requireSeazonaSettings } from './index.js';
+import { LANES, runSeazonaSync } from './lanes.js';
+import { seazonaSchema } from './tables.js';
+
+const lanes = process.argv.slice(2);
+const unknown = lanes.filter((lane) => !LANES.includes(lane));
+if (unknown.length) {
+  console.error(`Unknown lane ${unknown.join(', ')}. Lanes: ${LANES.join(', ')}.`);
+  process.exit(2);
+}
+
+let database;
+try {
+  // The adapter's tables exist only while it is on (docs/INTEGRATIONS.md).
+  if (!resolveEnabledIntegrations().includes('seazona')) {
+    throw new Error('Seazona is turned off: add seazona to FLOW_INTEGRATIONS first');
+  }
+  const settings = requireSeazonaSettings();
+  database = openDatabase({ max: 2 });
+  await migrateAdapterSchema(database.db, { id: 'seazona', schema: seazonaSchema });
+  const client = createSeazonaClient({ settings, db: database.db, workflow: 'seazona-sync-once' });
+  const result = await runSeazonaSync(database.db, client, { settings, only: lanes, force: true });
+  console.log(JSON.stringify({ mode: settings.mode, requests: client.stats.requests, ...result }, null, 2));
+  process.exitCode = result.ok ? 0 : 1;
+} catch (error) {
+  console.error(`[seazona] ${error.message}`);
+  process.exitCode = 1;
+} finally {
+  await database?.close();
+}

package/server/integrations/seazona/tables.js

@@ -0,0 +1,17 @@
+import { fileURLToPath } from 'node:url';
+
+// The adapter's schema declaration for the integration port: its own
+// migrations, and every table they create (docs/INTEGRATIONS.md).
+export const seazonaSchema = Object.freeze({
+  migrationsFolder: fileURLToPath(new URL('./migrations', import.meta.url)),
+  tables: Object.freeze([
+    'seazona_api_governor',
+    'seazona_api_requests',
+    'seazona_orders',
+    'seazona_invoices',
+    'seazona_clients',
+    'seazona_reference',
+    'seazona_lane_state',
+    'seazona_order_read_failures',
+  ]),
+});

package/server/integrations/xero/catalogue.js

@@ -0,0 +1,184 @@
+import { sql } from 'drizzle-orm';
+import { withXeroLane } from './governor.js';
+
+// Flow's copy of a connected organisation's Xero contacts and items. Xero
+// owns them: Flow never creates or changes a Xero contact or item. A sync
+// reads them all (a few calls: contacts 100 a page, items in one) and
+// replaces the copy in one transaction, so invoice preview can match
+// contacts and item codes without spending Xero calls.
+
+// Xero dates come as "/Date(1792000000000+0000)/" or ISO text.
+export function parseXeroDate(value) {
+  if (!value) return null;
+  const legacy = /^\/Date\((-?\d+)/.exec(String(value));
+  const at = legacy ? Number(legacy[1]) : Date.parse(value);
+  return Number.isFinite(at) ? new Date(at) : null;
+}
+
+// Names compare case-insensitively with spaces collapsed, as Xero's own
+// contact name check does.
+export function normaliseName(value) {
+  return String(value ?? '').trim().replace(/\s+/g, ' ').toLowerCase();
+}
+
+const toCents = (amount) => (typeof amount === 'number' && Number.isFinite(amount) ? Math.round(amount * 100) : null);
+
+export function mapContact(contact) {
+  return {
+    xeroContactId: contact.ContactID,
+    name: String(contact.Name ?? '').trim(),
+    email: contact.EmailAddress || null,
+    status: contact.ContactStatus || 'ACTIVE',
+    isCustomer: Boolean(contact.IsCustomer),
+    isSupplier: Boolean(contact.IsSupplier),
+    salesTracking: (contact.SalesTrackingCategories ?? []).map((t) => ({ category: t.TrackingCategoryName, option: t.TrackingOptionName })),
+    xeroUpdatedAt: parseXeroDate(contact.UpdatedDateUTC),
+  };
+}
+
+export function mapItem(item) {
+  return {
+    xeroItemId: item.ItemID,
+    code: String(item.Code ?? '').trim(),
+    name: item.Name || null,
+    description: item.Description || null,
+    isSold: item.IsSold !== false,
+    salesUnitAmountCents: toCents(item.SalesDetails?.UnitPrice),
+    salesAccountCode: item.SalesDetails?.AccountCode || null,
+    salesTaxType: item.SalesDetails?.TaxType || null,
+    xeroUpdatedAt: parseXeroDate(item.UpdatedDateUTC),
+  };
+}
+
+async function replaceContacts(tx, organisationId, contacts) {
+  const ids = contacts.map((c) => c.xeroContactId);
+  await tx.execute(sql`delete from xero_contacts where organisation_id = ${organisationId}
+    and not (xero_contact_id = any(${sql.param(ids)}::text[]))`);
+  for (const c of contacts) {
+    await tx.execute(sql`
+      insert into xero_contacts (organisation_id, xero_contact_id, name, email, status, is_customer, is_supplier, sales_tracking, xero_updated_at, synced_at)
+      values (${organisationId}, ${c.xeroContactId}, ${c.name}, ${c.email}, ${c.status}, ${c.isCustomer}, ${c.isSupplier}, ${JSON.stringify(c.salesTracking)}::jsonb, ${c.xeroUpdatedAt}, now())
+      on conflict (organisation_id, xero_contact_id) do update set
+        name = excluded.name, email = excluded.email, status = excluded.status, is_customer = excluded.is_customer,
+        is_supplier = excluded.is_supplier, sales_tracking = excluded.sales_tracking,
+        xero_updated_at = excluded.xero_updated_at, synced_at = now()`);
+  }
+}
+
+async function replaceItems(tx, organisationId, items) {
+  const ids = items.map((i) => i.xeroItemId);
+  await tx.execute(sql`delete from xero_items where organisation_id = ${organisationId}
+    and not (xero_item_id = any(${sql.param(ids)}::text[]))`);
+  for (const i of items) {
+    await tx.execute(sql`
+      insert into xero_items (organisation_id, xero_item_id, code, name, description, is_sold, sales_unit_amount_cents, sales_account_code, sales_tax_type, xero_updated_at, synced_at)
+      values (${organisationId}, ${i.xeroItemId}, ${i.code}, ${i.name}, ${i.description}, ${i.isSold}, ${i.salesUnitAmountCents}, ${i.salesAccountCode}, ${i.salesTaxType}, ${i.xeroUpdatedAt}, now())
+      on conflict (organisation_id, xero_item_id) do update set
+        code = excluded.code, name = excluded.name, description = excluded.description, is_sold = excluded.is_sold,
+        sales_unit_amount_cents = excluded.sales_unit_amount_cents, sales_account_code = excluded.sales_account_code,
+        sales_tax_type = excluded.sales_tax_type, xero_updated_at = excluded.xero_updated_at, synced_at = now()`);
+  }
+}
+
+// Reads every Xero contact and item and replaces Flow's copy. A failed read
+// leaves the copy as it was and records the failure.
+export async function syncCatalogue(db, runtime, organisationId, { startedBy = null } = {}) {
+  return runtime.serial(organisationId, () => withXeroLane('sync', async () => {
+    const { client } = await runtime.clientFor(db, organisationId);
+    const { rows: [run] } = await db.execute(sql`insert into xero_sync_runs (organisation_id, started_by) values (${organisationId}, ${startedBy}) returning id, started_at`);
+    try {
+      const contacts = (await client.listContacts()).map(mapContact).filter((c) => c.xeroContactId && c.name);
+      // An item without a code cannot go on an invoice line by code.
+      const items = (await client.listItems()).map(mapItem).filter((i) => i.xeroItemId && i.code);
+      await db.transaction(async (tx) => {
+        await replaceContacts(tx, organisationId, contacts);
+        await replaceItems(tx, organisationId, items);
+        await tx.execute(sql`update xero_sync_runs set status = 'succeeded', finished_at = now(), contact_count = ${contacts.length}, item_count = ${items.length} where id = ${run.id}`);
+      });
+      return { id: run.id, status: 'succeeded', contactCount: contacts.length, itemCount: items.length };
+    } catch (error) {
+      await db.execute(sql`update xero_sync_runs set status = 'failed', finished_at = now(), error_code = ${error.code ?? 'xero_sync_failed'}, error_message = ${String(error.message).slice(0, 500)} where id = ${run.id}`);
+      throw error;
+    }
+  }));
+}
+
+export async function lastSync(db, organisationId) {
+  const { rows } = await db.execute(sql`
+    select id, status, started_at, finished_at, contact_count, item_count, error_code, error_message
+    from xero_sync_runs where organisation_id = ${organisationId} order by started_at desc limit 1`);
+  const row = rows[0];
+  if (!row) return null;
+  return {
+    id: row.id,
+    status: row.status,
+    startedAt: row.started_at,
+    finishedAt: row.finished_at,
+    contactCount: row.contact_count,
+    itemCount: row.item_count,
+    error: row.error_code ? { code: row.error_code, message: row.error_message } : null,
+  };
+}
+
+// When contacts and items were last copied from Xero, or null.
+export async function lastSuccessfulSyncAt(db, organisationId) {
+  const { rows } = await db.execute(sql`select max(finished_at) as at from xero_sync_runs where organisation_id = ${organisationId} and status = 'succeeded'`);
+  return rows[0]?.at ?? null;
+}
+
+const contactRow = (row) => ({
+  xeroContactId: row.xero_contact_id,
+  name: row.name,
+  email: row.email,
+  status: row.status,
+  isCustomer: row.is_customer,
+  isSupplier: row.is_supplier,
+  salesTracking: row.sales_tracking,
+  xeroUpdatedAt: row.xero_updated_at,
+  syncedAt: row.synced_at,
+});
+
+const itemRow = (row) => ({
+  xeroItemId: row.xero_item_id,
+  code: row.code,
+  name: row.name,
+  description: row.description,
+  isSold: row.is_sold,
+  salesUnitAmountCents: row.sales_unit_amount_cents,
+  salesAccountCode: row.sales_account_code,
+  salesTaxType: row.sales_tax_type,
+  syncedAt: row.synced_at,
+});
+
+export async function listContacts(db, organisationId, { q = '', limit = 200 } = {}) {
+  const like = `%${String(q).trim().replace(/[\\%_]/g, (c) => `\\${c}`)}%`;
+  const { rows } = await db.execute(sql`select * from xero_contacts where organisation_id = ${organisationId}
+    and name ilike ${like} order by lower(name) limit ${Math.min(Math.max(1, Number(limit) || 200), 1000)}`);
+  return rows.map(contactRow);
+}
+
+export async function listItems(db, organisationId) {
+  const { rows } = await db.execute(sql`select * from xero_items where organisation_id = ${organisationId} order by code`);
+  return rows.map(itemRow);
+}
+
+export async function itemsByCode(db, organisationId, codes) {
+  const wanted = [...new Set(codes.filter(Boolean))];
+  if (!wanted.length) return new Map();
+  const { rows } = await db.execute(sql`select * from xero_items where organisation_id = ${organisationId}
+    and code = any(${sql.param(wanted)}::text[])`);
+  return new Map(rows.map((row) => [row.code, itemRow(row)]));
+}
+
+// The Xero contact for a Flow contact name: exactly one active contact with
+// the same name, or why not. Flow never creates a Xero contact (as before):
+// a missing or doubled name is for a person to fix in Xero, then sync.
+export async function matchContact(db, organisationId, name) {
+  const wanted = normaliseName(name);
+  const { rows } = await db.execute(sql`select * from xero_contacts where organisation_id = ${organisationId}
+    and regexp_replace(lower(trim(name)), '\\s+', ' ', 'g') = ${wanted}`);
+  const matches = rows.map(contactRow).filter((c) => c.status === 'ACTIVE' && normaliseName(c.name) === wanted);
+  if (matches.length === 1) return { state: 'matched', contact: matches[0] };
+  if (matches.length > 1) return { state: 'ambiguous', matches };
+  return { state: 'missing' };
+}