@arcforgelabs/flow 2026.10.26 → 2026.10.29

package/server/core/sending.js

@@ -0,0 +1,283 @@
+import { randomUUID } from 'node:crypto';
+import { and, asc, desc, eq, inArray, sql } from 'drizzle-orm';
+import { invoiceLines, invoices } from '../db/schema.js';
+import { FlowError } from './errors.js';
+import { issueInvoice } from './invoices.js';
+import { soleOrganisation } from './pipeline.js';
+import { enqueueJob, runNextJob } from './queue.js';
+
+// Drafts, Problem, Ready and Send all ready (docs/INVOICE_SENDING.md).
+//
+// Flow checks every draft. It checks its own data first: the draft has lines,
+// a total above zero, and a price item (or, for a line such as a rush
+// charge, an account) on every line. When an accounting
+// system is connected, its own checks are added (for Xero: the customer
+// matches one Xero contact, every item is in Xero). A draft with a problem is
+// in Problem. A person marks a draft without one ready; any later change to
+// the draft sends it back to be checked again.
+//
+// Send all ready issues every ready draft (each gets its number) and, when an
+// accounting system is connected, queues it to go there. The send worker
+// sends the queue in the background on the job queue, so a long send never
+// holds a person's request and two Flow processes never send at once. An
+// issued invoice the accounting system refused has a problem until a person
+// sends it again.
+
+export const SEND_KIND = 'invoices.send';
+// Drafts one press issues; the rest wait for the next press.
+export const SEND_BATCH = 100;
+// Drafts checked for Ready and Problem, oldest first.
+export const CHECK_LIMIT = 500;
+const WORKER_BATCH = 25;
+const WORKER_EVERY_MS = 30 * 1000;
+const LEASE_MS = 15 * 60 * 1000;
+// Outcomes that mean the accounting system holds the invoice.
+const SENT = new Set(['created', 'reconciled', 'existing', 'already_in_xero']);
+
+const problem = (code, message) => ({ code, message });
+
+// Flow's own checks of one draft. `lines` are its invoice lines.
+export function draftProblems(invoice, lines) {
+  const problems = [];
+  if (!lines.length) problems.push(problem('no_lines', 'The invoice has no lines.'));
+  else if (invoice.totalCents <= 0) problems.push(problem('no_amount', 'The total is $0.00 or less.'));
+  for (const line of lines) {
+    if (!line.priceItemId && !line.accountCode) problems.push(problem('line_no_item', `Line ${line.position} has no price item.`));
+  }
+  return problems;
+}
+
+// Flow's checks, and the accounting system's, for some drafts. Answers
+// Map(id -> problems) holding only the drafts that have one.
+async function checkDrafts(db, organisationId, drafts, accounting) {
+  const ids = drafts.map((d) => d.id);
+  const problems = new Map();
+  if (!ids.length) return problems;
+  const lines = await db.select({ invoiceId: invoiceLines.invoiceId, position: invoiceLines.position, priceItemId: invoiceLines.priceItemId, accountCode: invoiceLines.accountCode })
+    .from(invoiceLines).where(inArray(invoiceLines.invoiceId, ids)).orderBy(asc(invoiceLines.position));
+  const linesOf = Map.groupBy(lines, (l) => l.invoiceId);
+  for (const draft of drafts) {
+    const found = draftProblems(draft, linesOf.get(draft.id) ?? []);
+    if (found.length) problems.set(draft.id, found);
+  }
+  if (accounting) {
+    const outside = await accounting.capabilities.checkDrafts({ organisationId, invoiceIds: ids });
+    for (const [id, found] of outside ?? []) {
+      if (found.length) problems.set(id, [...(problems.get(id) ?? []), ...found]);
+    }
+  }
+  return problems;
+}
+
+// The views of the Invoices page. `accounting` is the accounting adapter, or
+// null. Every draft is in one view: Problem (a check failed), Ready (a person
+// marked it ready) or To check (the rest). An issued invoice is Sending while
+// queued, and a Problem when the accounting system refused it. Answers
+// { toCheck: [ids], ready: [ids], problems: Map(id -> problems), sending: Set(ids) }.
+export async function invoiceViews(db, organisationId, { accounting = null } = {}) {
+  const drafts = await db.select({ id: invoices.id, totalCents: invoices.totalCents, readyAt: invoices.readyAt }).from(invoices)
+    .where(and(eq(invoices.organisationId, organisationId), eq(invoices.status, 'draft')))
+    .orderBy(asc(invoices.createdAt), asc(invoices.id))
+    .limit(CHECK_LIMIT);
+  const problems = await checkDrafts(db, organisationId, drafts, accounting);
+  const sending = new Set();
+  const issued = await db.select({ id: invoices.id, sendState: invoices.sendState, sendError: invoices.sendError }).from(invoices)
+    .where(and(eq(invoices.organisationId, organisationId), eq(invoices.status, 'issued'), inArray(invoices.sendState, ['queued', 'failed'])))
+    .orderBy(desc(invoices.sendUpdatedAt));
+  for (const row of issued) {
+    if (row.sendState === 'queued') sending.add(row.id);
+    else problems.set(row.id, [row.sendError ?? problem('send_failed', 'Sending failed.')]);
+  }
+  const clean = drafts.filter((d) => !problems.has(d.id));
+  return {
+    toCheck: clean.filter((d) => !d.readyAt).map((d) => d.id),
+    ready: clean.filter((d) => d.readyAt).map((d) => d.id),
+    problems,
+    sending,
+  };
+}
+
+// The view of one invoice, with its problems, for the invoice page.
+export async function invoiceView(db, organisationId, invoice, { accounting = null } = {}) {
+  if (invoice.status === 'void') return { view: null, problems: [] };
+  if (invoice.status === 'issued') {
+    if (invoice.sendState === 'queued') return { view: 'sending', problems: [] };
+    if (invoice.sendState === 'failed') return { view: 'problem', problems: [invoice.sendError ?? problem('send_failed', 'Sending failed.')] };
+    return { view: null, problems: [] };
+  }
+  const found = (await checkDrafts(db, organisationId, [invoice], accounting)).get(invoice.id) ?? [];
+  return { view: found.length ? 'problem' : invoice.readyAt ? 'ready' : 'to_check', problems: found };
+}
+
+// Mark ready: a person checked these drafts. A draft with a problem stays
+// where it is. Answers { marked, refused: [{ invoiceId, problems }] }.
+export async function markReady(db, organisationId, invoiceIds, { personId, accounting = null }) {
+  const drafts = await db.select({ id: invoices.id, totalCents: invoices.totalCents }).from(invoices)
+    .where(and(eq(invoices.organisationId, organisationId), eq(invoices.status, 'draft'), inArray(invoices.id, invoiceIds)));
+  if (drafts.length !== new Set(invoiceIds).size) throw new FlowError('not_draft', 'only a draft can be marked ready');
+  const problems = await checkDrafts(db, organisationId, drafts, accounting);
+  const good = drafts.filter((d) => !problems.has(d.id)).map((d) => d.id);
+  if (good.length) {
+    await db.update(invoices).set({ readyAt: sql`now()`, readyBy: personId ?? null })
+      .where(and(eq(invoices.organisationId, organisationId), eq(invoices.status, 'draft'), inArray(invoices.id, good)));
+  }
+  return { marked: good.length, refused: [...problems].map(([invoiceId, found]) => ({ invoiceId, problems: found })) };
+}
+
+// Back to drafts: the drafts need another look before they go.
+export async function markNotReady(db, organisationId, invoiceIds) {
+  const rows = await db.update(invoices).set({ readyAt: null, readyBy: null })
+    .where(and(eq(invoices.organisationId, organisationId), eq(invoices.status, 'draft'), inArray(invoices.id, invoiceIds)))
+    .returning({ id: invoices.id });
+  return { moved: rows.length };
+}
+
+// Before Flow issues anything: an accounting system that is on must be
+// connected and take writes, or the invoices would be issued and stuck.
+async function assertCanSend(accounting, organisationId) {
+  if (!accounting) return;
+  const status = await accounting.capabilities.sendStatus({ organisationId });
+  if (!status.connected) {
+    throw new FlowError('accounting_not_connected', `${accounting.name} is not connected. Connect it in Integrations, then send.`);
+  }
+  if (!status.writesAllowed) {
+    throw new FlowError('accounting_writes_off', `${accounting.name} does not take invoices from this installation yet (writes are off). Nothing was issued.`);
+  }
+}
+
+// Send all ready: issues each ready draft, then queues it for the accounting
+// system. Answers { issued, queued, remaining }.
+export async function sendAllReady(db, organisationId, { accounting = null, personId, issueDate }) {
+  await assertCanSend(accounting, organisationId);
+  const { ready } = await invoiceViews(db, organisationId, { accounting });
+  const batch = ready.slice(0, SEND_BATCH);
+  let issued = 0;
+  for (const invoiceId of batch) {
+    // Queued first: the worker sends only issued invoices, so a stop between
+    // the two steps leaves a queued draft, never an issued invoice nobody sends.
+    if (accounting) await queue(db, organisationId, [invoiceId], personId);
+    try {
+      await issueInvoice(db, organisationId, invoiceId, { issuedBy: `person:${personId}`, issueDate });
+    } catch (error) {
+      if (accounting) await unqueue(db, organisationId, invoiceId);
+      // Someone issued or changed it a moment ago: leave it to them.
+      if (error.code === 'not_draft' || error.code === 'not_found' || error.code === 'invalid') continue;
+      throw error;
+    }
+    issued += 1;
+  }
+  return { issued, queued: accounting ? issued : 0, remaining: ready.length - batch.length };
+}
+
+// Send again: issued invoices that failed go back on the queue. With no ids,
+// every failed one.
+export async function sendAgain(db, organisationId, { accounting = null, personId, invoiceIds = null }) {
+  await assertCanSend(accounting, organisationId);
+  if (!accounting) throw new FlowError('accounting_not_connected', 'No accounting system is on. Nothing to send.');
+  const where = [eq(invoices.organisationId, organisationId), eq(invoices.status, 'issued'), eq(invoices.sendState, 'failed')];
+  if (invoiceIds) where.push(inArray(invoices.id, invoiceIds));
+  const rows = await db.select({ id: invoices.id }).from(invoices).where(and(...where));
+  await queue(db, organisationId, rows.map((r) => r.id), personId);
+  return { queued: rows.length };
+}
+
+async function queue(db, organisationId, invoiceIds, personId) {
+  if (!invoiceIds.length) return;
+  await db.update(invoices)
+    .set({ sendState: 'queued', sendError: null, sendRequestedBy: personId ?? null, sendUpdatedAt: sql`now()` })
+    .where(and(eq(invoices.organisationId, organisationId), inArray(invoices.id, invoiceIds)));
+}
+
+function unqueue(db, organisationId, invoiceId) {
+  return db.update(invoices).set({ sendState: null, sendRequestedBy: null, sendUpdatedAt: sql`now()` })
+    .where(and(eq(invoices.organisationId, organisationId), eq(invoices.id, invoiceId), eq(invoices.status, 'draft')));
+}
+
+// One pass of the send worker: up to `limit` queued invoices, oldest first.
+export async function sendQueued(db, organisationId, { accounting, limit = WORKER_BATCH }) {
+  const rows = await db.select({ id: invoices.id, by: invoices.sendRequestedBy }).from(invoices)
+    .where(and(eq(invoices.organisationId, organisationId), eq(invoices.status, 'issued'), eq(invoices.sendState, 'queued')))
+    .orderBy(asc(invoices.sendUpdatedAt), asc(invoices.id))
+    .limit(limit);
+  const summary = { sent: 0, failed: 0, waiting: 0 };
+  for (const [by, group] of Map.groupBy(rows, (r) => r.by ?? null)) {
+    const { invoices: results } = await accounting.capabilities.pushInvoices({
+      organisationId, invoiceIds: group.map((r) => r.id), pushedBy: by,
+    });
+    for (const result of results) {
+      if (SENT.has(result.outcome)) {
+        await settle(db, organisationId, result.invoiceId, { sendState: 'sent', sendError: null });
+        summary.sent += 1;
+      } else if (result.outcome === 'not_tried' && result.error?.code === 'xero_rate_limited') {
+        // The day's or minute's calls ran out: it stays queued for a later pass.
+        summary.waiting += 1;
+      } else {
+        const error = result.error ?? { code: `send_${result.outcome}`, message: `Sending ended as ${result.outcome}.` };
+        await settle(db, organisationId, result.invoiceId, { sendState: 'failed', sendError: { code: error.code, message: error.message } });
+        summary.failed += 1;
+      }
+    }
+  }
+  return summary;
+}
+
+function settle(db, organisationId, invoiceId, fields) {
+  return db.update(invoices).set({ ...fields, sendUpdatedAt: sql`now()` })
+    .where(and(eq(invoices.organisationId, organisationId), eq(invoices.id, invoiceId), eq(invoices.sendState, 'queued')));
+}
+
+// The send worker: every 30 seconds, when invoices are queued, one pass on
+// the job queue.
+export function createSendWorker({ db, integrations, log = console, timers = { setTimeout, clearTimeout }, everyMs = WORKER_EVERY_MS }) {
+  const workerId = `send-${randomUUID()}`;
+  let timer = null;
+  let running = null;
+  let stopped = true;
+
+  function schedule() {
+    if (stopped) return;
+    timer = timers.setTimeout(tick, everyMs);
+    timer?.unref?.();
+  }
+
+  async function tick() {
+    timer = null;
+    if (stopped) return;
+    running = (async () => {
+      try {
+        const [accounting] = integrations.with('pushInvoices');
+        if (!accounting) return;
+        const organisationId = await soleOrganisation(db);
+        if (!organisationId) return;
+        const [waiting] = await db.select({ id: invoices.id }).from(invoices)
+          .where(and(eq(invoices.organisationId, organisationId), eq(invoices.sendState, 'queued'))).limit(1);
+        if (!waiting) return;
+        await enqueueJob(db, organisationId, { kind: SEND_KIND, dedupeKey: 'all' });
+        const ran = await runNextJob(db, {
+          workerId,
+          leaseMs: LEASE_MS,
+          handlers: { [SEND_KIND]: () => sendQueued(db, organisationId, { accounting }) },
+        });
+        if (ran) log.info?.(`[sending] ${ran.outcome}: ${JSON.stringify(ran.job.result ?? ran.job.lastError ?? {})}`);
+      } catch (error) {
+        log.error?.(`[sending] ${error?.code ?? 'error'}: ${error?.message ?? error}`);
+      }
+    })();
+    await running;
+    running = null;
+    schedule();
+  }
+
+  return {
+    start() {
+      stopped = false;
+      schedule();
+    },
+    async stop() {
+      stopped = true;
+      if (timer) timers.clearTimeout(timer);
+      timer = null;
+      await running;
+    },
+  };
+}

package/server/db/migrate-all.js

@@ -0,0 +1,26 @@
+import { migrateDatabase, openDatabase } from './index.js';
+import { adapters as shipped } from '../integrations/adapters.js';
+import { migrateAdapterSchema } from '../integrations/schema.js';
+
+// Brings a database up to this build: the core migrations, then the tables
+// of every adapter this build ships, whether or not it is on. On Replit the
+// workspace's database runs this before a publish (scripts/replit-deploy.sh
+// update-workspace), so it holds every table production can hold and
+// publishing never offers to drop one (docs/REPLIT.md).
+export async function migrateEverything(db, { adapters = shipped, log = () => {} } = {}) {
+  await migrateDatabase(db);
+  for (const adapter of adapters) {
+    if (!adapter.schema) continue;
+    await migrateAdapterSchema(db, adapter);
+    log(`${adapter.id} tables are up to date`);
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const handle = openDatabase({ max: 1 });
+  try {
+    await migrateEverything(handle.db, { log: (line) => console.log(`[deploy] ${line}`) });
+  } finally {
+    await handle.close();
+  }
+}

package/server/db/migrations/0010_invoicing_rules.sql

@@ -0,0 +1,72 @@
+CREATE TABLE IF NOT EXISTS "automations" (
+	"organisation_id" uuid NOT NULL,
+	"key" text NOT NULL,
+	"enabled" boolean NOT NULL,
+	"config" jsonb DEFAULT '{}'::jsonb NOT NULL,
+	"updated_by" uuid,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "automations_pk" PRIMARY KEY("organisation_id","key")
+);
+--> statement-breakpoint
+CREATE TABLE IF NOT EXISTS "customer_billing_settings" (
+	"organisation_id" uuid NOT NULL,
+	"contact_id" uuid NOT NULL,
+	"billable" boolean DEFAULT true NOT NULL,
+	"default_practitioner" text,
+	"auto_draft" boolean,
+	"send_mode" text,
+	"payment_terms_days" integer,
+	"updated_by" uuid,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "customer_billing_settings_pk" PRIMARY KEY("organisation_id","contact_id"),
+	CONSTRAINT "customer_billing_settings_send_mode_valid" CHECK ("customer_billing_settings"."send_mode" is null or "customer_billing_settings"."send_mode" in ('accounting_draft', 'approve_and_email')),
+	CONSTRAINT "customer_billing_settings_terms_valid" CHECK ("customer_billing_settings"."payment_terms_days" is null or "customer_billing_settings"."payment_terms_days" between 0 and 365)
+);
+--> statement-breakpoint
+CREATE TABLE IF NOT EXISTS "invoicing_settings" (
+	"organisation_id" uuid PRIMARY KEY NOT NULL,
+	"send_mode" text DEFAULT 'accounting_draft' NOT NULL,
+	"stale_days" integer DEFAULT 90 NOT NULL,
+	"payment_terms_days" integer DEFAULT 30 NOT NULL,
+	"require_practitioner" boolean DEFAULT false NOT NULL,
+	"rush_item_code" text,
+	"rush_percent" integer DEFAULT 20 NOT NULL,
+	"updated_by" uuid,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "invoicing_settings_send_mode_valid" CHECK (send_mode in ('accounting_draft', 'approve_and_email')),
+	CONSTRAINT "invoicing_settings_stale_days_valid" CHECK ("invoicing_settings"."stale_days" between 1 and 3650),
+	CONSTRAINT "invoicing_settings_terms_valid" CHECK ("invoicing_settings"."payment_terms_days" between 0 and 365),
+	CONSTRAINT "invoicing_settings_rush_valid" CHECK ("invoicing_settings"."rush_percent" between 0 and 100)
+);
+--> statement-breakpoint
+ALTER TABLE "billing_obligations" ADD COLUMN IF NOT EXISTS "source_status" text;--> statement-breakpoint
+ALTER TABLE "billing_obligations" ADD COLUMN IF NOT EXISTS "ready_at" timestamp with time zone;--> statement-breakpoint
+ALTER TABLE "billing_obligations" ADD COLUMN IF NOT EXISTS "ready_by" text;--> statement-breakpoint
+DO $flow_guard$ BEGIN
+	ALTER TABLE "automations" ADD CONSTRAINT "automations_organisation_id_organisations_id_fk" FOREIGN KEY ("organisation_id") REFERENCES "public"."organisations"("id") ON DELETE no action ON UPDATE no action;
+EXCEPTION WHEN duplicate_object OR duplicate_table OR invalid_table_definition THEN NULL;
+END $flow_guard$;--> statement-breakpoint
+DO $flow_guard$ BEGIN
+	ALTER TABLE "automations" ADD CONSTRAINT "automations_updated_by_people_id_fk" FOREIGN KEY ("updated_by") REFERENCES "public"."people"("id") ON DELETE set null ON UPDATE no action;
+EXCEPTION WHEN duplicate_object OR duplicate_table OR invalid_table_definition THEN NULL;
+END $flow_guard$;--> statement-breakpoint
+DO $flow_guard$ BEGIN
+	ALTER TABLE "customer_billing_settings" ADD CONSTRAINT "customer_billing_settings_organisation_id_organisations_id_fk" FOREIGN KEY ("organisation_id") REFERENCES "public"."organisations"("id") ON DELETE no action ON UPDATE no action;
+EXCEPTION WHEN duplicate_object OR duplicate_table OR invalid_table_definition THEN NULL;
+END $flow_guard$;--> statement-breakpoint
+DO $flow_guard$ BEGIN
+	ALTER TABLE "customer_billing_settings" ADD CONSTRAINT "customer_billing_settings_updated_by_people_id_fk" FOREIGN KEY ("updated_by") REFERENCES "public"."people"("id") ON DELETE set null ON UPDATE no action;
+EXCEPTION WHEN duplicate_object OR duplicate_table OR invalid_table_definition THEN NULL;
+END $flow_guard$;--> statement-breakpoint
+DO $flow_guard$ BEGIN
+	ALTER TABLE "customer_billing_settings" ADD CONSTRAINT "customer_billing_settings_contact_same_org" FOREIGN KEY ("organisation_id","contact_id") REFERENCES "public"."contacts"("organisation_id","id") ON DELETE no action ON UPDATE no action;
+EXCEPTION WHEN duplicate_object OR duplicate_table OR invalid_table_definition THEN NULL;
+END $flow_guard$;--> statement-breakpoint
+DO $flow_guard$ BEGIN
+	ALTER TABLE "invoicing_settings" ADD CONSTRAINT "invoicing_settings_organisation_id_organisations_id_fk" FOREIGN KEY ("organisation_id") REFERENCES "public"."organisations"("id") ON DELETE no action ON UPDATE no action;
+EXCEPTION WHEN duplicate_object OR duplicate_table OR invalid_table_definition THEN NULL;
+END $flow_guard$;--> statement-breakpoint
+DO $flow_guard$ BEGIN
+	ALTER TABLE "invoicing_settings" ADD CONSTRAINT "invoicing_settings_updated_by_people_id_fk" FOREIGN KEY ("updated_by") REFERENCES "public"."people"("id") ON DELETE set null ON UPDATE no action;
+EXCEPTION WHEN duplicate_object OR duplicate_table OR invalid_table_definition THEN NULL;
+END $flow_guard$;

package/server/db/migrations/0011_invoice_rules.sql

@@ -0,0 +1,27 @@
+CREATE TABLE IF NOT EXISTS "invoice_rules" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"organisation_id" uuid NOT NULL,
+	"name" text NOT NULL,
+	"position" integer NOT NULL,
+	"enabled" boolean DEFAULT true NOT NULL,
+	"trigger" text DEFAULT 'job_ready' NOT NULL,
+	"conditions" jsonb DEFAULT '[]'::jsonb NOT NULL,
+	"action" jsonb NOT NULL,
+	"starter_key" text,
+	"updated_by" uuid,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "invoice_rules_trigger_valid" CHECK ("invoice_rules"."trigger" in ('job_ready')),
+	CONSTRAINT "invoice_rules_name_valid" CHECK (length("invoice_rules"."name") between 1 and 120)
+);
+--> statement-breakpoint
+ALTER TABLE "invoicing_settings" ADD COLUMN IF NOT EXISTS "rules_seeded" boolean DEFAULT false NOT NULL;--> statement-breakpoint
+DO $flow_guard$ BEGIN
+	ALTER TABLE "invoice_rules" ADD CONSTRAINT "invoice_rules_organisation_id_organisations_id_fk" FOREIGN KEY ("organisation_id") REFERENCES "public"."organisations"("id") ON DELETE no action ON UPDATE no action;
+EXCEPTION WHEN duplicate_object OR duplicate_table OR invalid_table_definition THEN NULL;
+END $flow_guard$;--> statement-breakpoint
+DO $flow_guard$ BEGIN
+	ALTER TABLE "invoice_rules" ADD CONSTRAINT "invoice_rules_updated_by_people_id_fk" FOREIGN KEY ("updated_by") REFERENCES "public"."people"("id") ON DELETE set null ON UPDATE no action;
+EXCEPTION WHEN duplicate_object OR duplicate_table OR invalid_table_definition THEN NULL;
+END $flow_guard$;--> statement-breakpoint
+CREATE UNIQUE INDEX IF NOT EXISTS "invoice_rules_starter_key" ON "invoice_rules" USING btree ("organisation_id","starter_key");

package/server/db/migrations/0012_invoice_sending.sql

@@ -0,0 +1,18 @@
+ALTER TABLE "invoices" ADD COLUMN IF NOT EXISTS "ready_at" timestamp with time zone;--> statement-breakpoint
+ALTER TABLE "invoices" ADD COLUMN IF NOT EXISTS "ready_by" uuid;--> statement-breakpoint
+ALTER TABLE "invoices" ADD COLUMN IF NOT EXISTS "send_state" text;--> statement-breakpoint
+ALTER TABLE "invoices" ADD COLUMN IF NOT EXISTS "send_error" jsonb;--> statement-breakpoint
+ALTER TABLE "invoices" ADD COLUMN IF NOT EXISTS "send_requested_by" uuid;--> statement-breakpoint
+ALTER TABLE "invoices" ADD COLUMN IF NOT EXISTS "send_updated_at" timestamp with time zone;--> statement-breakpoint
+DO $flow_guard$ BEGIN
+	ALTER TABLE "invoices" ADD CONSTRAINT "invoices_ready_by_people_id_fk" FOREIGN KEY ("ready_by") REFERENCES "public"."people"("id") ON DELETE set null ON UPDATE no action;
+EXCEPTION WHEN duplicate_object OR duplicate_table OR invalid_table_definition THEN NULL;
+END $flow_guard$;--> statement-breakpoint
+DO $flow_guard$ BEGIN
+	ALTER TABLE "invoices" ADD CONSTRAINT "invoices_send_requested_by_people_id_fk" FOREIGN KEY ("send_requested_by") REFERENCES "public"."people"("id") ON DELETE set null ON UPDATE no action;
+EXCEPTION WHEN duplicate_object OR duplicate_table OR invalid_table_definition THEN NULL;
+END $flow_guard$;--> statement-breakpoint
+DO $flow_guard$ BEGIN
+	ALTER TABLE "invoices" ADD CONSTRAINT "invoices_send_state_valid" CHECK ("invoices"."send_state" is null or "invoices"."send_state" in ('queued', 'sent', 'failed'));
+EXCEPTION WHEN duplicate_object OR duplicate_table OR invalid_table_definition THEN NULL;
+END $flow_guard$;

package/server/db/migrations/0013_line_mappings.sql

@@ -0,0 +1,35 @@
+CREATE TABLE IF NOT EXISTS "line_mappings" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"organisation_id" uuid NOT NULL,
+	"kind" text NOT NULL,
+	"match" text DEFAULT 'exact' NOT NULL,
+	"label" text NOT NULL,
+	"unit_amount_cents" integer,
+	"item_code" text,
+	"account_code" text,
+	"tax_code" text,
+	"description" text,
+	"enabled" boolean DEFAULT true NOT NULL,
+	"origin" text DEFAULT 'person' NOT NULL,
+	"updated_by" uuid,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "line_mappings_kind_valid" CHECK ("line_mappings"."kind" in ('alias', 'price_alias', 'saved', 'account')),
+	CONSTRAINT "line_mappings_match_valid" CHECK ("line_mappings"."match" in ('exact', 'starts_with')),
+	CONSTRAINT "line_mappings_tax_code_valid" CHECK ("line_mappings"."tax_code" is null or "line_mappings"."tax_code" in ('GST', 'GST_FREE')),
+	CONSTRAINT "line_mappings_target" CHECK (("line_mappings"."kind" = 'account' and "line_mappings"."account_code" is not null) or ("line_mappings"."kind" <> 'account' and "line_mappings"."item_code" is not null)),
+	CONSTRAINT "line_mappings_price" CHECK ("line_mappings"."kind" not in ('price_alias', 'saved') or "line_mappings"."unit_amount_cents" is not null),
+	CONSTRAINT "line_mappings_label_valid" CHECK (length("line_mappings"."label") between 1 and 200)
+);
+--> statement-breakpoint
+ALTER TABLE "invoice_lines" ADD COLUMN IF NOT EXISTS "account_code" text;--> statement-breakpoint
+ALTER TABLE "price_items" ADD COLUMN IF NOT EXISTS "description" text;--> statement-breakpoint
+DO $flow_guard$ BEGIN
+	ALTER TABLE "line_mappings" ADD CONSTRAINT "line_mappings_organisation_id_organisations_id_fk" FOREIGN KEY ("organisation_id") REFERENCES "public"."organisations"("id") ON DELETE no action ON UPDATE no action;
+EXCEPTION WHEN duplicate_object OR duplicate_table OR invalid_table_definition THEN NULL;
+END $flow_guard$;--> statement-breakpoint
+DO $flow_guard$ BEGIN
+	ALTER TABLE "line_mappings" ADD CONSTRAINT "line_mappings_updated_by_people_id_fk" FOREIGN KEY ("updated_by") REFERENCES "public"."people"("id") ON DELETE set null ON UPDATE no action;
+EXCEPTION WHEN duplicate_object OR duplicate_table OR invalid_table_definition THEN NULL;
+END $flow_guard$;--> statement-breakpoint
+CREATE UNIQUE INDEX IF NOT EXISTS "line_mappings_unique" ON "line_mappings" USING btree ("organisation_id","kind","match","label",coalesce("unit_amount_cents", -1));