@diy-accounting-uk/diya-gl 1.2.43 → 1.2.44

package/README.md

@@ -71,6 +71,78 @@ Each subcommand is also its own command, if you only want one on your `PATH`:
   `extract_book`, `report`, `edit_lines`, `save_workbook`. Point an MCP client at
   `diya-gl-mcp` (or `diya-gl mcp`) with no arguments.
 
+## API
+
+The package root exports three functions that turn a book into the figures HMRC's MTD APIs
+take. Each takes the parsed book, its lines and a parameters object, and returns a promise.
+Nothing is sent anywhere: the answer is the request body to send, plus what fed it.
+
+Load a book first:
+
+```js
+import { readFileSync } from "node:fs";
+import { parse } from "smol-toml";
+
+function loadBook(dir) {
+  const book = parse(readFileSync(`${dir}/book.toml`, "utf8"));
+  const lines = readFileSync(`${dir}/lines.jsonl`, "utf8")
+    .split("\n")
+    .filter(Boolean)
+    .map((line) => JSON.parse(line));
+  return { book, lines };
+}
+```
+
+### `deriveVatReturn(book, lines, { periodEnd, periodStart?, periodKey? })`
+
+The nine VAT return boxes for the three-month period ending `periodEnd` (YYYY-MM-DD), from a
+Limited Company book that declares `diya-gl:vatRegistered = true`. `periodStart`, when given,
+must open that quarter; `periodKey` is echoed back. The answer carries `boxes` (box1 to box9),
+`hmrc` (the same figures under HMRC's field names, boxes 1 to 5 to the penny and 6 to 9 in
+whole pounds), `months`, `dueDate`, `scheme`, and `lines`: the journal lines behind boxes 1, 4,
+6 and 7, each with what it contributes. A book whose lines do not reconcile with its VAT
+interface is refused.
+
+```js
+import { deriveVatReturn } from "@diy-accounting-uk/diya-gl";
+
+const { book, lines } = loadBook("my-company-book");
+const answer = await deriveVatReturn(book, lines, { periodStart: "2025-07-01", periodEnd: "2025-09-30" });
+console.log(answer.hmrc); // { vatDueSales, vatDueAcquisitions, totalVatDue, ..., totalAcquisitionsExVAT }
+```
+
+### `deriveItsaQuarterlyUpdate(book, lines, { periodEndDate?, quarterlyPeriodType?, taxYear? })`
+
+One period of HMRC's Self Employment Business API from a Self Employed book. In 2023-24 and
+2024-25 each period carries its own figures; from 2025-26 each carries the running total from
+6 April. `periodEndDate` picks the period among the year's four; without it every period is
+answered. `quarterlyPeriodType` is `standard` (6 April quarters, the default) or `calendar`.
+`taxYear` (as `2025-26`) overrides the year the book's dates imply. Each period lists the fields
+the book cannot source under `omitted`; those are left out of the body, never sent as zero.
+
+```js
+import { deriveItsaQuarterlyUpdate } from "@diy-accounting-uk/diya-gl";
+
+const { book, lines } = loadBook("my-self-employed-book");
+const answer = await deriveItsaQuarterlyUpdate(book, lines, { periodEndDate: "2025-10-05" });
+const [period] = answer.periods; // { periodDates, periodIncome, periodExpenses, ..., omitted, covers }
+```
+
+### `deriveItsaAnnualSubmission(book, lines, { taxYear? })`
+
+The year's allowances and adjustments for the same API's annual submission, from a Self
+Employed book, restricted to the fields HMRC accepts for that tax year. `taxYear` (as
+`2025-26`) overrides the year the book's dates imply. The answer carries `allowances`,
+`adjustments`, `omitted` and `warnings`.
+
+```js
+import { deriveItsaAnnualSubmission } from "@diy-accounting-uk/diya-gl";
+
+const { book, lines } = loadBook("my-self-employed-book");
+const answer = await deriveItsaAnnualSubmission(book, lines, { taxYear: "2025-26" });
+console.log(answer.allowances.annualInvestmentAllowance);
+```
+
 ## The format
 
 A diya-gl book's fields are drawn from the XBRL Global Ledger Taxonomy Framework 2015 and

package/dist/app/data/releases.json

@@ -1351,6 +1351,32 @@
           "scorecard": "101605 passed, 0 warnings, 0 failed"
         }
       }
+    },
+    {
+      "tag": "diya-gl-v1.2.43",
+      "date": "2026-10-03",
+      "formatVersion": "diya-gl/1",
+      "engineVersion": "1.2.40+57de8f55b",
+      "taxDataHash": "89424bd36c0d",
+      "reconciledCommit": "54e8731a91279975e61b1a232fbb67fda89515f0",
+      "templates": {
+        "bst": {
+          "hash": "0d003e10e00c",
+          "scorecard": "812 passed, 0 warnings, 0 failed"
+        },
+        "taxi": {
+          "hash": "1ff69654d64d",
+          "scorecard": "700 passed, 0 warnings, 0 failed"
+        },
+        "se": {
+          "hash": "064605ae76ed",
+          "scorecard": "8014 passed, 0 warnings, 0 failed"
+        },
+        "ltd": {
+          "hash": "5bb7be9b6d97",
+          "scorecard": "101605 passed, 0 warnings, 0 failed"
+        }
+      }
     }
   ]
 }

package/dist/app/lib/calculators/ltd.js

@@ -60,7 +60,7 @@ import { attributionWriter, entriesOf, entryOf, fieldEntriesOf, unionOf } from "
 
 const SHORT_MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
 const MONTH_COLS = ["C", "D", "E", "F", "G", "H", "I", "J", "K", "L", "M", "N"];
-const VAT_RATE = 0.2;
+export const VAT_RATE = 0.2;
 
 // Sales and Purchases analysis columns, code letter by column letter, in the
 // order row 5 of each month tab tests them. Column AK of a Purchases month

package/dist/app/lib/calculators/se-derivations.js

@@ -26,7 +26,7 @@ let cachedMapping = null;
 
 // Resolved on first use, not at import: the engine bundle loads in the browser,
 // where import.meta.url is an http URL and fileURLToPath throws.
-function loadMapping() {
+export function loadMapping() {
   if (!cachedMapping) {
     const here = dirname(fileURLToPath(import.meta.url));
     const mappingPath = resolve(here, "..", "..", "data", "hmrc", "sa103-mtd-mapping.json");
@@ -50,7 +50,7 @@ function boxEntry(boxes, boxNumber) {
 // first is the one this template's cell actually answers -- section 8 of the
 // design records which, box by box -- so a caller asking for "the field this
 // box answers" gets that one unless told to reach past it.
-function fieldsOf(entry) {
+export function fieldsOf(entry) {
   return entry.field.split("|").map((field) => field.trim());
 }
 
@@ -63,11 +63,15 @@ function primaryField(boxes, boxNumber) {
 // rather than the object this call meant to build. Every path here comes from
 // sa103-mtd-mapping.json's own "field" column, so a segment like this is a
 // defect in that mapping file and must fail loudly rather than land quietly
-// on some other object. The check sits inside the walk, as literal
-// comparisons, and each intermediate node is only reused when it is the
-// object's own property: the shape static analysis recognises as guarded.
+// on some other object. The whole path is refused before anything is
+// written, so a refused path leaves the target untouched. The check is
+// repeated inside the walk, as literal comparisons, and each intermediate
+// node is only reused when it is the object's own property: the shape static
+// analysis recognises as guarded.
 export function setPath(target, path, value) {
   const parts = path.split(".");
+  const refused = parts.find((part) => part === "__proto__" || part === "constructor" || part === "prototype");
+  if (refused !== undefined) throw new Error(`setPath: "${refused}" is not a field name, in path "${path}"`);
   let node = target;
   for (let i = 0; i < parts.length; i++) {
     const part = parts[i];
@@ -491,7 +495,7 @@ const NO_SOURCE_ANNUAL_BOXES = [
 // 2026-27 additions, gated behind HMRC test flags) is not treated as a
 // live field here -- neither has a cell in this template regardless, so
 // the payload does not change, only whether the gap is worth warning about.
-function annualFieldsUnavailableForYear(taxYear) {
+export function annualFieldsUnavailableForYear(taxYear) {
   const years = loadMapping().api.years;
   const order = Object.keys(years);
   const index = order.indexOf(taxYear);

package/dist/app/lib/derivations/index.js

@@ -0,0 +1,8 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2006-2026 DIY Accounting Limited
+//
+// index.js — the diya-gl package's public module: the filing figures a book
+// answers, imported as `@diy-accounting-uk/diya-gl`.
+
+export { deriveVatReturn } from "./vat-return.js";
+export { deriveItsaQuarterlyUpdate, deriveItsaAnnualSubmission } from "./itsa.js";

package/dist/app/lib/derivations/itsa.js

@@ -0,0 +1,236 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2006-2026 DIY Accounting Limited
+//
+// itsa.js — the two ITSA answers HMRC's Self Employment Business API takes
+// from a self-employed (se) book. deriveItsaQuarterlyUpdate answers one
+// period: the period's own figures in a tax year filed as dated period
+// summaries, a running total from 6 April in a year filed as cumulative
+// period summaries. deriveItsaAnnualSubmission answers the year's allowances
+// and adjustments. Both call calculators/se-derivations.js and add no
+// arithmetic beyond summing quarters.
+//
+// The field set HMRC accepts changes by tax year (sa103-mtd-mapping.json's
+// api.years: allowances gone from 2025-26, an adjustment gone from 2026-27,
+// two test-only additions), and every answer here is filtered to the year's
+// live fields. A field the template cannot source is omitted, never sent as
+// a zero.
+
+import {
+  annualFieldsUnavailableForYear,
+  buildSelfEmploymentAnnualSubmission,
+  buildSelfEmploymentQuarterlyUpdates,
+  fieldsOf,
+  loadMapping,
+  setPath,
+} from "../calculators/se-derivations.js";
+import { loadTaxDataForBook, productOf } from "../product-workbook.js";
+
+export const QUARTERLY_PERIOD_TYPES = ["standard", "calendar"];
+
+const TAX_YEAR_LABEL = /^(\d{4})-(\d{2})$/;
+
+function requireSelfEmployedBook(book, lines, caller) {
+  if (!book || !lines) throw new Error(`${caller} requires a book and its lines`);
+  const product = productOf(book);
+  if (product !== "se") {
+    throw new Error(`The book is a "${product}" book; the ITSA derivations read a self-employed (se) book`);
+  }
+}
+
+// "2025-26" names the package's se-2025-2026.toml; a label the mapping's
+// api.years does not carry is refused before any figure is derived, because
+// the field set for that year is unknown.
+function taxYearFileNameFor(label) {
+  const match = TAX_YEAR_LABEL.exec(label ?? "");
+  if (!match) throw new Error(`taxYear must look like 2025-26, not "${label}"`);
+  const start = Number(match[1]);
+  const end = start + 1;
+  if (String(end).slice(-2) !== match[2]) throw new Error(`taxYear "${label}" does not name two consecutive years`);
+  return `se-${start}-${end}`;
+}
+
+async function taxDataFor(book, taxYear) {
+  const options = taxYear ? { taxYearName: taxYearFileNameFor(taxYear) } : {};
+  const taxData = await loadTaxDataForBook(book, options);
+  const label = taxData?.tax_year?.label;
+  if (!label) throw new Error("the tax year file declares no tax_year.label");
+  if (!loadMapping().api.years[label]) {
+    throw new Error(`sa103-mtd-mapping.json's api.years carries no entry for tax year "${label}"`);
+  }
+  return taxData;
+}
+
+function boxesOnRoute(route) {
+  return loadMapping().boxes.filter((entry) => entry.form === "SA103F" && entry.route === route && entry.field);
+}
+
+/**
+ * The quarterly field slots HMRC's period summary carries, from the mapping:
+ * every quarterly-route field (a box shared by two fields counts both) plus
+ * the consolidated-expenses election the box 31 caveat names. The mapping
+ * varies none of these by tax year; the year decides the shape, not the set.
+ * @returns {string[]}
+ */
+export function quarterlyFieldSlots() {
+  const slots = new Set();
+  for (const entry of boxesOnRoute("quarterly")) for (const field of fieldsOf(entry)) slots.add(field);
+  slots.add("periodExpenses.consolidatedExpenses");
+  return [...slots].sort();
+}
+
+/**
+ * The annual field slots HMRC's schema accepts for one tax year: every
+ * annual-route field in the mapping, less those api.years says are gone by
+ * that year, less those added only in a later year, less the test-only
+ * additions (a fieldsAdded entry carrying a status).
+ * @param {string} taxYear - a label such as "2025-26"
+ * @returns {string[]}
+ */
+export function annualFieldSlotsForTaxYear(taxYear) {
+  const unavailable = annualFieldsUnavailableForYear(taxYear);
+  for (const year of Object.values(loadMapping().api.years)) {
+    for (const added of year.fieldsAdded || []) {
+      if (typeof added !== "string") unavailable.add(added.field);
+    }
+  }
+  const slots = new Set();
+  for (const entry of boxesOnRoute("annual")) for (const field of fieldsOf(entry)) slots.add(field);
+  return [...slots].filter((field) => !unavailable.has(field)).sort();
+}
+
+function readPath(target, path) {
+  let node = target;
+  for (const part of path.split(".")) {
+    if (node === null || typeof node !== "object" || !Object.hasOwn(node, part)) return undefined;
+    node = node[part];
+  }
+  return node;
+}
+
+function round2(value) {
+  return Math.round(value * 100) / 100;
+}
+
+function sumPeriods(periods, slots) {
+  const total = {};
+  for (const slot of slots) {
+    let sum = null;
+    for (const period of periods) {
+      const value = readPath(period, slot);
+      if (typeof value === "number") sum = (sum ?? 0) + value;
+    }
+    if (sum !== null) setPath(total, slot, round2(sum));
+  }
+  return total;
+}
+
+// Rebuilds a payload from the slots the year accepts, in the mapping's own
+// order, so a field the derivation never set stays absent and a field the
+// year no longer accepts is dropped. Answers the payload and the slots left
+// out of it.
+function restrictToSlots(payload, slots) {
+  const kept = {};
+  const omitted = [];
+  for (const slot of slots) {
+    const value = readPath(payload, slot);
+    if (value === undefined) omitted.push(slot);
+    else setPath(kept, slot, value);
+  }
+  return { kept, omitted };
+}
+
+function periodLabel(period) {
+  return `${period.periodDates.periodStartDate} to ${period.periodDates.periodEndDate}`;
+}
+
+/**
+ * One period of the Self Employment Business API from a self-employed book.
+ * In a tax year HMRC files as dated period summaries (2023-24, 2024-25) the
+ * answer is that period's own figures; in a year filed as cumulative period
+ * summaries (2025-26 on) it is the running total from the year's first
+ * period through the one named. The period is picked by periodEndDate among
+ * the year's four; with no periodEndDate every period is answered.
+ * @param {Object} book - parsed book.toml
+ * @param {Array} lines - parsed lines.jsonl entries
+ * @param {{periodEndDate?: string, quarterlyPeriodType?: "standard"|"calendar", taxYear?: string}} [params] -
+ *   quarterlyPeriodType defaults to standard (6 April quarters); taxYear (as 2025-26) overrides the year the
+ *   book's dates imply
+ * @returns {Promise<Object>} { taxYear, shape, quarterlyPeriodType, fieldSlots, periods, warnings }
+ */
+export async function deriveItsaQuarterlyUpdate(book, lines, { periodEndDate, quarterlyPeriodType, taxYear } = {}) {
+  requireSelfEmployedBook(book, lines, "deriveItsaQuarterlyUpdate");
+  const taxData = await taxDataFor(book, taxYear);
+  const label = taxData.tax_year.label;
+  const shape = loadMapping().api.years[label].quarterly;
+  const periodType = quarterlyPeriodType || "standard";
+  if (!QUARTERLY_PERIOD_TYPES.includes(periodType)) {
+    throw new Error(`quarterlyPeriodType must be one of ${QUARTERLY_PERIOD_TYPES.join(", ")}, not "${periodType}"`);
+  }
+
+  const derived = buildSelfEmploymentQuarterlyUpdates(book, lines, taxData, { quarterlyPeriodType: periodType });
+  const slots = quarterlyFieldSlots();
+  const periods = derived.periods;
+
+  let wanted = periods;
+  if (periodEndDate) {
+    const index = periods.findIndex((period) => period.periodDates.periodEndDate === periodEndDate);
+    if (index === -1) {
+      throw new Error(
+        `No ${periodType} period of ${label} ends on ${periodEndDate}; the periods end on ${periods.map((p) => p.periodDates.periodEndDate).join(", ")}`,
+      );
+    }
+    wanted = [periods[index]];
+  }
+
+  const answers = wanted.map((period) => {
+    const index = periods.indexOf(period);
+    const covered = shape === "cumulative-period-summary" ? periods.slice(0, index + 1) : [period];
+    const figures = shape === "cumulative-period-summary" ? sumPeriods(covered, slots) : period;
+    const { kept, omitted } = restrictToSlots(figures, slots);
+    return {
+      periodDates: {
+        periodStartDate: covered[0].periodDates.periodStartDate,
+        periodEndDate: period.periodDates.periodEndDate,
+      },
+      ...kept,
+      omitted,
+      covers: covered.map(periodLabel),
+    };
+  });
+
+  return {
+    taxYear: label,
+    shape,
+    quarterlyPeriodType: periodType,
+    fieldSlots: slots,
+    periods: answers,
+    warnings: derived.warnings,
+  };
+}
+
+/**
+ * The year's allowances and adjustments for the Self Employment Business
+ * API's annual submission, from a self-employed book, restricted to the
+ * fields HMRC's schema accepts for that tax year.
+ * @param {Object} book - parsed book.toml
+ * @param {Array} lines - parsed lines.jsonl entries
+ * @param {{taxYear?: string}} [params] - taxYear (as 2025-26) overrides the year the book's dates imply
+ * @returns {Promise<Object>} { taxYear, fieldSlots, allowances, adjustments, omitted, warnings }
+ */
+export async function deriveItsaAnnualSubmission(book, lines, { taxYear } = {}) {
+  requireSelfEmployedBook(book, lines, "deriveItsaAnnualSubmission");
+  const taxData = await taxDataFor(book, taxYear);
+  const label = taxData.tax_year.label;
+  const slots = annualFieldSlotsForTaxYear(label);
+
+  const derived = buildSelfEmploymentAnnualSubmission(book, lines, taxData);
+  const { kept, omitted } = restrictToSlots(derived, slots);
+
+  return {
+    taxYear: label,
+    fieldSlots: slots,
+    ...kept,
+    omitted,
+    warnings: derived.warnings,
+  };
+}

package/dist/app/lib/derivations/vat-return.js

@@ -0,0 +1,238 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2006-2026 DIY Accounting Limited
+//
+// vat-return.js — the nine VAT boxes for one obligation period, read from the
+// Ltd engine's own Vatreturns.xlsx!Vatinterface results, with HMRC's field
+// names, HMRC's rounding, and the journal lines that fed each box. Nothing
+// here computes VAT the engine has not already computed: the boxes are the
+// interface's quarter columns, and the lines are attributed with the same
+// split the journal rows use, then reconciled against those columns.
+
+import { calculateFromDiyaGl } from "../diya-gl-calculator.js";
+import { diyaGlToScenario } from "../diya-gl-loader.js";
+import { loadTaxDataForBook, productOf } from "../product-workbook.js";
+import { isStraddlingLine, LTD_PURCHASE_CODE_MAP, LTD_SALES_CODE_MAP } from "../scenario-extractor.js";
+import { dateFromExcelSerial } from "../calculators/shared.js";
+import { VAT_RATE } from "../calculators/ltd.js";
+import { splitVat, VATINTERFACE_FIRST_MONTH_ROW, VATINTERFACE_FIRST_ROW, VATINTERFACE_LAST_ROW } from "../tax/vat.js";
+
+const INTERFACE_SHEET = "Vatreturns.xlsx!Vatinterface";
+const MONTHS_IN_QUARTER = 3;
+
+/**
+ * The ISO day an Excel serial names.
+ * @param {number} serial
+ * @returns {string}
+ */
+export function isoFromSerial(serial) {
+  return dateFromExcelSerial(serial).toISOString().slice(0, 10);
+}
+
+function isoDate(value) {
+  if (value === undefined || value === null) return null;
+  return new Date(value).toISOString().slice(0, 10);
+}
+
+function firstOfMonthsBefore(isoMonthEnd, monthsBefore) {
+  const [year, month] = isoMonthEnd.split("-").map(Number);
+  return new Date(Date.UTC(year, month - 1 - monthsBefore, 1)).toISOString().slice(0, 10);
+}
+
+function monthKey(isoDay) {
+  return isoDay.slice(0, 7);
+}
+
+function pence(value) {
+  return Math.round(value * 100) / 100;
+}
+
+function pounds(value) {
+  return Math.round(value);
+}
+
+function splitGross(gross) {
+  return splitVat(gross, VAT_RATE);
+}
+
+/**
+ * The interface rows the engine built for a book: one per period end, with
+ * the month figures and, from the first accounting month on, the quarter sums
+ * the return boxes read.
+ * @param {Object} results - calculateFromDiyaGl() output for a Company (ltd) book
+ * @returns {Array<{row: number, periodEnd: string, dueDate: string, month: Object, quarter: Object|null, flatRate: number}>}
+ */
+export function interfaceRows(results) {
+  const sheet = results[INTERFACE_SHEET];
+  if (!sheet) throw new Error("The book's product carries no VAT interface; only a Company (ltd) book answers a VAT return");
+  const rows = [];
+  for (let row = VATINTERFACE_FIRST_ROW; row <= VATINTERFACE_LAST_ROW; row++) {
+    const hasQuarter = row >= VATINTERFACE_FIRST_MONTH_ROW;
+    rows.push({
+      row,
+      periodEnd: isoFromSerial(sheet[`B${row}`]),
+      dueDate: isoFromSerial(sheet[`C${row}`]),
+      month: {
+        salesNet: sheet[`D${row}`] || 0,
+        salesVat: sheet[`F${row}`] || 0,
+        purchasesNet: sheet[`H${row}`] || 0,
+        purchasesVat: sheet[`J${row}`] || 0,
+      },
+      quarter: hasQuarter
+        ? {
+            salesNet: sheet[`E${row}`] || 0,
+            salesVat: sheet[`G${row}`] || 0,
+            purchasesNet: sheet[`I${row}`] || 0,
+            purchasesVat: sheet[`K${row}`] || 0,
+          }
+        : null,
+      flatRate: sheet[`M${row}`] || 0,
+    });
+  }
+  return rows;
+}
+
+function lineContribution(line, box) {
+  const { vat, net } = splitGross(line.amount);
+  return {
+    entryNumber: line.entryNumber,
+    lineNumber: line.lineNumber ?? null,
+    date: line.postingDate,
+    account: line.accountMainID,
+    reference: line.documentReference ?? null,
+    counterparty: line.detailComment ?? null,
+    gross: pence(line.amount),
+    contributes: pence(box === "vat" ? vat : net),
+  };
+}
+
+// The journal lines behind one quarter, bucketed the way the engine's month
+// tabs and straddling sheets take them: a line without diya-gl:vatPeriodEnd
+// lands on the month its postingDate names; a line with it lands on the
+// interface row carrying that period end.
+function linesForQuarter(lines, quarterRows) {
+  const monthEnds = new Set(quarterRows.map((r) => r.periodEnd));
+  const months = new Set(quarterRows.map((r) => monthKey(r.periodEnd)));
+  const inQuarter = (line) => {
+    if (isStraddlingLine(line)) return monthEnds.has(isoDate(line["diya-gl:vatPeriodEnd"]));
+    return months.has(monthKey(line.postingDate));
+  };
+  const sales = lines.filter((l) => l.sourceJournalID === "sales" && LTD_SALES_CODE_MAP[l.accountMainID] && inQuarter(l));
+  const purchases = lines.filter((l) => l.sourceJournalID === "purchases" && LTD_PURCHASE_CODE_MAP[l.accountMainID] && inQuarter(l));
+  return { sales, purchases };
+}
+
+function sumContributions(lines, part) {
+  return lines.reduce((total, line) => total + splitGross(line.amount)[part], 0);
+}
+
+function reconcile(label, attributed, engine) {
+  if (Math.abs(attributed - engine) > 0.005) {
+    throw new Error(
+      `The lines attributed to ${label} sum to ${pence(attributed)} but the book's VAT interface carries ${pence(engine)}; ` +
+        "a line is dated outside the accounting year or posts to a month the interface does not carry, so this return cannot be derived",
+    );
+  }
+}
+
+/**
+ * The nine VAT return boxes for the quarter ending on periodEnd, from a
+ * Company (ltd) book that declares itself VAT registered.
+ * @param {Object} book - parsed book.toml
+ * @param {Array} lines - parsed lines.jsonl entries
+ * @param {{periodEnd: string, periodStart?: string, periodKey?: string}} params - periodEnd is the
+ *   obligation's period end (YYYY-MM-DD); periodStart, when given, must open that quarter; periodKey is
+ *   echoed back untouched
+ * @returns {Promise<Object>} { vatRegistrationNumber, periodKey, periodStart, periodEnd, dueDate, scheme,
+ *   months, boxes, hmrc, lines, notes }
+ */
+export async function deriveVatReturn(book, lines, { periodEnd, periodStart, periodKey } = {}) {
+  if (!book || !lines) throw new Error("deriveVatReturn requires a book and its lines");
+  if (!periodEnd) throw new Error("deriveVatReturn requires periodEnd (the obligation's period end, YYYY-MM-DD)");
+  const entity = book.entityInformation ?? {};
+  if (entity["diya-gl:vatRegistered"] !== true) {
+    throw new Error(
+      "The book does not declare the company VAT registered (entityInformation diya-gl:vatRegistered), so it carries no VAT return",
+    );
+  }
+
+  const product = productOf(book);
+  const taxData = await loadTaxDataForBook(book);
+  const results = calculateFromDiyaGl(book, lines, product, taxData, diyaGlToScenario(book, lines, product));
+  const rows = interfaceRows(results);
+  const wantedEnd = isoDate(periodEnd);
+  const index = rows.findIndex((r) => r.periodEnd === wantedEnd);
+  if (index < 0) {
+    throw new Error(
+      `The book carries no VAT period ending ${wantedEnd}; it answers periods ending ${rows.map((r) => r.periodEnd).join(", ")}`,
+    );
+  }
+  const row = rows[index];
+  if (!row.quarter) {
+    throw new Error(
+      `The period ending ${wantedEnd} is before the book's accounting year; the earliest quarter this book answers ends ${rows[VATINTERFACE_FIRST_MONTH_ROW - VATINTERFACE_FIRST_ROW].periodEnd}`,
+    );
+  }
+  const expectedStart = firstOfMonthsBefore(wantedEnd, MONTHS_IN_QUARTER - 1);
+  if (periodStart && isoDate(periodStart) !== expectedStart) {
+    throw new Error(
+      `The book answers three-month periods ending on a month end; ${isoDate(periodStart)} to ${wantedEnd} is not one, the quarter ending ${wantedEnd} starts ${expectedStart}`,
+    );
+  }
+
+  const quarterRows = rows.slice(index - (MONTHS_IN_QUARTER - 1), index + 1);
+  const { sales, purchases } = linesForQuarter(lines, quarterRows);
+  reconcile("box 1", sumContributions(sales, "vat"), row.quarter.salesVat);
+  reconcile("box 4", sumContributions(purchases, "vat"), row.quarter.purchasesVat);
+  reconcile("box 6", sumContributions(sales, "net"), row.quarter.salesNet);
+  reconcile("box 7", sumContributions(purchases, "net"), row.quarter.purchasesNet);
+
+  const flatRate = row.flatRate > 0;
+  const box1 = pence(row.quarter.salesVat);
+  const box2 = 0;
+  const box3 = pence(box1 + box2);
+  const box4 = pence(row.quarter.purchasesVat);
+  const box5 = pence(box3 - box4);
+  const box6 = pounds(row.quarter.salesNet + (flatRate ? row.quarter.salesVat : 0));
+  const box7 = pounds(row.quarter.purchasesNet);
+  const box8 = 0;
+  const box9 = 0;
+
+  return {
+    vatRegistrationNumber: entity["diya-gl:vatNumber"] ?? null,
+    periodKey: periodKey ?? null,
+    periodStart: expectedStart,
+    periodEnd: wantedEnd,
+    dueDate: row.dueDate,
+    scheme: flatRate ? "flat-rate" : "standard",
+    months: quarterRows.map((r) => ({
+      periodEnd: r.periodEnd,
+      salesNet: pence(r.month.salesNet),
+      salesVat: pence(r.month.salesVat),
+      purchasesNet: pence(r.month.purchasesNet),
+      purchasesVat: pence(r.month.purchasesVat),
+    })),
+    boxes: { box1, box2, box3, box4, box5, box6, box7, box8, box9 },
+    hmrc: {
+      vatDueSales: box1,
+      vatDueAcquisitions: box2,
+      totalVatDue: box3,
+      vatReclaimedCurrPeriod: box4,
+      netVatDue: box5,
+      totalValueSalesExVAT: box6,
+      totalValuePurchasesExVAT: box7,
+      totalValueGoodsSuppliedExVAT: box8,
+      totalAcquisitionsExVAT: box9,
+    },
+    lines: {
+      box1: sales.map((l) => lineContribution(l, "vat")),
+      box4: purchases.map((l) => lineContribution(l, "vat")),
+      box6: sales.map((l) => lineContribution(l, "net")),
+      box7: purchases.map((l) => lineContribution(l, "net")),
+    },
+    notes: [
+      `The engine applies ${VAT_RATE * 100}% to every sales and purchases journal line; the lines' own taxCode and taxRate are not read.`,
+      "Boxes 2, 8 and 9 are nil: the book carries no EU acquisitions or supplies.",
+      "Boxes 1 to 5 are to the penny and boxes 6 to 9 whole pounds; box 5 is the rounded box 3 less the rounded box 4.",
+    ],
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diy-accounting-uk/diya-gl",
-  "version": "1.2.43",
+  "version": "1.2.44",
   "type": "module",
   "description": "Recalculate, read and write DIYA-GL books from the command line",
   "license": "Apache-2.0",
@@ -20,6 +20,11 @@
     "diya-gl-view": "bin/diya-gl-view.js",
     "diya-gl-mcp": "bin/diya-gl-mcp.js"
   },
+  "exports": {
+    ".": "./dist/app/lib/derivations/index.js",
+    "./dist/*": "./dist/*",
+    "./package.json": "./package.json"
+  },
   "files": ["bin/", "dist/", "README.md", "NOTICE"],
   "scripts": {
     "prepack": "node scripts/prepack.mjs"