@arcforgelabs/flow 2026.10.18 → 2026.10.19

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

@@ -0,0 +1,20 @@
+{
+  "version": "7",
+  "dialect": "postgresql",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "7",
+      "when": 1792329974352,
+      "tag": "0000_api_governor",
+      "breakpoints": true
+    },
+    {
+      "idx": 1,
+      "version": "7",
+      "when": 1792330268730,
+      "tag": "0001_mirror",
+      "breakpoints": true
+    }
+  ]
+}

package/server/integrations/seazona/replay.js

@@ -0,0 +1,79 @@
+import { readFileSync } from 'node:fs';
+
+// Replay mode: Seazona answers come from a file of recorded, synthetic
+// responses, and nothing reaches a network (issue #10). Tests and development
+// use it. A replay file holds synthetic data only (CONTRIBUTING.md).
+//
+// Format (docs/SEAZONA.md, "Replay files"):
+//   { "responses": [
+//       { "path": "invoices/", "query": { "lastModified": "*" }, "status": 200, "body": [] },
+//       { "path": "orders/ORD-1", "status": 404 },
+//       { "path": "orders/ORD-2", "sequence": [{ "status": 500 }, { "status": 200, "body": {} }] }
+//   ] }
+// `path` is relative to the API root. `query` is optional; each listed key
+// must match, and "*" matches any value. The first matching entry answers. A
+// `sequence` answers in order and then repeats its last answer. A request that
+// no entry matches fails closed with the kind `replay_miss`.
+
+function normalisePath(path) {
+  return String(path || '').replace(/^\/+/, '').replace(/^v1\//i, '');
+}
+
+function queryMatches(expected, actual) {
+  if (!expected) return true;
+  return Object.entries(expected).every(([key, value]) => (
+    value === '*' ? actual.has(key) : actual.get(key) === String(value)
+  ));
+}
+
+export function loadReplay(source) {
+  const replay = typeof source === 'string' ? JSON.parse(readFileSync(source, 'utf8')) : source;
+  if (!replay || !Array.isArray(replay.responses)) {
+    throw new TypeError('A Seazona replay needs a "responses" list');
+  }
+  return replay;
+}
+
+// A fetch() that answers from the replay. `calls` lists what was asked, so a
+// test can check exactly which requests the adapter made.
+export function createReplayFetch(source) {
+  const replay = loadReplay(source);
+  const entries = replay.responses.map((entry) => ({ ...entry, path: normalisePath(entry.path), served: 0 }));
+  const calls = [];
+
+  async function replayFetch(input, init = {}) {
+    const url = new URL(String(input));
+    const method = (init.method || 'GET').toUpperCase();
+    const path = normalisePath(url.pathname.replace(/^\/v1\//i, ''));
+    calls.push({ method, path, query: Object.fromEntries(url.searchParams) });
+    const entry = entries.find((candidate) => (
+      (candidate.method || 'GET').toUpperCase() === method
+      && candidate.path === path
+      && queryMatches(candidate.query, url.searchParams)
+    ));
+    if (!entry) {
+      const error = new Error(`replay has no answer for ${method} ${path}`);
+      error.kind = 'replay_miss';
+      throw error;
+    }
+    const answers = Array.isArray(entry.sequence) ? entry.sequence : [entry];
+    const answer = answers[Math.min(entry.served, answers.length - 1)];
+    entry.served += 1;
+    if (answer.error === 'timeout') {
+      const error = new Error('The operation was aborted');
+      error.name = 'AbortError';
+      throw error;
+    }
+    const status = answer.status ?? 200;
+    let body = null;
+    if (typeof answer.rawBody === 'string') body = answer.rawBody;
+    else if (answer.body !== undefined) body = JSON.stringify(answer.body);
+    return new Response(status === 204 ? null : body, {
+      status,
+      headers: { 'content-type': 'application/json', ...(answer.headers || {}) },
+    });
+  }
+
+  replayFetch.calls = calls;
+  return replayFetch;
+}

package/server/integrations/seazona/scheduler.js

@@ -0,0 +1,78 @@
+import { LANES } from './lanes.js';
+import { readLaneStates } from './store.js';
+
+// The background sync, for live mode only (issue #10: index.js never creates
+// it in sandbox or replay). It runs the lanes that are due, then sleeps until
+// the next lane is due, between 15 seconds and 30 minutes. One run at a time.
+
+const MIN_DELAY_MS = 15_000;
+const MAX_DELAY_MS = 30 * 60_000;
+
+export function createSeazonaScheduler({
+  db,
+  run,
+  now = Date.now,
+  log = console,
+  timers = { setTimeout, clearTimeout },
+  firstDelayMs = 5_000,
+} = {}) {
+  let timer = null;
+  let running = null;
+  let stopped = false;
+  let nextRunAt = null;
+  let last = null;
+
+  async function nextDelayMs() {
+    const states = await readLaneStates(db);
+    let soonest = Infinity;
+    for (const lane of LANES) {
+      const at = states.get(lane)?.nextRunAt?.getTime();
+      soonest = Math.min(soonest, Number.isFinite(at) ? at - Number(now()) : 0);
+    }
+    return Math.min(MAX_DELAY_MS, Math.max(MIN_DELAY_MS, soonest));
+  }
+
+  function schedule(delayMs) {
+    if (stopped) return;
+    nextRunAt = new Date(Number(now()) + delayMs).toISOString();
+    timer = timers.setTimeout(tick, delayMs);
+    timer?.unref?.();
+  }
+
+  async function tick() {
+    timer = null;
+    if (stopped) return;
+    running = (async () => {
+      const startedAt = new Date(Number(now())).toISOString();
+      try {
+        const result = await run();
+        const failed = Object.entries(result.results).filter(([, lane]) => !lane.ok);
+        last = { at: startedAt, ok: result.ok, lanes: Object.keys(result.results), failed: failed.map(([lane]) => lane) };
+        for (const [lane, outcome] of failed) log.warn?.(`[seazona] ${lane}: ${outcome.error}`);
+      } catch (error) {
+        last = { at: startedAt, ok: false, error: error?.message || String(error) };
+        log.error?.(`[seazona] sync run failed: ${last.error}`);
+      }
+    })();
+    await running;
+    running = null;
+    schedule(await nextDelayMs().catch(() => MIN_DELAY_MS));
+  }
+
+  return {
+    start() {
+      stopped = false;
+      schedule(firstDelayMs);
+    },
+    async stop() {
+      stopped = true;
+      if (timer) timers.clearTimeout(timer);
+      timer = null;
+      nextRunAt = null;
+      await running;
+    },
+    status() {
+      return { running: Boolean(running), nextRunAt, lastRun: last };
+    },
+  };
+}

package/server/integrations/seazona/schema.js

@@ -0,0 +1,157 @@
+import { sql } from 'drizzle-orm';
+import { bigint, bigserial, boolean, index, integer, jsonb, pgTable, primaryKey, text, timestamp } from 'drizzle-orm/pg-core';
+
+// The Seazona adapter's own tables. They are not part of the core schema
+// (server/db/schema.js): the adapter creates them only when it is enabled
+// (issue #13). One installation talks to one Seazona account, so these tables
+// are installation-wide, like `people`.
+
+const at = (name) => timestamp(name, { withTimezone: true });
+
+// One row per API client: when the next request may go, and any cooldown a
+// 429 asked for. Every process that shares the database shares this row.
+export const seazonaApiGovernor = pgTable('seazona_api_governor', {
+  clientKey: text('client_key').primaryKey(),
+  nextEligibleAt: at('next_eligible_at').notNull().default(sql`'epoch'`),
+  cooldownUntil: at('cooldown_until').notNull().default(sql`'epoch'`),
+  updatedAt: at('updated_at').notNull().defaultNow(),
+});
+
+// One row per request sent. The rate limit counts these rows, and they are
+// the telemetry an operator reads to answer the vendor. A row keeps the
+// request path (for example /v1/orders/<order id>, so a failing record can be
+// named), never the host, the query or a credential, and never a response.
+export const seazonaApiRequests = pgTable('seazona_api_requests', {
+  id: bigserial('id', { mode: 'number' }).primaryKey(),
+  clientKey: text('client_key').notNull(),
+  workflow: text('workflow').notNull(),
+  admittedAt: at('admitted_at').notNull(),
+  requestPath: text('request_path'),
+  statusCode: integer('status_code'),
+  failureKind: text('failure_kind'),
+  durationMs: integer('duration_ms'),
+  isRetry: boolean('is_retry').notNull().default(false),
+}, (t) => [
+  index('seazona_api_requests_window').on(t.clientKey, t.admittedAt),
+]);
+
+// The mirror. Each row is what Seazona said at the last successful read,
+// reduced to what billing needs: no clinical notes, no files, and no patient
+// field unless SEAZONA_KEEP_PATIENT_REFERENCE is on. Money is integer cents,
+// as Seazona reported it. `list_signature` is a hash of the list fields, so an
+// unchanged list row costs no detail read; `record_hash` tells a change apart.
+const cents = (name) => bigint(name, { mode: 'number' });
+const mirrored = () => ({
+  listSignature: text('list_signature'),
+  recordHash: text('record_hash').notNull(),
+  firstSeenAt: at('first_seen_at').notNull(),
+  lastSyncedAt: at('last_synced_at').notNull(),
+  lastChangedAt: at('last_changed_at').notNull(),
+});
+
+export const seazonaOrders = pgTable('seazona_orders', {
+  id: text('id').primaryKey(),
+  invoiceNumber: text('invoice_number'),
+  clientId: text('client_id'),
+  company: text('company'),
+  doctorName: text('doctor_name'),
+  status: text('status'),
+  orderedText: text('ordered_text'),
+  dueText: text('due_text'),
+  lastModifiedText: text('last_modified_text'),
+  department: text('department'),
+  lines: jsonb('lines').notNull().default([]),
+  subtotalCents: cents('subtotal_cents'),
+  patientReference: text('patient_reference'),
+  // Issue #12: Seazona answered 404. The row and its history stay; the order
+  // reads as "Deleted in Seazona" and is out of billing. A later successful
+  // read clears it.
+  deletedInSourceAt: at('deleted_in_source_at'),
+  ...mirrored(),
+}, (t) => [
+  index('seazona_orders_invoice_number').on(t.invoiceNumber),
+  index('seazona_orders_changed').on(t.lastChangedAt),
+]);
+
+export const seazonaInvoices = pgTable('seazona_invoices', {
+  invoiceNumber: text('invoice_number').primaryKey(),
+  seazonaId: text('seazona_id'),
+  clientId: text('client_id'),
+  accountNumber: text('account_number'),
+  company: text('company'),
+  doctorName: text('doctor_name'),
+  status: text('status'),
+  invoiceDateText: text('invoice_date_text'),
+  dueText: text('due_text'),
+  lastModifiedText: text('last_modified_text'),
+  lines: jsonb('lines').notNull().default([]),
+  subtotalCents: cents('subtotal_cents'),
+  taxCents: cents('tax_cents'),
+  totalCents: cents('total_cents'),
+  discountCents: cents('discount_cents'),
+  patientReference: text('patient_reference'),
+  ...mirrored(),
+}, (t) => [
+  index('seazona_invoices_changed').on(t.lastChangedAt),
+]);
+
+export const seazonaClients = pgTable('seazona_clients', {
+  id: text('id').primaryKey(),
+  accountNumber: text('account_number'),
+  company: text('company'),
+  fullName: text('full_name'),
+  email: text('email'),
+  phone: text('phone'),
+  address: jsonb('address'),
+  taxRate: text('tax_rate'),
+  active: boolean('active'),
+  doctors: jsonb('doctors').notNull().default([]),
+  lastModifiedText: text('last_modified_text'),
+  ...mirrored(),
+});
+
+// Products and users: long-lived reference lists, read in full once a day.
+export const seazonaReference = pgTable('seazona_reference', {
+  resource: text('resource').notNull(),
+  id: text('id').notNull(),
+  name: text('name'),
+  code: text('code'),
+  kind: text('kind'),
+  priceCents: cents('price_cents'),
+  taxable: boolean('taxable'),
+  recordHash: text('record_hash').notNull(),
+  lastSyncedAt: at('last_synced_at').notNull(),
+}, (t) => [
+  primaryKey({ columns: [t.resource, t.id] }),
+]);
+
+// One row per sync lane: its cursor, when it runs next, and its last failure.
+export const seazonaLaneState = pgTable('seazona_lane_state', {
+  lane: text('lane').primaryKey(),
+  status: text('status').notNull().default('idle'),
+  cursorTime: at('cursor_time'),
+  cursor: jsonb('cursor').notNull().default({}),
+  lastSuccessAt: at('last_success_at'),
+  lastAttemptAt: at('last_attempt_at'),
+  nextRunAt: at('next_run_at'),
+  failureCount: integer('failure_count').notNull().default(0),
+  lastError: text('last_error'),
+  // The order ids and statuses behind the last failure (issue #12). Never
+  // patient data.
+  failureDetails: jsonb('failure_details'),
+  heldReason: text('held_reason'),
+  updatedAt: at('updated_at').notNull().defaultNow(),
+});
+
+// Issue #12: each failed order read, per order. A failed order moves to the
+// back of the rotation; after a few failures in a row it is quarantined for a
+// bounded time, then gets one more read. A successful read or a 404 clears it.
+export const seazonaOrderReadFailures = pgTable('seazona_order_read_failures', {
+  orderId: text('order_id').primaryKey(),
+  failureCount: integer('failure_count').notNull(),
+  lastAttemptAt: at('last_attempt_at').notNull(),
+  lastHttpStatus: integer('last_http_status'),
+  lastFailureKind: text('last_failure_kind'),
+  lastError: text('last_error'),
+  quarantinedUntil: at('quarantined_until'),
+});

package/server/integrations/seazona/settings.js

@@ -0,0 +1,161 @@
+// Seazona adapter settings. Everything that names an installation (the API
+// host, the API client) comes from configuration; the code holds no default
+// host or account. docs/SEAZONA.md lists every setting.
+//
+// The mode says which environment the adapter acts on (issue #10):
+//   live     the installation's real Seazona account; the scheduler runs.
+//   sandbox  a Seazona test account; runs only when asked, never on a timer.
+//   replay   recorded, synthetic responses from a file; no network at all.
+// There is no default mode. Without one the adapter does nothing.
+
+export const MODES = Object.freeze(['live', 'sandbox', 'replay']);
+
+// Seazona publishes 60 requests a minute per API client. Flow stays at half of
+// that, across every process that shares the database, and a setting can only
+// lower it.
+export const PUBLISHED_REQUESTS_PER_MINUTE = 60;
+export const MAX_REQUESTS_PER_MINUTE = 30;
+
+const DAY_MS = 24 * 60 * 60_000;
+
+export class SeazonaSettingsError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'SeazonaSettingsError';
+    this.code = 'seazona_settings_invalid';
+  }
+}
+
+function text(value) {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+export function clampInt(value, fallback, min, max) {
+  const parsed = Number.parseInt(String(value ?? ''), 10);
+  if (!Number.isFinite(parsed)) return fallback;
+  return Math.min(max, Math.max(min, parsed));
+}
+
+// SEAZONA_API_BASE_URL is the API root, with or without /v1. It must be https:
+// the API takes basic authentication.
+export function normaliseBaseUrl(value) {
+  const raw = text(value);
+  if (!raw) return '';
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new SeazonaSettingsError('SEAZONA_API_BASE_URL is not a URL');
+  }
+  if (url.protocol !== 'https:') throw new SeazonaSettingsError('SEAZONA_API_BASE_URL must use https');
+  if (url.search || url.hash || url.username || url.password) {
+    throw new SeazonaSettingsError('SEAZONA_API_BASE_URL must be a plain address with no query, fragment or credentials');
+  }
+  const path = url.pathname.replace(/\/+$/, '').replace(/\/v1$/i, '');
+  return `${url.origin}${path}/v1`;
+}
+
+// Returns the resolved settings, or throws SeazonaSettingsError. `mode` is
+// null when SEAZONA_MODE is unset: the adapter is then not configured.
+export function resolveSeazonaSettings(env = process.env) {
+  const modeText = text(env.SEAZONA_MODE).toLowerCase();
+  if (modeText && !MODES.includes(modeText)) {
+    throw new SeazonaSettingsError(`SEAZONA_MODE must be one of ${MODES.join(', ')}`);
+  }
+  const mode = modeText || null;
+
+  const rate = {
+    requestsPerMinute: clampInt(env.SEAZONA_API_REQUESTS_PER_MINUTE, MAX_REQUESTS_PER_MINUTE, 1, MAX_REQUESTS_PER_MINUTE),
+    publishedLimitPerMinute: PUBLISHED_REQUESTS_PER_MINUTE,
+    // Retries cover 429 and 5xx answers only. Every attempt counts against
+    // the limit, so keep this small.
+    maxRetries: clampInt(env.SEAZONA_API_MAX_RETRIES, 2, 0, 6),
+    timeoutMs: clampInt(env.SEAZONA_API_TIMEOUT_MS, 30_000, 1_000, 120_000),
+    // How long one request may wait for a free slot before it gives up.
+    maxWaitMs: clampInt(env.SEAZONA_API_MAX_WAIT_MS, 120_000, 1_000, 15 * 60_000),
+    // Long enough to answer a vendor's question about last month.
+    telemetryRetentionMs: clampInt(env.SEAZONA_API_TELEMETRY_RETENTION_DAYS, 35, 1, 90) * DAY_MS,
+  };
+
+  const MINUTE = 60_000;
+  const ms = (name, fallback, min, max) => clampInt(env[name], fallback, min, max);
+  const sync = {
+    // How often each lane runs in live mode, and how old its data may get
+    // before /health calls it stale.
+    lanes: {
+      invoices: { cadenceMs: ms('SEAZONA_INVOICE_CADENCE_MS', 2 * MINUTE, MINUTE, DAY_MS), freshnessMs: 10 * MINUTE },
+      orders_recent: { cadenceMs: ms('SEAZONA_ORDER_CADENCE_MS', 5 * MINUTE, MINUTE, DAY_MS), freshnessMs: 15 * MINUTE },
+      orders_active: { cadenceMs: ms('SEAZONA_ACTIVE_ORDER_CADENCE_MS', 5 * MINUTE, MINUTE, DAY_MS), freshnessMs: 30 * MINUTE },
+      clients: { cadenceMs: ms('SEAZONA_CLIENT_CADENCE_MS', 30 * MINUTE, MINUTE, DAY_MS), freshnessMs: 60 * MINUTE },
+      products: { cadenceMs: ms('SEAZONA_REFERENCE_CADENCE_MS', DAY_MS, MINUTE, 30 * DAY_MS), freshnessMs: 2 * DAY_MS },
+      users: { cadenceMs: ms('SEAZONA_REFERENCE_CADENCE_MS', DAY_MS, MINUTE, 30 * DAY_MS), freshnessMs: 2 * DAY_MS },
+    },
+    // Re-read this much before a lastModified cursor, so a change written
+    // while the last run was reading is not missed.
+    cursorOverlapMs: 5 * MINUTE,
+    // The recent-order lane reads orders placed in the last N days, a few
+    // days per run (GET orders/?ordered= matches one UTC day).
+    orderLookbackDays: clampInt(env.SEAZONA_ORDER_LOOKBACK_DAYS, 30, 1, 3650),
+    orderDaysPerRun: clampInt(env.SEAZONA_ORDER_DAYS_PER_RUN, 6, 1, 31),
+    // The first invoice run reads from the start of today (UTC) minus this.
+    invoiceLookbackDays: clampInt(env.SEAZONA_INVOICE_LOOKBACK_DAYS, 0, 0, 3650),
+    // Seazona documents no paging. A list exactly this long may be cut off,
+    // so the lane holds its cursor instead of trusting it.
+    listCap: clampInt(env.SEAZONA_LIST_CAP, 50, 1, 10_000),
+    // The active-order lane re-reads this many open orders per run, oldest first.
+    activeOrdersPerRun: clampInt(env.SEAZONA_ACTIVE_ORDERS_PER_RUN, 25, 1, 500),
+    // Issue #12: after this many failed reads in a row an order waits this long.
+    orderQuarantineFailures: clampInt(env.SEAZONA_ORDER_QUARANTINE_FAILURES, 3, 1, 20),
+    orderQuarantineMs: ms('SEAZONA_ORDER_QUARANTINE_MS', DAY_MS, 5 * MINUTE, 30 * DAY_MS),
+    // A failed lane waits 1 minute, doubling to at most 6 hours.
+    retryBaseMs: MINUTE,
+    retryMaxMs: 6 * 60 * MINUTE,
+    heldRetryMs: 60 * MINUTE,
+    // A lane marked as running for longer than this is taken to have died.
+    stuckLaneMs: 20 * MINUTE,
+    // VISION.md: Flow keeps a patient reference only where an invoice must
+    // print one. Off by default; on, orders and invoices keep Seazona's
+    // patient field as the reference.
+    keepPatientReference: ['1', 'true', 'on', 'yes'].includes(text(env.SEAZONA_KEEP_PATIENT_REFERENCE).toLowerCase()),
+  };
+
+  const settings = {
+    mode,
+    sync,
+    baseUrl: '',
+    credentials: null,
+    replayFile: '',
+    rate,
+    // The scheduler starts only in live mode (issue #10).
+    scheduled: mode === 'live',
+  };
+
+  if (mode === 'live' || mode === 'sandbox') {
+    settings.baseUrl = normaliseBaseUrl(env.SEAZONA_API_BASE_URL);
+    if (!settings.baseUrl) throw new SeazonaSettingsError(`SEAZONA_API_BASE_URL is required in ${mode} mode`);
+    const clientId = text(env.SEAZONA_API_CLIENT_ID);
+    const clientSecret = text(env.SEAZONA_API_CLIENT_SECRET);
+    if (!clientId || !clientSecret) {
+      throw new SeazonaSettingsError(`SEAZONA_API_CLIENT_ID and SEAZONA_API_CLIENT_SECRET are required in ${mode} mode`);
+    }
+    settings.credentials = { clientId, clientSecret };
+  } else if (mode === 'replay') {
+    settings.replayFile = text(env.SEAZONA_REPLAY_FILE);
+    if (!settings.replayFile) throw new SeazonaSettingsError('SEAZONA_REPLAY_FILE is required in replay mode');
+    // Replay never reaches a network, so the address is only a label.
+    settings.baseUrl = 'https://seazona.replay.invalid/v1';
+  }
+
+  return settings;
+}
+
+// What /health and Settings may show. Never the credentials or the host.
+export function describeSeazonaSettings(settings) {
+  return {
+    mode: settings?.mode ?? null,
+    configured: Boolean(settings?.mode),
+    scheduled: Boolean(settings?.scheduled),
+    requestsPerMinute: settings?.rate?.requestsPerMinute ?? null,
+    publishedLimitPerMinute: PUBLISHED_REQUESTS_PER_MINUTE,
+  };
+}