@arcforgelabs/flow 2026.10.18 → 2026.10.19

package/server/integrations/seazona/ledger.js

@@ -0,0 +1,66 @@
+// Seazona work, shaped for the billing obligation ledger (server/core/ledger.js,
+// issue #3). The adapter does not import the ledger: the core reads the
+// billing feed and passes these shapes to it.
+//
+//   item.ledgerJob       -> observeJob(db, organisationId, { ...item.ledgerJob, contactId })
+//   withdrawn.ledgerHold -> setHold(db, organisationId, <obligation id>, { ...ledgerHold, actor })
+//
+// One Seazona order is one billable job. The contact is Flow's, so the core
+// resolves it (from item.client) and adds contactId; the ledger keeps a job
+// without one pending.
+
+export const SEAZONA_SOURCE_SYSTEM = 'seazona';
+
+function ledgerLine(line) {
+  return {
+    // The ledger maps a line to a price item by its exact code only.
+    itemCode: line.code ?? null,
+    description: line.description,
+    quantity: 1,
+    // Unknown amount or tax: the price item with the same code fills them.
+    unitAmountCents: line.amountCents ?? undefined,
+    taxCode: typeof line.taxable === 'boolean' ? (line.taxable ? 'GST' : 'GST_FREE') : undefined,
+  };
+}
+
+// The lines that bill the job. When the job's Seazona invoice carries this
+// order and no other, its lines are what the lab billed, discounts included.
+// When it carries several orders, its lines cannot be split between them, so
+// the order's own lines are used and nothing is billed twice.
+export function ledgerLinesFor(item) {
+  const invoiceLines = item.invoice?.lines ?? [];
+  const useInvoice = item.invoice && item.invoiceOrderCount === 1 && invoiceLines.length > 0;
+  return { lines: (useInvoice ? invoiceLines : item.lines ?? []).map(ledgerLine), linesFrom: useInvoice ? 'invoice' : 'order' };
+}
+
+// observeJob's input for one billable feed item, without contactId.
+// `observedAt` is the last successful read from Seazona, so the ledger's
+// out-of-date check measures how old Seazona's report really is.
+export function toLedgerJob(item) {
+  return {
+    sourceSystem: SEAZONA_SOURCE_SYSTEM,
+    sourceJobRef: item.sourceId,
+    sourceInvoiceRef: item.invoiceNumber ?? null,
+    // The Seazona order id is the case number. Never patient data.
+    caseRef: item.sourceId,
+    practitioner: item.doctorName ?? null,
+    // The Seazona API gives a shipped status but no shipped date.
+    shippedOn: null,
+    lines: ledgerLinesFor(item).lines,
+    observedAt: item.syncedAt,
+    actor: SEAZONA_SOURCE_SYSTEM,
+  };
+}
+
+// An order deleted in Seazona sends its obligation, if there is one, to
+// review: a person decides what happens to any invoice already made. An order
+// that only stopped being billable needs nothing from the ledger.
+export function toLedgerHold(entry) {
+  if (entry.reason !== 'deleted_in_seazona') return null;
+  return {
+    sourceSystem: SEAZONA_SOURCE_SYSTEM,
+    sourceJobRef: entry.sourceId,
+    holdState: 'review',
+    reason: 'the order was deleted in Seazona',
+  };
+}

package/server/integrations/seazona/map.js

@@ -0,0 +1,229 @@
+import { createHash } from 'node:crypto';
+
+// Seazona API records, reduced to what billing needs. Each mapper takes the
+// list row and the detail read and returns the mirror row. Notes, files,
+// settings and other clinical detail are dropped. The patient field is kept
+// only as a reference, and only when the installation asks for it
+// (SEAZONA_KEEP_PATIENT_REFERENCE; VISION.md, "Why does Flow keep as little
+// patient data as it can?").
+
+export const DELETED_STATUS = 'Deleted in Seazona';
+
+// Statuses after which Seazona does not change an order again. "Complete" is
+// not one of them: a lab often moves a complete order to Shipped days or
+// months later, and the list API has no lastModified cursor for orders, so a
+// complete order stays in the active-order rotation until it ships.
+const FINAL_STATUS = /(shipped|delivered|cancelled|canceled|void|closed|archived|deleted)/i;
+
+export function text(value) {
+  if (value === null || value === undefined) return '';
+  return String(value).trim();
+}
+
+function textOrNull(value) {
+  return text(value) || null;
+}
+
+function number(value) {
+  if (value === null || value === undefined || value === '') return null;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+// Seazona reports dollars as decimals; Flow keeps integer cents.
+export function toCents(value) {
+  const amount = number(value);
+  return amount === null ? null : Math.round(amount * 100);
+}
+
+export function stableSerialize(value) {
+  if (value === null || value === undefined) return 'null';
+  if (Array.isArray(value)) return `[${value.map(stableSerialize).join(',')}]`;
+  if (typeof value === 'object') {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableSerialize(value[key])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+export function hashOf(value) {
+  return createHash('sha256').update(stableSerialize(value)).digest('hex');
+}
+
+export function isFinalStatus(status) {
+  return FINAL_STATUS.test(text(status));
+}
+
+export function isCompleteStatus(status) {
+  return /\bcomplete(?:d)?\b/i.test(text(status));
+}
+
+export function isShippedStatus(status) {
+  return /\b(shipped|delivered)\b/i.test(text(status));
+}
+
+// What a person sees for an order: its Seazona status, or "Deleted in
+// Seazona" once Seazona answered 404 for it.
+export function orderStatusLabel(row) {
+  return row?.deletedInSourceAt ? DELETED_STATUS : text(row?.status);
+}
+
+// Seazona dates come as ISO text or as day/month/year (Australian order),
+// with an optional time. Returns the calendar date (yyyy-mm-dd) or null.
+export function parseSeazonaDate(value) {
+  const raw = text(value);
+  if (!raw) return null;
+  const dmy = raw.match(/^(\d{1,2})\/(\d{1,2})\/(\d{2,4})\b/);
+  if (dmy) {
+    const day = Number(dmy[1]);
+    const month = Number(dmy[2]);
+    const year = dmy[3].length === 2 ? 2000 + Number(dmy[3]) : Number(dmy[3]);
+    const date = new Date(Date.UTC(year, month - 1, day));
+    if (date.getUTCMonth() !== month - 1 || date.getUTCDate() !== day) return null;
+    return date.toISOString().slice(0, 10);
+  }
+  const iso = raw.match(/^(\d{4})-(\d{2})-(\d{2})/);
+  return iso ? `${iso[1]}-${iso[2]}-${iso[3]}` : null;
+}
+
+function mapLine(item = {}, { discount = false } = {}) {
+  const amountCents = toCents(item.price ?? item.amount);
+  const line = {
+    itemId: textOrNull(item.id),
+    kind: discount ? 'discount' : (text(item.type) || 'product'),
+    description: text(item.name || item.description),
+    code: textOrNull(item.code),
+    amountCents: discount && amountCents !== null ? -Math.abs(amountCents) : amountCents,
+  };
+  if (typeof item.taxable === 'boolean') line.taxable = item.taxable;
+  if (item.tooth !== undefined && item.tooth !== null && text(item.tooth)) line.tooth = text(item.tooth);
+  return line;
+}
+
+const sumCents = (lines) => lines.reduce((sum, line) => sum + (line.amountCents ?? 0), 0);
+
+// The list fields that tell an order changed. Equal signatures mean the
+// detail read can be skipped. The patient field is left out, so not even a
+// hash of it is stored.
+export function orderListSignature(item = {}) {
+  return hashOf({
+    id: text(item.id),
+    invoiceNumber: text(item.invoiceNumber),
+    company: text(item.company),
+    doctor: text(item.clientName),
+    status: text(item.status),
+    department: text(item.department),
+    ordered: text(item.ordered),
+    due: text(item.due),
+  });
+}
+
+export function mapOrder(listItem = {}, detail = null, { keepPatientReference = false } = {}) {
+  const merged = { ...listItem, ...(detail || {}) };
+  const lines = Array.isArray(merged.products)
+    ? merged.products.map((item) => mapLine(item)).filter((line) => line.description)
+    : [];
+  return {
+    id: text(merged.id),
+    invoiceNumber: textOrNull(merged.invoiceNumber),
+    clientId: textOrNull(merged.clientId),
+    company: textOrNull(merged.company),
+    doctorName: textOrNull(merged.clientName),
+    status: textOrNull(merged.status),
+    orderedText: textOrNull(merged.ordered),
+    dueText: textOrNull(merged.due),
+    lastModifiedText: textOrNull(merged.lastModified),
+    department: textOrNull(merged.department),
+    lines,
+    subtotalCents: lines.length ? sumCents(lines) : null,
+    patientReference: keepPatientReference ? textOrNull(merged.patient) : null,
+  };
+}
+
+export function invoiceListSignature(item = {}) {
+  return hashOf({
+    id: text(item.id),
+    invoiceNumber: text(item.invoiceNumber),
+    clientId: text(item.clientId),
+    status: text(item.status),
+    due: text(item.due),
+    lastModified: text(item.lastModified),
+    subtotal: number(item.subtotal ?? item.sales),
+    tax: number(item.tax),
+    total: number(item.total),
+  });
+}
+
+export function mapInvoice(listItem = {}, detail = null, { keepPatientReference = false } = {}) {
+  const merged = { ...listItem, ...(detail || {}) };
+  const products = Array.isArray(merged.productServiceItems) ? merged.productServiceItems.map((item) => mapLine(item)) : [];
+  const discounts = Array.isArray(merged.discountItems) ? merged.discountItems.map((item) => mapLine(item, { discount: true })) : [];
+  const lines = [...products, ...discounts].filter((line) => line.description);
+  return {
+    invoiceNumber: text(merged.invoiceNumber),
+    seazonaId: textOrNull(merged.id),
+    clientId: textOrNull(merged.clientId),
+    accountNumber: textOrNull(merged.accountNumber),
+    company: textOrNull(merged.company),
+    doctorName: textOrNull(merged.fullName),
+    status: textOrNull(merged.status),
+    invoiceDateText: textOrNull(merged.invoiceDate || merged.created),
+    dueText: textOrNull(merged.due),
+    lastModifiedText: textOrNull(merged.lastModified),
+    lines,
+    subtotalCents: toCents(merged.subtotal ?? merged.sales),
+    taxCents: toCents(merged.tax),
+    totalCents: toCents(merged.total),
+    discountCents: toCents(merged.discounts),
+    patientReference: keepPatientReference ? textOrNull(merged.patient) : null,
+  };
+}
+
+export function clientListSignature(item = {}) {
+  return hashOf({
+    id: text(item.id),
+    accountNumber: text(item.accountNumber),
+    company: text(item.company),
+    fullName: text(item.fullName),
+    email: text(item.email || item.emailAddresses),
+    phone: text(item.phone1 || item.phone),
+    lastModified: text(item.lastModified),
+    discontinued: Boolean(item.discontinued),
+  });
+}
+
+export function mapClient(listItem = {}, detail = null) {
+  const merged = { ...listItem, ...(detail || {}) };
+  const address = {};
+  for (const field of ['address1', 'address2', 'city', 'region', 'postalCode', 'countryCode']) {
+    if (text(merged[field])) address[field] = text(merged[field]);
+  }
+  return {
+    id: text(merged.id),
+    accountNumber: textOrNull(merged.accountNumber),
+    company: textOrNull(merged.company),
+    fullName: textOrNull(merged.fullName),
+    email: textOrNull(merged.email || merged.emailAddresses),
+    phone: textOrNull(merged.phone1 || merged.phone),
+    address: Object.keys(address).length ? address : null,
+    taxRate: number(merged.taxRate) === null ? null : String(number(merged.taxRate)),
+    active: merged.discontinued === undefined ? null : !merged.discontinued,
+    // Who at the practice the work is for: an id and a name, nothing more.
+    doctors: Array.isArray(merged.doctors)
+      ? merged.doctors.map((doctor) => ({ id: text(doctor?.id), fullName: text(doctor?.fullName) })).filter((doctor) => doctor.id)
+      : [],
+    lastModifiedText: textOrNull(merged.lastModified),
+  };
+}
+
+export function mapReference(resource, item = {}) {
+  const name = text(item.name || item.fullName || [item.firstName, item.lastName].map(text).filter(Boolean).join(' '));
+  return {
+    resource,
+    id: text(item.id),
+    name: name || null,
+    code: resource === 'products' ? textOrNull(item.code) : null,
+    kind: resource === 'products' ? textOrNull(item.type) : null,
+    priceCents: resource === 'products' ? toCents(item.price ?? item.amount) : null,
+    taxable: resource === 'products' && typeof item.taxable === 'boolean' ? item.taxable : null,
+  };
+}

package/server/integrations/seazona/migrations/0000_api_governor.sql

@@ -0,0 +1,20 @@
+CREATE TABLE "seazona_api_governor" (
+	"client_key" text PRIMARY KEY NOT NULL,
+	"next_eligible_at" timestamp with time zone DEFAULT 'epoch' NOT NULL,
+	"cooldown_until" timestamp with time zone DEFAULT 'epoch' NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "seazona_api_requests" (
+	"id" bigserial PRIMARY KEY NOT NULL,
+	"client_key" text NOT NULL,
+	"workflow" text NOT NULL,
+	"admitted_at" timestamp with time zone NOT NULL,
+	"request_path" text,
+	"status_code" integer,
+	"failure_kind" text,
+	"duration_ms" integer,
+	"is_retry" boolean DEFAULT false NOT NULL
+);
+--> statement-breakpoint
+CREATE INDEX "seazona_api_requests_window" ON "seazona_api_requests" USING btree ("client_key","admitted_at");

package/server/integrations/seazona/migrations/0001_mirror.sql

@@ -0,0 +1,106 @@
+CREATE TABLE "seazona_clients" (
+	"id" text PRIMARY KEY NOT NULL,
+	"account_number" text,
+	"company" text,
+	"full_name" text,
+	"email" text,
+	"phone" text,
+	"address" jsonb,
+	"tax_rate" text,
+	"active" boolean,
+	"doctors" jsonb DEFAULT '[]'::jsonb NOT NULL,
+	"last_modified_text" text,
+	"list_signature" text,
+	"record_hash" text NOT NULL,
+	"first_seen_at" timestamp with time zone NOT NULL,
+	"last_synced_at" timestamp with time zone NOT NULL,
+	"last_changed_at" timestamp with time zone NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "seazona_invoices" (
+	"invoice_number" text PRIMARY KEY NOT NULL,
+	"seazona_id" text,
+	"client_id" text,
+	"account_number" text,
+	"company" text,
+	"doctor_name" text,
+	"status" text,
+	"invoice_date_text" text,
+	"due_text" text,
+	"last_modified_text" text,
+	"lines" jsonb DEFAULT '[]'::jsonb NOT NULL,
+	"subtotal_cents" bigint,
+	"tax_cents" bigint,
+	"total_cents" bigint,
+	"discount_cents" bigint,
+	"patient_reference" text,
+	"list_signature" text,
+	"record_hash" text NOT NULL,
+	"first_seen_at" timestamp with time zone NOT NULL,
+	"last_synced_at" timestamp with time zone NOT NULL,
+	"last_changed_at" timestamp with time zone NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "seazona_lane_state" (
+	"lane" text PRIMARY KEY NOT NULL,
+	"status" text DEFAULT 'idle' NOT NULL,
+	"cursor_time" timestamp with time zone,
+	"cursor" jsonb DEFAULT '{}'::jsonb NOT NULL,
+	"last_success_at" timestamp with time zone,
+	"last_attempt_at" timestamp with time zone,
+	"next_run_at" timestamp with time zone,
+	"failure_count" integer DEFAULT 0 NOT NULL,
+	"last_error" text,
+	"failure_details" jsonb,
+	"held_reason" text,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "seazona_order_read_failures" (
+	"order_id" text PRIMARY KEY NOT NULL,
+	"failure_count" integer NOT NULL,
+	"last_attempt_at" timestamp with time zone NOT NULL,
+	"last_http_status" integer,
+	"last_failure_kind" text,
+	"last_error" text,
+	"quarantined_until" timestamp with time zone
+);
+--> statement-breakpoint
+CREATE TABLE "seazona_orders" (
+	"id" text PRIMARY KEY NOT NULL,
+	"invoice_number" text,
+	"client_id" text,
+	"company" text,
+	"doctor_name" text,
+	"status" text,
+	"ordered_text" text,
+	"due_text" text,
+	"last_modified_text" text,
+	"department" text,
+	"lines" jsonb DEFAULT '[]'::jsonb NOT NULL,
+	"subtotal_cents" bigint,
+	"patient_reference" text,
+	"deleted_in_source_at" timestamp with time zone,
+	"list_signature" text,
+	"record_hash" text NOT NULL,
+	"first_seen_at" timestamp with time zone NOT NULL,
+	"last_synced_at" timestamp with time zone NOT NULL,
+	"last_changed_at" timestamp with time zone NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "seazona_reference" (
+	"resource" text NOT NULL,
+	"id" text NOT NULL,
+	"name" text,
+	"code" text,
+	"kind" text,
+	"price_cents" bigint,
+	"taxable" boolean,
+	"record_hash" text NOT NULL,
+	"last_synced_at" timestamp with time zone NOT NULL,
+	CONSTRAINT "seazona_reference_resource_id_pk" PRIMARY KEY("resource","id")
+);
+--> statement-breakpoint
+CREATE INDEX "seazona_invoices_changed" ON "seazona_invoices" USING btree ("last_changed_at");--> statement-breakpoint
+CREATE INDEX "seazona_orders_invoice_number" ON "seazona_orders" USING btree ("invoice_number");--> statement-breakpoint
+CREATE INDEX "seazona_orders_changed" ON "seazona_orders" USING btree ("last_changed_at");

package/server/integrations/seazona/migrations/meta/0000_snapshot.json

@@ -0,0 +1,149 @@
+{
+  "id": "3bb4b809-5730-4ae9-8127-2766cac649c6",
+  "prevId": "00000000-0000-0000-0000-000000000000",
+  "version": "7",
+  "dialect": "postgresql",
+  "tables": {
+    "public.seazona_api_governor": {
+      "name": "seazona_api_governor",
+      "schema": "",
+      "columns": {
+        "client_key": {
+          "name": "client_key",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "next_eligible_at": {
+          "name": "next_eligible_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'epoch'"
+        },
+        "cooldown_until": {
+          "name": "cooldown_until",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'epoch'"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.seazona_api_requests": {
+      "name": "seazona_api_requests",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "bigserial",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "client_key": {
+          "name": "client_key",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "workflow": {
+          "name": "workflow",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "admitted_at": {
+          "name": "admitted_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "request_path": {
+          "name": "request_path",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "status_code": {
+          "name": "status_code",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "failure_kind": {
+          "name": "failure_kind",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "duration_ms": {
+          "name": "duration_ms",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "is_retry": {
+          "name": "is_retry",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        }
+      },
+      "indexes": {
+        "seazona_api_requests_window": {
+          "name": "seazona_api_requests_window",
+          "columns": [
+            {
+              "expression": "client_key",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "admitted_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    }
+  },
+  "enums": {},
+  "schemas": {},
+  "sequences": {},
+  "roles": {},
+  "policies": {},
+  "views": {},
+  "_meta": {
+    "columns": {},
+    "schemas": {},
+    "tables": {}
+  }
+}