@arcforgelabs/flow 2026.10.20-beta.1 → 2026.10.21

package/SECURITY.md

@@ -31,6 +31,10 @@ paste a credential, in full or in part.
 - **Integrations.** Seazona, Xero and every later adapter reach the core only
   through the integration port. Their credentials are stored per
   organisation, encrypted, and are write-only in Settings.
+- **Records and files.** Every record is in the installation's PostgreSQL.
+  Files reach the core only through the object storage port; PostgreSQL
+  holds each file's key, owner, size and hash, and the hash is checked on
+  read. Download links are signed.
 - **Issued documents are records.** An invoice a customer has been sent is
   never changed in place; a change produces a new version.
 
@@ -53,6 +57,8 @@ paste a credential, in full or in part.
 - Session cookies are `Secure`, `HttpOnly` and `SameSite`.
 - Flow stores no clinical notes, images or scans, and keeps a patient
   reference only where an invoice must print one.
+- Object keys and file names carry a case number at most, never a patient
+  name or other patient data.
 - CI runs gitleaks on every push and pull request
   (`.github/workflows/secret-scan.yml`).
 

package/VISION.md

@@ -47,6 +47,15 @@ sensitive. Flow keeps the case number and the practice. It keeps a patient
 reference only when a practice needs one printed on its invoice, and it keeps
 no clinical notes or images.
 
+### Why does Flow keep its records in PostgreSQL only?
+
+One database is less to run, back up and upgrade. Every record lives in
+PostgreSQL, with `jsonb` for evidence and documents. Files (PDFs, payment
+proof, exports) go through one object storage port, and PostgreSQL keeps only
+each file's key, owner, size, type and hash. A need that seems to call for
+another kind of database is raised as a decision first. The goal is an
+installation that needs little maintenance (`docs/DATA_MODEL.md`, "Storage").
+
 ### Why does each lab get its own installation?
 
 Labs' customers, prices and credentials must never meet. Each installation has

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@arcforgelabs/flow",
-  "version": "2026.10.20-beta.1",
+  "version": "2026.10.21",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@arcforgelabs/flow",
-      "version": "2026.10.20-beta.1",
+      "version": "2026.10.21",
       "license": "MIT",
       "dependencies": {
         "@clerk/backend": "3.23.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcforgelabs/flow",
-  "version": "2026.10.20-beta.1",
+  "version": "2026.10.21",
   "description": "Invoicing, bill entry and a financial dashboard for labs, with Seazona and Xero integrations.",
   "license": "MIT",
   "repository": {

package/server/import/at-start.js

@@ -0,0 +1,52 @@
+import { sql } from 'drizzle-orm';
+import { organisations } from '../db/schema.js';
+import { applyImport, planImport, readEarlierFlow, summarisePlan } from './earlier-flow.js';
+
+// The import from the earlier codebase, run once by the server itself. On a
+// host with no shell next to the app (a published Replit app) the operator
+// moves the earlier tables into their own schema, then sets
+// FLOW_IMPORT_EARLIER_SCHEMA and FLOW_IMPORT_ORGANISATION. While the database
+// has no organisation, the next start reads that schema in a read-only
+// transaction and writes the records (server/import/earlier-flow.js). Once an
+// organisation exists, it does nothing.
+
+const SCHEMA_NAME = /^[a-z_][a-z0-9_]{0,62}$/;
+
+export function resolveImportAtStart(env = process.env) {
+  const schema = (env.FLOW_IMPORT_EARLIER_SCHEMA ?? '').trim();
+  if (!schema) return null;
+  if (!SCHEMA_NAME.test(schema)) throw new Error('FLOW_IMPORT_EARLIER_SCHEMA must be a plain lower-case schema name, e.g. earlier');
+  const organisationName = (env.FLOW_IMPORT_ORGANISATION ?? '').trim();
+  if (!organisationName) throw new Error('FLOW_IMPORT_ORGANISATION (the lab\'s name) is required with FLOW_IMPORT_EARLIER_SCHEMA');
+  return { schema, organisationName };
+}
+
+// Returns the import's counts, or null when there was nothing to do.
+export async function importEarlierAtStart({ db, pool, settings, log = console }) {
+  if (!settings) return null;
+  const [{ count }] = (await db.execute(sql`select count(*)::int as count from ${organisations}`)).rows;
+  if (count > 0) {
+    log.info?.('[import] skipped: this database already has an organisation (unset FLOW_IMPORT_EARLIER_SCHEMA)');
+    return null;
+  }
+
+  let plan;
+  const client = await pool.connect();
+  try {
+    await client.query('BEGIN TRANSACTION READ ONLY');
+    // The schema name was checked against SCHEMA_NAME, so it is safe to quote.
+    await client.query(`SET LOCAL search_path TO "${settings.schema}"`);
+    plan = planImport(await readEarlierFlow(client));
+    await client.query('COMMIT');
+  } catch (error) {
+    await client.query('ROLLBACK').catch(() => {});
+    throw new Error(`could not read schema "${settings.schema}": ${error.message}`);
+  } finally {
+    client.release();
+  }
+
+  log.info?.(`[import] plan from schema "${settings.schema}": ${JSON.stringify(summarisePlan(plan))}`);
+  const result = await applyImport(db, plan, { organisationName: settings.organisationName });
+  log.info?.(`[import] imported: ${JSON.stringify(result.counts)}`);
+  return result.counts;
+}

package/server/import/earlier-flow.js

@@ -45,6 +45,12 @@ function parseJson(text) {
   }
 }
 
+// The earlier codebase stored some accounting payloads as the API sent them
+// (`UnitPrice`) and some as its SDK returned them (`unitPrice`).
+function field(object, name) {
+  return object[name] ?? object[name[0].toLowerCase() + name.slice(1)];
+}
+
 function isTrue(value) {
   return value === true || value === 1 || value === '1' || value === 'true';
 }
@@ -82,8 +88,8 @@ function planContacts(rows, skipped) {
       skipped.push({ table: 'contacts', key, reason: 'unreadable_raw_json' });
       continue;
     }
-    const customer = isTrue(raw.IsCustomer);
-    const supplier = isTrue(raw.IsSupplier);
+    const customer = isTrue(field(raw, 'IsCustomer'));
+    const supplier = isTrue(field(raw, 'IsSupplier'));
     // A contact the accounting system has never billed or paid is most often
     // a new customer, so it comes across as one.
     const kinds = supplier && !customer ? ['supplier'] : supplier ? ['customer', 'supplier'] : ['customer'];
@@ -120,12 +126,12 @@ function planPriceItems(rows, skipped, defaulted) {
       skipped.push({ table: 'price_items', key, reason: 'unreadable_sales_details' });
       continue;
     }
-    const unitAmountCents = toCents(sales.UnitPrice);
+    const unitAmountCents = toCents(field(sales, 'UnitPrice'));
     if (unitAmountCents === null) {
       skipped.push({ table: 'price_items', key, reason: 'no_sales_price' });
       continue;
     }
-    const taxType = String(sales.TaxType ?? '').trim().toUpperCase();
+    const taxType = String(field(sales, 'TaxType') ?? '').trim().toUpperCase();
     if (!taxType) defaulted.push({ table: 'price_items', key, reason: 'no_tax_type_used_gst' });
     const taxCode = !taxType || GST_TAX_TYPES.has(taxType) ? 'GST' : 'GST_FREE';
     planned.push({ sourceKey: key, code, name, unitAmountCents, taxCode });

package/server/index.js

@@ -5,6 +5,7 @@ import { seedFirstOwner } from './auth/people.js';
 import { createPersonAuth } from './auth/session.js';
 import { resolveSignInSettings } from './auth/settings.js';
 import { migrateDatabase, openDatabase } from './db/index.js';
+import { importEarlierAtStart, resolveImportAtStart } from './import/at-start.js';
 import { createIntegrations } from './integrations/index.js';
 import { resolveDefaultFamily } from './theme/themes.js';
 import { createUpdateChecker, UPDATE_CHECK_INTERVAL_MS } from './update-check.js';
@@ -34,11 +35,26 @@ try {
   process.exit(1);
 }
 
+let importAtStart;
+try {
+  importAtStart = resolveImportAtStart();
+} catch (error) {
+  console.error(`[import] ${error.message}`);
+  process.exit(1);
+}
+
 // Flow's records live in PostgreSQL. Migrations run before the server accepts
 // requests, so a release never serves an older schema. Then each enabled
 // integration's own tables, and no others (docs/INTEGRATIONS.md).
 const database = openDatabase();
 await migrateDatabase(database.db);
+// A failed import stops the start, so Flow never opens with half its records.
+try {
+  await importEarlierAtStart({ db: database.db, pool: database.pool, settings: importAtStart });
+} catch (error) {
+  console.error(`[import] ${error.message}`);
+  process.exit(1);
+}
 await integrations.start(database.db);
 const integrationsOn = integrations.list().filter((a) => a.enabled).map((a) => a.id);
 console.log(`[integrations] on: ${integrationsOn.join(', ') || 'none'} (FLOW_INTEGRATIONS)`);