Seazona adapter

Seazona is the lab's case system. The Seazona adapter reads what billing needs through the Seazona REST API: invoices, orders, clients, products and users. It never writes to Seazona, and it never drives a browser. The code is in server/integrations/seazona/. Core code never imports it (CONTRIBUTING.md).

Status: the adapter is on the integration port. It keeps Seazona's invoices, orders, clients, products and users in step and gives invoice preparation a billing feed. Invoice preparation itself is not built yet.

Turn it on #

In Flow, an owner opens Integrations, then Seazona: choose the mode, paste the API address, client id and client secret, and press Save and turn Seazona on. Seazona starts at once; live mode starts the background sync. The secret is stored sealed (docs/INTEGRATIONS.md, "Set up in Flow").

A host can instead turn it on with environment settings:

1. Add seazona to FLOW_INTEGRATIONS (docs/INTEGRATIONS.md). Its tables are created at the next start.
2. Set SEAZONA_MODE and the settings for that mode (below). With Seazona on and no mode, or a malformed setting, Flow does not start: the adapter never guesses which account it acts on.
3. Start Flow. The log says [seazona] mode live; background sync on.
4. Check GET /health: integrations lists Seazona with its mode, each lane and the rate governor.

In sandbox or replay, sync when you choose:

DATABASE_URL=postgres://… FLOW_INTEGRATIONS=seazona SEAZONA_MODE=sandbox … \
  node server/integrations/seazona/sync-once.js [lane …]

It runs the named lanes (all when none is named) once, through the rate governor, and prints what each did.

Modes #

The mode says which environment the adapter acts on (issue #10). It comes from SEAZONA_MODE only. There is no default: with no mode the adapter does nothing.

Development and CI use replay or sandbox. Never give a development workspace live credentials.

Settings #

The code holds no Seazona host or account. Every address and credential is configuration.

Rate governor #

Seazona publishes a limit of 60 requests a minute for each API client. Flow stays at 30, and counts every process that shares the database as one client, because Seazona does (server/integrations/seazona/governor.js):

• A request waits until fewer than 30 requests went out in the last minute, and at least 2 seconds have passed since the last one.
• A 429 answer with Retry-After holds every process for that long (at most 60 seconds).
• A 429 or 5xx answer is retried at most SEAZONA_API_MAX_RETRIES times, with a growing wait. Each retry counts against the limit.
• A request that waits longer than SEAZONA_API_MAX_WAIT_MS gives up with seazona_api_governor_timeout.
• In live and sandbox the client refuses to start without the governor, so no code path can call Seazona ungoverned.

Failed calls (issue #101) #

Seazona can cut off an account's API access when it sees many failed calls, even inside the rate limit. So the governor also stops calls, through the shared call guard (docs/INTEGRATIONS.md, "Outbound calls", issue #111) on the governor's own tables. A stopped call fails at once with SeazonaCallsStopped and makes no request.

flowchart LR
  call[Call] --> ok{Answer}
  ok -- 2xx or 404 on one record --> closed[Circuit closed]
  ok -- 401 or 403 --> halt[Halted: no call until a person saves the settings]
  ok -- 5xx, 429, other 4xx, timeout --> count[Count the failure]
  count -- 5 in 10 min --> open[Open: no call for the pause]
  open -- pause ends --> probe[One probe call]
  probe -- fails --> open2[Open again, pause doubled, at most 6 h]
  probe -- works --> closed
  count -- 50 today --> day[No call until the next UTC day]

Each held failure is reported once to the error services that are on (log.error, docs/SENTRY.md): a lane that starts failing or changes its failure code, a stopped lane, an open circuit, a spent budget, and records newly quarantined. A repeat of the same failure is a warning in the host log only. The report text names the lane and the code, never a record, a host or a credential, so the error service groups repeats. With no error service on, the host log has the same lines.

Each request leaves one row in seazona_api_requests: when it went, the request path (for example /v1/orders/<order id>), the status or failure kind, the time it took and whether it was a retry. The row never holds the host, the query, a credential or a response. governor.summarise({ from, to }) gives the totals for a period and each failing path with its count, which answers a question such as "why did this account make thousands of failed reads last month?".

The background sync #

Only live mode starts it (server/integrations/seazona/scheduler.js). It first runs 5 seconds after start, runs every lane that is due, then sleeps until the next lane is due (at least 15 seconds, at most 30 minutes). One run at a time; a lane that another process is running is skipped.

Sync lanes #

Each lane keeps one kind of record fresh, on its own cadence (server/integrations/seazona/lanes.js). One failing lane never stops another.

A list row whose list fields did not change costs no detail read.

A list SEAZONA_LIST_CAP long may be cut off, so the lane reads on (issue #125):

• Invoices and clients have no paging. Seazona's guide says the invoice list answers changes on or after lastModified, oldest first. So a full list is one part of the window: the next part starts at its last row's lastModified (clients: one second before it). A run that reaches SEAZONA_LIST_PAGES_PER_RUN stores the exact start of the next part, and the next run goes on from it, with no 5-minute overlap.
• Orders are paged. A full page goes on to the next page. A short page, or a page whose last order is two days past the day, ends the day. A run that stops inside a day goes on from that page next time.

The lane holds (held), keeps where it got to and tries again in an hour only where it cannot go on: a full list whose rows are not oldest first, a full list inside one second, a next order page that answers the same orders again, or a products or users list exactly at the cap (those lists come whole, with no paging).

A failed lane waits 1 minute, doubling to at most 6 hours, or as long as a 429 asked. A lane that says it is running for more than 20 minutes is taken to have died, and another run may claim it.

Sweep (issue #126) #

The cursor lanes see only what their queries return. An edit to an order older than the recent-order window that has left the active rotation, a record deleted in Seazona, and a change behind a cursor that moved too far can pass them by. The sweep lane (server/integrations/seazona/sweep.js) reads whole lists again on a slow cycle and compares them with Flow's copy:

• A client or invoice that answers 404 is marked missing. Its row is never deleted. The mark clears when Seazona lists it again.
• A change at or after where the owning lane reads next is left to that lane and costs no call.
• Each kind starts again at most once a cycle (7 days). The sweep makes at most 10 calls a run and 100 a UTC day, through the same rate governor and call guard as every lane, and keeps its place in the lane's cursor.
• An order or record whose read fails is recorded as in any lane, and is not read again in the same cycle.
• What the sweep finds that the lanes missed (changed, created, deleted, missing) is kept in seazona_sweep_findings and reported to the error services once a run. A count above zero is a signal to fix a lane.
• The source high-water mark is the latest lastModified Flow holds for invoices and for clients. /health shows it beside where the owning lane reads next. When Seazona's time is ahead of Flow's clock by more than the 5-minute cursor overlap, the sweep reports it once.

Bad orders (issue #12) #

Every order read follows these rules:

• A 404 marks the order deleted in Seazona. Its row and history stay and its sync time is refreshed, so it never comes first again. It reads as "Deleted in Seazona", leaves the active-order rotation and is out of billing. If it shows up in an order list again it is read, and a successful read clears the mark.
• Each other failure is recorded per order (seazona_order_read_failures): the HTTP status or the kind (empty_response, timeout, invalid_json, network). A failed order moves to the back of the rotation.
• An empty answer is a failure, never a success.
• After 3 failures in a row an order is quarantined for 1 day, then gets one more read. A failure then quarantines it again; a success clears it.
• A lane fails only when most of its reads fail. A few bad orders never push every other order into the lane's backoff.
• A 429, or a request that waits too long for a slot, stops the lane without counting against any order: it is about Seazona, not the order.
• Errors name each failing order. A failed lane's error lists up to 10 as ORD-1 (HTTP 500), ORD-2 (timeout). The lane's failure details hold up to 25, with the quarantined orders. readSeazonaSyncHealth() returns them for /health. None of it holds patient data.

What is kept #

The mirror keeps what billing needs, in integer cents as Seazona reported them: order and invoice numbers, practice and dentist, status, dates, lines (description, code, amount, taxable) and totals; client account, email, phone, address and dentist names; product prices; user names. It keeps no notes, files, settings, staff email or dentist phone, and no patient field unless SEAZONA_KEEP_PATIENT_REFERENCE is on.

Billing feed #

The adapter's pullWorkItems(cursor) capability is what invoice preparation reads (server/integrations/seazona/feed.js). Each call returns the orders that changed since the cursor, oldest change first, up to 200:

• items: complete and shipped orders. Each has the order (sourceId, invoiceNumber, status, shipped, practice, dentist, orderedOn, dueOn, lines, subtotalCents, patientReference), the Seazona invoice that carries it (invoice, or null) and the practice's account and email (client).
• withdrawn: every other changed order, with reason deleted_in_seazona or not_billable, so work already held for it can be dropped. An order deleted in Seazona is never an item, from any cursor.
• cursor: pass it to the next call. more is true when the page was full.

Each item also carries ledgerJob and each withdrawn entry ledgerWithdrawn, shaped for the billing obligation ledger (below).

A change to an order or to its Seazona invoice puts the order at the end of the feed again. A read that finds no change does too, at most once an hour, so the ledger's report of the order never gets older than a day while a lane still reads it (the ledger refuses a draft from a report over a day old). An order no lane reads again (shipped, and placed before the recent-order lookback) is not reported again. Before Flow drafts or sends from such a job, it reads the order now (readWorkItem, server/integrations/seazona/act.js; server/core/read-before-act.js): one GET orders/{id} through the call guard, stored through the mirror, answered as the feed would answer it. Call registry.whenEnabled('seazona', …) to reach it, so a turned-off adapter answers as turned off (docs/INTEGRATIONS.md).

Billing ledger #

The feed is shaped for the billing obligation ledger (server/core/ledger.js, issue #3). One Seazona order is one billable job (server/integrations/seazona/ledger.js):

for (const item of page.items) {
  await observeJob(db, organisationId, { ...item.ledgerJob, contactId: contactFor(item.client) });
}
for (const { ledgerWithdrawn } of page.withdrawn) {
  await observeWithdrawn(db, organisationId, ledgerWithdrawn);
}

Amounts are tax-exclusive, as Seazona reports them, and the ledger adds GST per line. An order deleted in Seazona sends its obligation to review (ledgerWithdrawn); a person decides what happens to any invoice already made. An order whose status moves back (for example from Shipped to In Production) loses an unsent ready mark, and goes to review when its invoice was made (docs/DATA_SPINE.md, "When a job changes after its invoice"). The ledger's "paid" write-back to Seazona is not built: this adapter only reads.

History import #

The API sync reads forward from the day it started. The history import brings in the years before that, so Flow holds the lab's full job history. It has two sources, and both end in the same batches, reconciliation and history table:

• The API backfill (the main source, below). It reads every past order from the Seazona API. Each order it reads is a batch row: the record of what the API confirmed.
• A CSV export (parked). Seazona's help pages document no export format, so this path is only for a file a person has. It is not built out further unless the API backfill cannot do the job.

The earlier app's own links from orders to Xero invoices are already in prior_links (imported at start); the matcher uses them as evidence for each history job (docs/JOB_INVOICE_LINKS.md). The earlier app read only 30 days of orders, so its archive is not a full history.

The API backfill #

An owner or admin starts it on Integrations › Seazona, History: pick the day in Read from and press Start (Stop ends it). Resume goes on where a stopped read stopped. Orders that any earlier read staged are skipped, so a read again over the same days costs only the list calls. The card shows the shared SyncStatus row: pulse until a real result, total jobs from history.jobs, the day rail and an approximate time remaining. Waiting shows the retry countdown. The page polls every five seconds only while visible and running or waiting. Resume starts a new clock without resetting the total. No steps dropdown is shown until persisted steps are available. GET /api/seazona/history gives the run's startedAt, persisted endedAt (after Stop or Done, so elapsed time survives reload), and its phase: running, waiting (the guard holds or a run failed; nextRunAt is the retry), failed (Seazona halted calls, or 3 runs failed in a row; cause says why), stopped or done. The page calls POST /api/seazona/history/backfill with { "from": "2019-01-01" } (and through, by default the day before the recent-order lane's window). The history lane then:

1. lists orders from the next day (GET orders/?ordered=<day>, with page and pageSize up to 500). Seazona's guide says the list answers the orders placed on or after that time, oldest first, in stable pages; the recent-order lane was built when it answered one day. The walk works either way: a full page goes on to the next page, a short page to the next day, and an order placed after through ends the walk unread;
2. leaves out the orders the live copy already holds;
3. reads each other order (GET orders/<id>), maps it as the live lanes do, and stages it as job case:<order id> in the backfill's batch;
4. reconciles each staged job at once, and writes a new one to Flow's history; a job that needs a person waits in the batch.

It makes at most SEAZONA_HISTORY_CALLS_PER_RUN calls a run (default 10, at most 25), every SEAZONA_HISTORY_CADENCE_MS (default 2 minutes), through the same rate governor, circuit and failed-call budget as the live lanes. At the default, about 300 calls an hour. A 404 means the order is gone and is skipped. Other failed reads are retried later in the walk and quarantined after SEAZONA_ORDER_QUARANTINE_FAILURES. A refused or halted call stops the lane as it stops the others. The lane keeps its place (day, page and orders still to read) in its cursor, so it resumes after a restart. When the last day is done, the batch waits like an upload for a person to decide what is left. POST /api/seazona/history/backfill/stop ends it early. GET /api/seazona/history shows backfill: the next day, days done, the latest order day reached, orders read and orders still to read.

CSV upload #

The code is in server/integrations/seazona/history/; the routes are under /api/seazona/history (routes.js). There is no screen yet.

flowchart LR
  file[Seazona CSV export] -- upload --> stage[Staged batch<br/>rows and jobs]
  stage --> rec[Reconcile]
  mirror[API copy<br/>orders, invoices, clients] --> rec
  hist[Flow history] --> rec
  rec -- new --> apply
  rec -- same --> skip[Skipped]
  rec -- needs a person or changed --> person[Person decides]
  person -- import --> apply[Apply]
  person -- skip --> skip
  apply --> hist
  hist -- pullHistoryJobs --> core[Core: ledger and matcher]

1. Upload. An owner or admin posts the file (POST /history/batches, a text/csv body with ?fileName=, or JSON { csv, fileName, columns }, at most 25 MB and 200,000 rows). Flow guesses each column from its header (below); columns corrects a guess ({ "doctorName": "Client Name" }). A file without a practice, an item, an amount and a date is refused, and the answer lists the headers it has. The same file uploaded again answers its first batch.
2. Read. Each row is read into Flow fields. A row with a bad or missing date, practice, item or amount joins no job and is listed with its problems. Columns Flow does not know are listed by name; their values are never stored. The patient column groups rows into jobs and is stored only when SEAZONA_KEEP_PATIENT_REFERENCE is on.
3. Group. Rows with the same invoice number are one job; with no invoice number, the same case number; with neither, the same date, practice, doctor and patient, as the earlier app grouped them. A job with no number is keyed by its content without the patient, so no patient value or hash is kept.
4. Reconcile. Each job is compared with what Flow holds. It reads Flow's database only.
5. Decide. A person settles each job that waits: POST /history/batches/:id/decisions with { decisions: [{ jobKey, decision: "import" | "skip" | null, clientId? }] }.
6. Apply. POST /history/batches/:id/apply reconciles once more, then writes each new job and each job a person chose to import into seazona_history_jobs. A batch is applied once. Nothing in the API copy changes.

Outcomes: new (apply writes it), same (already in Flow's history, skipped), changed and needs_person (wait for a decision). A difference is a finding, never a silent change.

The headers Flow reads (GET /history/columns). They compare without case, spaces or punctuation:

"Client Name" is not guessed: in Seazona it can mean the doctor or the practice, so map it with columns.

pullHistoryJobs(cursor) gives the applied jobs as ledger jobs marked historical, oldest change first. A job the API copy also holds uses the same order id as sourceJobRef, so the two are one job; others use the case number, else history:<job key>. health() shows history: jobs held, how many the API copy also has, the first and last job date, and open batches.

History jobs in the ledger #

The pipeline reads pullHistoryJobs after the live feed (server/core/pipeline.js, ingestHistory; server/core/history.js):

The matcher runs on held jobs too, so each history job gets its accounting state. GET /api/seazona/history/ledger lists the held history jobs by that state; ?state=needs_person gives not_found, ambiguous and conflict. A matched job stays held: it is history and already invoiced. Only a person's release (POST /api/seazona/history/ledger/:obligationId/release) moves a job into drafting. The Jobs board and GET /api/invoicing/jobs leave held history jobs out; /jobs?history=include shows them, and its counts.history gives how many there are.

Issues on job cards #

A history job a person must decide (outcome needs_person, or changed with no decision) is an issue on the card of the job it belongs to: the order with that id on the Jobs board. The adapter's jobIssues gives each issue as one short phrase (for example "Seazona client is unclear") and a link to the Seazona integration's reconciliation, /integrations/seazona?batch=<id>&job=<job key>. A person's decision there clears the issue: the board reads issues again each time. health() shows history.waitingForPerson, the count for the integration's card.

Health #

health() reads Flow's database only; it never calls Seazona. GET /health shows it under integrations:

• mode, scheduled and the request limit;
• governor: requests in the last minute, any 429 cooldown, the last day's requests, failures, 429s and retries, the circuit (closed, open, half_open, halted) with circuitOpenUntil and haltedReason, and failedToday against dailyFailureBudget. The last day's failures are split into faults (what the call guard counts) and notFound (404s), and failures lists the top 10 groups by path shape (record ids shown as :id), status and kind (issue #144);
• scheduler: the next run, the last run, and stuckSince while a run has not ended after 20 minutes. The scheduler then reports it once and goes on with the next run without it (issue #143);
• lanes: for each lane its status (ok, failed, held, stopped, processing, never_run), whether it is fresh or stale, its last success and error, and the failing orders by id and status; orders_active also lists the quarantined orders, and invoices and clients show quarantinedRecords and rereadDue (waits ended, re-read not yet made);
• deletedOrders: how many orders are marked deleted in Seazona;
• readsBeforeAct: today's reads before a draft or a send (reads, changed, withdrawn, unavailable), counted in memory since the last start, or null when there was none;
• sweep (issue #126): its calls today against the daily share, when each kind of record was last checked, what it found in the last 7 days by record kind, the clients and invoices marked missing, and the source high-water mark for invoices and clients (sourceLastModified, laneReadsFrom, gapMs, seazonaAhead).

ok is false while a lane is failed, held, stopped or stale, or a run is stuck. A lane is stale when it ran before and has not succeeded within its freshness limit, or two of its cadences if that is longer (issue #143). An integration problem never fails Flow's own health check.

alerts() tells owners and admins on the Integrations page what the sync cannot fix by itself: a refused API client, a read Seazona refused (a stopped lane), and reads that are late (stale lanes). None of it holds a host, a credential or patient data.

Replay files #

A replay file is JSON with a responses list. Each entry answers one request:

{
  "responses": [
    { "path": "invoices/", "query": { "lastModified": "*" }, "status": 200, "body": [] },
    { "path": "orders/ORD-1001", "status": 404 },
    { "path": "orders/ORD-1002", "sequence": [{ "status": 500 }, { "status": 200, "body": { "id": "ORD-1002" } }] },
    { "path": "orders/ORD-1003", "rawBody": "" },
    { "path": "orders/ORD-1004", "error": "timeout" }
  ]
}

• path is relative to the API root.
• query is optional. Each key it lists must match, and "*" matches any value.
• The first matching entry answers. A sequence answers in order, then repeats its last answer.
• A request that no entry matches fails with the kind replay_miss.

A replay file holds synthetic data only: no real lab, practice, dentist or patient (CONTRIBUTING.md).

Stage moves #

Seazona's API has no call that changes an order's status. So when a person moves a job to another Seazona stage on the Jobs board, Flow never calls Seazona. The move becomes a hand-off (stage-moves.js):

1. Flow records the move in seazona_stage_moves as waiting, and answers what to do: the order number, the new stage, and a link that opens the order in Seazona (SEAZONA_ORDER_URL, or the lab's Seazona order page).
2. The card shows in the new lane with "Waiting for Seazona" (listWork gives it pendingMove).
3. The person changes the status in Seazona. The next sync reads the order, and the move settles as done. Any new status settles it: Seazona has the last word.
4. After a day with no change, the move is expired. The card goes back to Seazona's stage. No alert follows: the person saw what to do in Seazona when they moved the card.
5. A person can take a waiting move back (cancelled).

Each person chooses whether the board asks before a stage move: "Ask before stage moves" under Your settings on the Seazona integration screen (seazona_person_settings, on by default). When Seazona adds an API call that changes a status, moveWork can make the change itself, and the hand-off stays only for a failed call (docs/JOB_BOARD_MOVES.md).

Tables #

The adapter owns its tables (issue #13). They are created only while the adapter is turned on, from its own migrations in server/integrations/seazona/migrations/, and are not part of the core schema. One installation talks to one Seazona account, so they are installation-wide.

To change them, edit server/integrations/seazona/schema.js and run:

npx drizzle-kit generate --config server/integrations/seazona/drizzle.config.js