@arcforgelabs/flow 0.0.0-stage → 2026.10.18-beta.1

package/server/core/invoices.js

@@ -0,0 +1,188 @@
+import { and, asc, desc, eq, sql } from 'drizzle-orm';
+import { contacts, invoiceLines, invoices, invoiceVersions, organisations, priceItems } from '../db/schema.js';
+import { FlowError, notFound } from './errors.js';
+import { invoiceTotals, lineTotals } from './money.js';
+
+// Invoices (accounts receivable). A draft can change. Issuing gives the
+// invoice its number and stores the document exactly as sent, as a new
+// version. To change an issued invoice, revise it back to a draft and issue
+// it again: the number stays and the earlier versions stay as they were.
+
+async function loadInvoice(tx, organisationId, invoiceId, { lock = false } = {}) {
+  let query = tx.select().from(invoices)
+    .where(and(eq(invoices.organisationId, organisationId), eq(invoices.id, invoiceId)));
+  if (lock) query = query.for('update');
+  const [row] = await query;
+  if (!row) throw notFound('invoice');
+  return row;
+}
+
+async function resolveLines(tx, organisationId, lines) {
+  if (!Array.isArray(lines)) throw new FlowError('invalid', 'lines must be a list');
+  const resolved = [];
+  for (const [index, line] of lines.entries()) {
+    let { description, unitAmountCents, taxCode } = line;
+    const quantity = line.quantity ?? 1;
+    if (line.priceItemId) {
+      const [item] = await tx.select().from(priceItems)
+        .where(and(eq(priceItems.organisationId, organisationId), eq(priceItems.id, line.priceItemId)));
+      if (!item) throw new FlowError('invalid', `line ${index + 1}: price item not found`);
+      description ??= item.name;
+      unitAmountCents ??= item.unitAmountCents;
+      taxCode ??= item.taxCode;
+    }
+    taxCode ??= 'GST';
+    if (!description?.trim()) throw new FlowError('invalid', `line ${index + 1}: description is required`);
+    let totals;
+    try {
+      totals = lineTotals({ quantity, unitAmountCents, taxCode });
+    } catch (error) {
+      throw new FlowError('invalid', `line ${index + 1}: ${error.message}`);
+    }
+    resolved.push({
+      position: index + 1,
+      priceItemId: line.priceItemId ?? null,
+      description: description.trim(),
+      quantity,
+      unitAmountCents,
+      taxCode,
+      ...totals,
+    });
+  }
+  return resolved;
+}
+
+async function writeLines(tx, invoice, lines) {
+  await tx.delete(invoiceLines).where(eq(invoiceLines.invoiceId, invoice.id));
+  if (lines.length) {
+    await tx.insert(invoiceLines).values(lines.map((line) => ({
+      ...line,
+      organisationId: invoice.organisationId,
+      invoiceId: invoice.id,
+    })));
+  }
+  const [row] = await tx.update(invoices)
+    .set({ ...invoiceTotals(lines), updatedAt: sql`now()` })
+    .where(eq(invoices.id, invoice.id))
+    .returning();
+  return row;
+}
+
+export async function createDraftInvoice(db, organisationId, { contactId, reference = null, dueDate = null, lines = [] }) {
+  return db.transaction(async (tx) => {
+    const [contact] = await tx.select().from(contacts)
+      .where(and(eq(contacts.organisationId, organisationId), eq(contacts.id, contactId)));
+    if (!contact) throw new FlowError('invalid', 'contact not found');
+    if (contact.kind !== 'customer') throw new FlowError('invalid', 'an invoice goes to a customer contact');
+    const resolved = await resolveLines(tx, organisationId, lines);
+    const [invoice] = await tx.insert(invoices)
+      .values({ organisationId, contactId, reference, dueDate })
+      .returning();
+    return writeLines(tx, invoice, resolved);
+  });
+}
+
+export async function updateDraftInvoice(db, organisationId, invoiceId, changes) {
+  return db.transaction(async (tx) => {
+    const invoice = await loadInvoice(tx, organisationId, invoiceId, { lock: true });
+    if (invoice.status !== 'draft') throw new FlowError('not_draft', 'only a draft invoice can change; revise it first');
+    const fields = {};
+    if ('reference' in changes) fields.reference = changes.reference;
+    if ('dueDate' in changes) fields.dueDate = changes.dueDate;
+    let row = invoice;
+    if (Object.keys(fields).length) {
+      [row] = await tx.update(invoices).set({ ...fields, updatedAt: sql`now()` })
+        .where(eq(invoices.id, invoice.id)).returning();
+    }
+    if ('lines' in changes) {
+      row = await writeLines(tx, row, await resolveLines(tx, organisationId, changes.lines));
+    }
+    return row;
+  });
+}
+
+export async function issueInvoice(db, organisationId, invoiceId, { issuedBy, issueDate }) {
+  if (!issuedBy) throw new FlowError('invalid', 'issuedBy is required');
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(issueDate ?? '')) throw new FlowError('invalid', 'issueDate must be YYYY-MM-DD');
+  return db.transaction(async (tx) => {
+    const invoice = await loadInvoice(tx, organisationId, invoiceId, { lock: true });
+    if (invoice.status !== 'draft') throw new FlowError('not_draft', 'only a draft invoice can be issued');
+    const lines = await tx.select().from(invoiceLines)
+      .where(eq(invoiceLines.invoiceId, invoice.id)).orderBy(asc(invoiceLines.position));
+    if (!lines.length) throw new FlowError('invalid', 'an invoice needs at least one line');
+
+    let number = invoice.number;
+    if (!number) {
+      const [org] = await tx.update(organisations)
+        .set({ nextInvoiceNumber: sql`${organisations.nextInvoiceNumber} + 1` })
+        .where(eq(organisations.id, organisationId))
+        .returning({ prefix: organisations.invoicePrefix, next: organisations.nextInvoiceNumber });
+      number = `${org.prefix}${String(org.next - 1).padStart(4, '0')}`;
+    }
+    const [contact] = await tx.select().from(contacts).where(eq(contacts.id, invoice.contactId));
+    const version = invoice.issuedVersion + 1;
+    const document = {
+      number,
+      version,
+      issueDate,
+      dueDate: invoice.dueDate,
+      reference: invoice.reference,
+      currency: invoice.currency,
+      contact: { id: contact.id, name: contact.name, email: contact.email },
+      lines: lines.map(({ position, description, quantity, unitAmountCents, taxCode, lineAmountCents, taxCents }) => (
+        { position, description, quantity, unitAmountCents, taxCode, lineAmountCents, taxCents }
+      )),
+      subtotalCents: invoice.subtotalCents,
+      taxCents: invoice.taxCents,
+      totalCents: invoice.totalCents,
+    };
+    await tx.insert(invoiceVersions).values({ organisationId, invoiceId, version, issuedBy, document });
+    const [row] = await tx.update(invoices)
+      .set({ status: 'issued', number, issuedVersion: version, issueDate, updatedAt: sql`now()` })
+      .where(eq(invoices.id, invoice.id))
+      .returning();
+    return row;
+  });
+}
+
+// Opens an issued invoice for change. The sent versions are not touched.
+export async function reviseInvoice(db, organisationId, invoiceId) {
+  return db.transaction(async (tx) => {
+    const invoice = await loadInvoice(tx, organisationId, invoiceId, { lock: true });
+    if (invoice.status !== 'issued') throw new FlowError('not_issued', 'only an issued invoice can be revised');
+    const [row] = await tx.update(invoices).set({ status: 'draft', updatedAt: sql`now()` })
+      .where(eq(invoices.id, invoice.id)).returning();
+    return row;
+  });
+}
+
+export async function voidInvoice(db, organisationId, invoiceId) {
+  return db.transaction(async (tx) => {
+    const invoice = await loadInvoice(tx, organisationId, invoiceId, { lock: true });
+    if (invoice.status === 'void') return invoice;
+    if (invoice.issuedVersion === 0) throw new FlowError('never_issued', 'delete a draft that was never issued; do not void it');
+    const [row] = await tx.update(invoices).set({ status: 'void', updatedAt: sql`now()` })
+      .where(eq(invoices.id, invoice.id)).returning();
+    return row;
+  });
+}
+
+export async function getInvoice(db, organisationId, invoiceId) {
+  const invoice = await loadInvoice(db, organisationId, invoiceId);
+  const lines = await db.select().from(invoiceLines)
+    .where(eq(invoiceLines.invoiceId, invoice.id)).orderBy(asc(invoiceLines.position));
+  return { ...invoice, lines };
+}
+
+export async function listInvoiceVersions(db, organisationId, invoiceId) {
+  await loadInvoice(db, organisationId, invoiceId);
+  return db.select().from(invoiceVersions)
+    .where(and(eq(invoiceVersions.organisationId, organisationId), eq(invoiceVersions.invoiceId, invoiceId)))
+    .orderBy(asc(invoiceVersions.version));
+}
+
+export async function listInvoices(db, organisationId, { status } = {}) {
+  const where = [eq(invoices.organisationId, organisationId)];
+  if (status) where.push(eq(invoices.status, status));
+  return db.select().from(invoices).where(and(...where)).orderBy(desc(invoices.createdAt));
+}

package/server/core/money.js

@@ -0,0 +1,38 @@
+// Money is integer cents. GST is 10% and is calculated and rounded per line,
+// half away from zero, on tax-exclusive amounts (the Xero default), so a
+// line's tax never changes when other lines are added.
+
+export const GST_RATE_BASIS_POINTS = 1000;
+
+function roundHalfAwayFromZero(numerator, denominator) {
+  const sign = Math.sign(numerator);
+  const abs = Math.abs(numerator);
+  return sign * Math.floor((abs * 2 + denominator) / (denominator * 2));
+}
+
+export function lineTotals({ quantity, unitAmountCents, taxCode }) {
+  if (!Number.isSafeInteger(quantity) || quantity <= 0) {
+    throw new TypeError('quantity must be a positive whole number');
+  }
+  if (!Number.isSafeInteger(unitAmountCents)) {
+    throw new TypeError('unitAmountCents must be whole cents');
+  }
+  if (taxCode !== 'GST' && taxCode !== 'GST_FREE') {
+    throw new TypeError(`unknown tax code: ${taxCode}`);
+  }
+  const lineAmountCents = quantity * unitAmountCents;
+  const taxCents = taxCode === 'GST'
+    ? roundHalfAwayFromZero(lineAmountCents * GST_RATE_BASIS_POINTS, 10_000)
+    : 0;
+  return { lineAmountCents, taxCents };
+}
+
+export function invoiceTotals(lines) {
+  let subtotalCents = 0;
+  let taxCents = 0;
+  for (const line of lines) {
+    subtotalCents += line.lineAmountCents;
+    taxCents += line.taxCents;
+  }
+  return { subtotalCents, taxCents, totalCents: subtotalCents + taxCents };
+}

package/server/db/index.js

@@ -0,0 +1,21 @@
+import { fileURLToPath } from 'node:url';
+import { drizzle } from 'drizzle-orm/node-postgres';
+import { migrate } from 'drizzle-orm/node-postgres/migrator';
+import pg from 'pg';
+import * as schema from './schema.js';
+
+const migrationsFolder = fileURLToPath(new URL('./migrations', import.meta.url));
+
+// Opens Flow's PostgreSQL database. The caller owns the pool: call close().
+export function openDatabase({ url = process.env.DATABASE_URL, max = 10 } = {}) {
+  if (!url) throw new Error('flow: DATABASE_URL is not set');
+  const pool = new pg.Pool({ connectionString: url, max });
+  const db = drizzle(pool, { schema });
+  return { db, pool, close: () => pool.end() };
+}
+
+export function migrateDatabase(db) {
+  return migrate(db, { migrationsFolder });
+}
+
+export { schema };

package/server/db/migrations/0000_core.sql

@@ -0,0 +1,93 @@
+CREATE TABLE "contacts" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"organisation_id" uuid NOT NULL,
+	"kind" text NOT NULL,
+	"name" text NOT NULL,
+	"email" text,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "contacts_org_id" UNIQUE("organisation_id","id"),
+	CONSTRAINT "contacts_org_kind_name" UNIQUE("organisation_id","kind","name"),
+	CONSTRAINT "contacts_kind_valid" CHECK ("contacts"."kind" in ('customer', 'supplier'))
+);
+--> statement-breakpoint
+CREATE TABLE "invoice_lines" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"organisation_id" uuid NOT NULL,
+	"invoice_id" uuid NOT NULL,
+	"position" integer NOT NULL,
+	"price_item_id" uuid,
+	"description" text NOT NULL,
+	"quantity" integer NOT NULL,
+	"unit_amount_cents" integer NOT NULL,
+	"tax_code" text NOT NULL,
+	"line_amount_cents" integer NOT NULL,
+	"tax_cents" integer NOT NULL,
+	CONSTRAINT "invoice_lines_invoice_position" UNIQUE("invoice_id","position"),
+	CONSTRAINT "invoice_lines_quantity_positive" CHECK ("invoice_lines"."quantity" > 0),
+	CONSTRAINT "invoice_lines_tax_code_valid" CHECK ("invoice_lines"."tax_code" in ('GST', 'GST_FREE'))
+);
+--> statement-breakpoint
+CREATE TABLE "invoice_versions" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"organisation_id" uuid NOT NULL,
+	"invoice_id" uuid NOT NULL,
+	"version" integer NOT NULL,
+	"issued_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"issued_by" text NOT NULL,
+	"document" jsonb NOT NULL,
+	CONSTRAINT "invoice_versions_invoice_version" UNIQUE("invoice_id","version"),
+	CONSTRAINT "invoice_versions_version_positive" CHECK ("invoice_versions"."version" > 0)
+);
+--> statement-breakpoint
+CREATE TABLE "invoices" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"organisation_id" uuid NOT NULL,
+	"contact_id" uuid NOT NULL,
+	"number" text,
+	"status" text DEFAULT 'draft' NOT NULL,
+	"issued_version" integer DEFAULT 0 NOT NULL,
+	"reference" text,
+	"currency" text DEFAULT 'AUD' NOT NULL,
+	"issue_date" date,
+	"due_date" date,
+	"subtotal_cents" integer DEFAULT 0 NOT NULL,
+	"tax_cents" integer DEFAULT 0 NOT NULL,
+	"total_cents" integer DEFAULT 0 NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "invoices_org_id" UNIQUE("organisation_id","id"),
+	CONSTRAINT "invoices_org_number" UNIQUE("organisation_id","number"),
+	CONSTRAINT "invoices_status_valid" CHECK ("invoices"."status" in ('draft', 'issued', 'void')),
+	CONSTRAINT "invoices_issued_has_number" CHECK ("invoices"."status" = 'draft' or "invoices"."number" is not null)
+);
+--> statement-breakpoint
+CREATE TABLE "organisations" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"name" text NOT NULL,
+	"invoice_prefix" text DEFAULT 'INV-' NOT NULL,
+	"next_invoice_number" integer DEFAULT 1 NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "organisations_next_invoice_number_positive" CHECK ("organisations"."next_invoice_number" > 0)
+);
+--> statement-breakpoint
+CREATE TABLE "price_items" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"organisation_id" uuid NOT NULL,
+	"code" text NOT NULL,
+	"name" text NOT NULL,
+	"unit_amount_cents" integer NOT NULL,
+	"tax_code" text DEFAULT 'GST' NOT NULL,
+	"archived_at" timestamp with time zone,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "price_items_org_id" UNIQUE("organisation_id","id"),
+	CONSTRAINT "price_items_org_code" UNIQUE("organisation_id","code"),
+	CONSTRAINT "price_items_tax_code_valid" CHECK ("price_items"."tax_code" in ('GST', 'GST_FREE'))
+);
+--> statement-breakpoint
+ALTER TABLE "contacts" ADD CONSTRAINT "contacts_organisation_id_organisations_id_fk" FOREIGN KEY ("organisation_id") REFERENCES "public"."organisations"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "invoice_lines" ADD CONSTRAINT "invoice_lines_invoice_same_org" FOREIGN KEY ("organisation_id","invoice_id") REFERENCES "public"."invoices"("organisation_id","id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "invoice_lines" ADD CONSTRAINT "invoice_lines_price_item_same_org" FOREIGN KEY ("organisation_id","price_item_id") REFERENCES "public"."price_items"("organisation_id","id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "invoice_versions" ADD CONSTRAINT "invoice_versions_invoice_same_org" FOREIGN KEY ("organisation_id","invoice_id") REFERENCES "public"."invoices"("organisation_id","id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "invoices" ADD CONSTRAINT "invoices_organisation_id_organisations_id_fk" FOREIGN KEY ("organisation_id") REFERENCES "public"."organisations"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "invoices" ADD CONSTRAINT "invoices_contact_same_org" FOREIGN KEY ("organisation_id","contact_id") REFERENCES "public"."contacts"("organisation_id","id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "price_items" ADD CONSTRAINT "price_items_organisation_id_organisations_id_fk" FOREIGN KEY ("organisation_id") REFERENCES "public"."organisations"("id") ON DELETE no action ON UPDATE no action;

package/server/db/migrations/0001_records_are_append_only.sql

@@ -0,0 +1,65 @@
+-- What a customer was sent is a record. These triggers hold that rule in the
+-- database, so no code path (or manual query) can quietly change it.
+
+CREATE FUNCTION flow_refuse_change() RETURNS trigger LANGUAGE plpgsql AS $$
+BEGIN
+  RAISE EXCEPTION 'flow: % on % is not allowed; issued records are append-only', TG_OP, TG_TABLE_NAME
+    USING ERRCODE = 'restrict_violation';
+END;
+$$;
+--> statement-breakpoint
+CREATE TRIGGER invoice_versions_append_only
+  BEFORE UPDATE OR DELETE ON invoice_versions
+  FOR EACH ROW EXECUTE FUNCTION flow_refuse_change();
+--> statement-breakpoint
+CREATE FUNCTION flow_invoice_lines_draft_only() RETURNS trigger LANGUAGE plpgsql AS $$
+DECLARE
+  parent_status text;
+BEGIN
+  SELECT status INTO parent_status FROM invoices
+    WHERE id = COALESCE(NEW.invoice_id, OLD.invoice_id);
+  -- A cascade from a deleted draft invoice finds no parent row.
+  IF parent_status IS NOT NULL AND parent_status <> 'draft' THEN
+    RAISE EXCEPTION 'flow: invoice lines change only while the invoice is a draft'
+      USING ERRCODE = 'restrict_violation';
+  END IF;
+  RETURN COALESCE(NEW, OLD);
+END;
+$$;
+--> statement-breakpoint
+CREATE TRIGGER invoice_lines_draft_only
+  BEFORE INSERT OR UPDATE OR DELETE ON invoice_lines
+  FOR EACH ROW EXECUTE FUNCTION flow_invoice_lines_draft_only();
+--> statement-breakpoint
+CREATE FUNCTION flow_invoice_rules() RETURNS trigger LANGUAGE plpgsql AS $$
+BEGIN
+  IF TG_OP = 'DELETE' THEN
+    IF OLD.issued_version > 0 THEN
+      RAISE EXCEPTION 'flow: an invoice that was issued cannot be deleted; void it'
+        USING ERRCODE = 'restrict_violation';
+    END IF;
+    RETURN OLD;
+  END IF;
+  IF NEW.organisation_id <> OLD.organisation_id THEN
+    RAISE EXCEPTION 'flow: an invoice cannot move to another organisation'
+      USING ERRCODE = 'restrict_violation';
+  END IF;
+  IF OLD.number IS NOT NULL AND NEW.number IS DISTINCT FROM OLD.number THEN
+    RAISE EXCEPTION 'flow: an invoice number never changes'
+      USING ERRCODE = 'restrict_violation';
+  END IF;
+  IF OLD.status = 'void' THEN
+    RAISE EXCEPTION 'flow: a void invoice cannot change'
+      USING ERRCODE = 'restrict_violation';
+  END IF;
+  IF NEW.issued_version < OLD.issued_version THEN
+    RAISE EXCEPTION 'flow: issued_version only goes up'
+      USING ERRCODE = 'restrict_violation';
+  END IF;
+  RETURN NEW;
+END;
+$$;
+--> statement-breakpoint
+CREATE TRIGGER invoices_rules
+  BEFORE UPDATE OR DELETE ON invoices
+  FOR EACH ROW EXECUTE FUNCTION flow_invoice_rules();

package/server/db/migrations/0002_people.sql

@@ -0,0 +1,19 @@
+CREATE TABLE "people" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"email" text NOT NULL,
+	"name" text,
+	"role" text NOT NULL,
+	"status" text DEFAULT 'active' NOT NULL,
+	"clerk_user_id" text,
+	"invited_by" uuid,
+	"linked_at" timestamp with time zone,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "people_email" UNIQUE("email"),
+	CONSTRAINT "people_clerk_user_id" UNIQUE("clerk_user_id"),
+	CONSTRAINT "people_email_lower" CHECK ("people"."email" = lower("people"."email")),
+	CONSTRAINT "people_role_valid" CHECK ("people"."role" in ('owner', 'admin', 'staff')),
+	CONSTRAINT "people_status_valid" CHECK ("people"."status" in ('active', 'pending', 'disabled'))
+);
+--> statement-breakpoint
+ALTER TABLE "people" ADD CONSTRAINT "people_invited_by_people_id_fk" FOREIGN KEY ("invited_by") REFERENCES "public"."people"("id") ON DELETE set null ON UPDATE no action;