@diy-accounting-uk/diya-gl 1.2.55 → 1.2.57

package/README.md

@@ -96,8 +96,9 @@ Each subcommand is also its own command, if you only want one on your `PATH`:
 
 ## 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.
+The package root exports five functions that turn a book into the figures HMRC's MTD APIs
+take. Each takes the parsed book, its lines and a parameters object. The VAT and self-employment
+functions return a promise; the two UK property functions return their answer directly.
 Nothing is sent anywhere: the answer is the request body to send, plus what fed it.
 
 Load a book first:
@@ -166,6 +167,36 @@ const answer = await deriveItsaAnnualSubmission(book, lines, { taxYear: "2025-26
 console.log(answer.allowances.annualInvestmentAllowance);
 ```
 
+### `deriveUkPropertyPeriod(book, lines, { periodStartDate, periodEndDate })`
+
+One period of HMRC's Property Business API (UK property) from a sole trader book. The book's
+chart names the HMRC field each account feeds with `diya-gl:ukPropertyField` on the account
+(for example `"income.periodAmount"` on the rent account, `"expenses.repairsAndMaintenance"` on
+the repairs account). The function sums the sales and purchases postings on those accounts
+between the two dates inclusive, net of VAT, with a credit note taking from its field. The
+answer carries `income`, `expenses`, `omitted` (the fields no posting fed; they are left out of
+the body, never sent as zero), `lines` and `warnings`. A book that names
+`expenses.consolidatedExpenses` and an itemised expense in the same period is refused, because
+HMRC takes one or the other.
+
+```js
+import { deriveUkPropertyPeriod } from "@diy-accounting-uk/diya-gl";
+
+const { book, lines } = loadBook("my-landlord-book");
+const answer = deriveUkPropertyPeriod(book, lines, { periodStartDate: "2025-04-06", periodEndDate: "2025-07-05" });
+console.log(answer.income.periodAmount, answer.expenses.repairsAndMaintenance);
+```
+
+### `deriveUkPropertyAnnual(book, lines, { taxYear? })`
+
+The year's adjustments (`balancingCharge`, `privateUseAdjustment`,
+`businessPremisesRenovationAllowanceBalancingCharges`) and allowances (`annualInvestmentAllowance`,
+`businessPremisesRenovationAllowance`, `otherCapitalAllowance`, `costOfReplacingDomesticItems`,
+`zeroEmissionsCarAllowance`) from the postings on the accounts the chart names, for the tax year
+`taxYear` (as `2025-26`; the default is the year the book's period end falls in). The property
+income allowance, `nonResidentLandlord` and `rentARoom.jointlyLet` are choices and facts about the
+landlord, not ledger figures; the answer lists them under `leftToPage`.
+
 ## 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

@@ -1663,6 +1663,58 @@
           "scorecard": "101608 passed, 0 warnings, 0 failed"
         }
       }
+    },
+    {
+      "tag": "diya-gl-v1.2.55",
+      "date": "2026-10-24",
+      "formatVersion": "diya-gl/1",
+      "engineVersion": "1.2.55+bb0dbecd",
+      "taxDataHash": "51bdff60e993",
+      "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": "8015 passed, 0 warnings, 0 failed"
+        },
+        "ltd": {
+          "hash": "a65ab09cf35c",
+          "scorecard": "101608 passed, 0 warnings, 0 failed"
+        }
+      }
+    },
+    {
+      "tag": "diya-gl-v1.2.56",
+      "date": "2026-10-25",
+      "formatVersion": "diya-gl/1",
+      "engineVersion": "1.2.56+4d61d48a",
+      "taxDataHash": "51bdff60e993",
+      "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": "8015 passed, 0 warnings, 0 failed"
+        },
+        "ltd": {
+          "hash": "a65ab09cf35c",
+          "scorecard": "101608 passed, 0 warnings, 0 failed"
+        }
+      }
     }
   ]
 }

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

@@ -554,7 +554,8 @@ function buildSchedule(scenario, rate, depreciationRates, investmentAllowancePer
   }
 
   for (const row of rows) {
-    const ratePercent = depreciationRates[row.assetClass];
+    // An asset that states its own rate depreciates at it; any other takes its class's rate.
+    const ratePercent = row.openingAsset?.depreciation_rate ?? depreciationRates[row.assetClass];
     const netBookValue = row.cost - row.depreciationBroughtForward;
     row.depreciationCharge = row.cost > 0 ? Math.min(row.cost * ratePercent, netBookValue) : 0;
     row.depreciationCarriedForward = row.cost > 0 ? row.depreciationBroughtForward + row.depreciationCharge : 0;

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

@@ -6,3 +6,4 @@
 
 export { deriveVatReturn } from "./vat-return.js";
 export { deriveItsaQuarterlyUpdate, deriveItsaAnnualSubmission } from "./itsa.js";
+export { deriveUkPropertyPeriod, deriveUkPropertyAnnual } from "./uk-property.js";

package/dist/app/lib/derivations/uk-property.js

@@ -0,0 +1,218 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2006-2026 DIY Accounting Limited
+//
+// uk-property.js — the two UK property answers HMRC's Property Business API
+// takes from a sole trader's book. deriveUkPropertyPeriod answers one
+// period's income and expenses; deriveUkPropertyAnnual answers the year's
+// adjustments and allowances the book can show.
+//
+// A book names the HMRC field an account feeds with the account's
+// diya-gl:ukPropertyField, in HMRC's own dotted names (income.periodAmount,
+// expenses.repairsAndMaintenance, allowances.costOfReplacingDomesticItems).
+// Lines posted through the sales and purchases journals to a named account
+// are summed net of VAT. A field with no posting is omitted, never sent as a
+// zero. Elections and facts about the landlord (the property income
+// allowance, non-resident landlord, rent a room jointly let) are not in a
+// ledger; they are listed under leftToPage.
+
+import { productOf } from "../product-workbook.js";
+import { signedAmount } from "../scenario-extractor.js";
+
+export const UK_PROPERTY_ACCOUNT_FIELD = "diya-gl:ukPropertyField";
+
+export const PERIOD_INCOME_FIELDS = ["periodAmount", "premiumsOfLeaseGrant", "reversePremiums", "otherIncome", "taxDeducted"].map(
+  (name) => `income.${name}`,
+);
+
+export const PERIOD_EXPENSE_FIELDS = [
+  "premisesRunningCosts",
+  "repairsAndMaintenance",
+  "financialCosts",
+  "professionalFees",
+  "costOfServices",
+  "other",
+  "residentialFinancialCost",
+  "travelCosts",
+  "consolidatedExpenses",
+].map((name) => `expenses.${name}`);
+
+export const ANNUAL_ADJUSTMENT_FIELDS = [
+  "balancingCharge",
+  "privateUseAdjustment",
+  "businessPremisesRenovationAllowanceBalancingCharges",
+].map((name) => `adjustments.${name}`);
+
+export const ANNUAL_ALLOWANCE_FIELDS = [
+  "annualInvestmentAllowance",
+  "businessPremisesRenovationAllowance",
+  "otherCapitalAllowance",
+  "costOfReplacingDomesticItems",
+  "zeroEmissionsCarAllowance",
+].map((name) => `allowances.${name}`);
+
+export const PERIOD_FIELDS = [...PERIOD_INCOME_FIELDS, ...PERIOD_EXPENSE_FIELDS];
+export const ANNUAL_FIELDS = [...ANNUAL_ADJUSTMENT_FIELDS, ...ANNUAL_ALLOWANCE_FIELDS];
+export const UK_PROPERTY_FIELDS = [...PERIOD_FIELDS, ...ANNUAL_FIELDS];
+
+// What the annual submission asks that no posting can answer.
+export const ANNUAL_LEFT_TO_PAGE = [
+  {
+    field: "allowances.propertyIncomeAllowance",
+    reason: "an election between the property income allowance and itemised expenses, made by the landlord.",
+  },
+  { field: "adjustments.nonResidentLandlord", reason: "a fact about the landlord's residence, not a ledger figure." },
+  { field: "adjustments.rentARoom.jointlyLet", reason: "a fact about how the room is let, not a ledger figure." },
+];
+
+const ISO_DAY = /^\d{4}-\d{2}-\d{2}$/;
+const TAX_YEAR_LABEL = /^(\d{4})-(\d{2})$/;
+const OPENING_BALANCE_PREFIX = "OB-";
+
+function round2(value) {
+  return Math.round(value * 100) / 100;
+}
+
+function setPath(target, path, value) {
+  const parts = path.split(".");
+  let node = target;
+  for (const part of parts.slice(0, -1)) node = node[part] ??= {};
+  node[parts.at(-1)] = value;
+}
+
+function requirePropertyBook(book, lines, caller) {
+  if (!book || !lines) throw new Error(`${caller} requires a book and its lines`);
+  const product = productOf(book);
+  if (product === "ltd") {
+    throw new Error(`The book is a "ltd" book; UK property income is an individual's, so ${caller} reads a sole trader book`);
+  }
+}
+
+// Account id -> HMRC field, from the book's own chart.
+function accountFields(book) {
+  const fields = new Map();
+  for (const journal of ["sales", "purchases"]) {
+    for (const [id, account] of Object.entries(book.accounts?.[journal] || {})) {
+      const field = account[UK_PROPERTY_ACCOUNT_FIELD];
+      if (field === undefined) continue;
+      if (!UK_PROPERTY_FIELDS.includes(field)) {
+        throw new Error(`account ${id} names ${UK_PROPERTY_ACCOUNT_FIELD} "${field}", which is not a UK property field`);
+      }
+      fields.set(id, field);
+    }
+  }
+  return fields;
+}
+
+function netAmount(line) {
+  return signedAmount(line) / (1 + (line.taxRate || 0));
+}
+
+// The postings inside [start, end] on a mapped account, summed by field.
+function figuresBetween(book, lines, fieldsWanted, start, end) {
+  const fields = accountFields(book);
+  const totals = new Map();
+  const contributions = [];
+  for (const line of lines) {
+    if (line.sourceJournalID !== "sales" && line.sourceJournalID !== "purchases") continue;
+    if (String(line.documentReference || "").startsWith(OPENING_BALANCE_PREFIX)) continue;
+    const field = fields.get(String(line.accountMainID));
+    if (!field || !fieldsWanted.includes(field)) continue;
+    if (line.postingDate < start || line.postingDate > end) continue;
+    const amount = round2(netAmount(line));
+    totals.set(field, (totals.get(field) ?? 0) + amount);
+    contributions.push({
+      entryNumber: line.entryNumber,
+      date: line.postingDate,
+      account: String(line.accountMainID),
+      field,
+      reference: line.documentReference ?? null,
+      counterparty: line.detailComment ?? null,
+      amount,
+    });
+  }
+  const figures = {};
+  for (const field of fieldsWanted) {
+    if (totals.has(field)) setPath(figures, field, round2(totals.get(field)));
+  }
+  return { figures, contributions, present: fieldsWanted.filter((field) => totals.has(field)) };
+}
+
+/**
+ * One period of HMRC's UK property income and expenses from a sole trader
+ * book whose chart names the property accounts. The answer is the period's
+ * own figures; a cumulative year's running total is the same call with the
+ * period starting on 6 April.
+ * @param {Object} book - parsed book.toml
+ * @param {Array} lines - parsed lines.jsonl entries
+ * @param {{periodStartDate: string, periodEndDate: string}} params - the period, both ends inclusive, as YYYY-MM-DD
+ * @returns {Object} { periodDates, income, expenses, fieldSlots, omitted, lines, warnings }
+ */
+export function deriveUkPropertyPeriod(book, lines, { periodStartDate, periodEndDate } = {}) {
+  requirePropertyBook(book, lines, "deriveUkPropertyPeriod");
+  if (!ISO_DAY.test(periodStartDate ?? "") || !ISO_DAY.test(periodEndDate ?? "")) {
+    throw new Error("periodStartDate and periodEndDate must be YYYY-MM-DD days");
+  }
+  if (periodStartDate > periodEndDate) throw new Error(`the period starts ${periodStartDate}, after it ends ${periodEndDate}`);
+
+  const { figures, contributions, present } = figuresBetween(book, lines, PERIOD_FIELDS, periodStartDate, periodEndDate);
+  const warnings = [];
+  const itemised = present.filter((field) => field.startsWith("expenses.") && field !== "expenses.consolidatedExpenses");
+  if (present.includes("expenses.consolidatedExpenses") && itemised.length > 0) {
+    throw new Error(`the period carries consolidated expenses and itemised expenses (${itemised.join(", ")}); HMRC takes one or the other`);
+  }
+  if (contributions.length === 0) warnings.push("no posting on a UK property account falls in the period");
+
+  return {
+    periodDates: { periodStartDate, periodEndDate },
+    income: figures.income ?? {},
+    expenses: figures.expenses ?? {},
+    fieldSlots: PERIOD_FIELDS,
+    omitted: PERIOD_FIELDS.filter((field) => !present.includes(field)),
+    lines: contributions,
+    warnings,
+  };
+}
+
+function taxYearBounds(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]);
+  if (String(start + 1).slice(-2) !== match[2]) throw new Error(`taxYear "${label}" does not name two consecutive years`);
+  return { start: `${start}-04-06`, end: `${start + 1}-04-05` };
+}
+
+// The tax year (6 April to 5 April) a day falls in.
+function taxYearLabelOf(isoDay) {
+  const [year, month, day] = isoDay.split("-").map(Number);
+  const start = month > 4 || (month === 4 && day >= 6) ? year : year - 1;
+  return `${start}-${String(start + 1).slice(-2)}`;
+}
+
+/**
+ * The year's adjustments and allowances for HMRC's UK property annual
+ * submission, from a sole trader book whose chart names the accounts. The
+ * year defaults to the one the book's period end falls in.
+ * @param {Object} book - parsed book.toml
+ * @param {Array} lines - parsed lines.jsonl entries
+ * @param {{taxYear?: string}} [params] - taxYear as 2025-26
+ * @returns {Object} { taxYear, adjustments, allowances, fieldSlots, omitted, leftToPage, lines, warnings }
+ */
+export function deriveUkPropertyAnnual(book, lines, { taxYear } = {}) {
+  requirePropertyBook(book, lines, "deriveUkPropertyAnnual");
+  const label =
+    taxYear ?? (book.documentInfo?.periodCoveredEnd ? taxYearLabelOf(String(book.documentInfo.periodCoveredEnd).slice(0, 10)) : undefined);
+  if (!label) throw new Error("the book declares no period end, so taxYear is required");
+  const { start, end } = taxYearBounds(label);
+
+  const { figures, contributions, present } = figuresBetween(book, lines, ANNUAL_FIELDS, start, end);
+  return {
+    taxYear: label,
+    adjustments: figures.adjustments ?? {},
+    allowances: figures.allowances ?? {},
+    fieldSlots: ANNUAL_FIELDS,
+    omitted: ANNUAL_FIELDS.filter((field) => !present.includes(field)),
+    leftToPage: ANNUAL_LEFT_TO_PAGE,
+    lines: contributions,
+    warnings: contributions.length === 0 ? ["no posting on a UK property account falls in the tax year"] : [],
+  };
+}

package/dist/app/lib/diya-gl-interchange.js

@@ -9,13 +9,14 @@
 // writeDiyaGlZip/writeBookJson, so a download from one matches an export
 // from another byte-for-byte.
 //
-// Seven byte kinds, told apart by content, never by file extension: a
+// Nine byte kinds, told apart by content, never by file extension: a
 // workbook, the zip a single-workbook package ships as, the zip a
 // multi-file package ships as, this module's own zip (book.toml +
-// lines.jsonl), that pair as one JSON file, the same JSON zipped, and the
-// legacy .xls this pipeline cannot read directly. A customer's upload can
-// be any of the first six under any name at all -- a renamed .xlsx is still
-// a workbook -- so the kind is decided by what the bytes actually contain.
+// lines.jsonl), that pair as one JSON file, the same JSON zipped, an Inline
+// XBRL accounts document, a plain XBRL instance, and the legacy .xls this
+// pipeline cannot read directly. A customer's upload can be any of the first
+// six under any name at all -- a renamed .xlsx is still a workbook -- so the
+// kind is decided by what the bytes actually contain.
 //
 // Reading a workbook or its package zip runs the pipeline export.js has
 // always run: the anchor guard, then the extractors and book builder
@@ -45,6 +46,9 @@ import { canonicalBookToml, canonicalLinesJsonl, compareLines, orderedBookTopLev
 import { serializeReportDocument } from "./report-serializer.js";
 import { parseDiyaGlData } from "./diya-gl-loader.js";
 import { stampBook } from "./provenance.js";
+import { sniffIxbrl } from "./ixbrl-reader.js";
+import { mapIxbrlAccounts } from "./ixbrl-accounts.js";
+import { buildIxbrlSummaryBooks } from "./ixbrl-summary-book.js";
 import * as bst from "../products/bst.js";
 
 export { AnchorError };
@@ -70,7 +74,7 @@ export class UnknownBookSourceError extends Error {
   constructor(name) {
     super(
       `${name ? `"${name}"` : "This file"} is not one of the kinds diya-gl reads: a Basic Sole Trader workbook (.xlsx), ` +
-        `its package zip, a diya-gl zip, a diya-gl JSON file, or that JSON zipped.`,
+        `its package zip, a diya-gl zip, a diya-gl JSON file, that JSON zipped, or an iXBRL accounts file.`,
     );
     this.name = "UnknownBookSourceError";
   }
@@ -196,14 +200,14 @@ async function zipKind(bytes) {
  * error messages only.
  * @param {Uint8Array} bytes
  * @param {string} [name] - a hint for messages, not for detection
- * @returns {Promise<"workbook"|"package-zip"|"package-set"|"diya-gl-zip"|"json-zip"|"json"|"xls"|"unknown">}
+ * @returns {Promise<"workbook"|"package-zip"|"package-set"|"diya-gl-zip"|"json-zip"|"json"|"ixbrl"|"xbrl"|"xls"|"unknown">}
  */
 export async function detectBookSource(bytes, name) {
   void name; // content decides the kind; the name is a hint for a caller's own error messages, never for detection
   if (isZipContainer(bytes)) return zipKind(bytes);
   if (startsWithBytes(bytes, OLE_MAGIC)) return "xls";
   if (looksLikeJsonObject(bytes)) return "json";
-  return "unknown";
+  return sniffIxbrl(bytes) ?? "unknown";
 }
 
 // ============================================================================
@@ -456,17 +460,37 @@ async function readJsonZipSource(bytes) {
   return { ...validated("json-zip", document.book, document.lines), product: document.product };
 }
 
+// An accounts file stands for two Company books, the file's own year and the
+// year before, each a summary with one line per tagged line. The comparative
+// pair, the accounts figures and the facts no figure uses ride beside them.
+async function readIxbrlSource(kind, bytes, deps) {
+  const accounts = mapIxbrlAccounts(bytes, deps.expect);
+  const summary = await buildIxbrlSummaryBooks(accounts, { resources: deps.resources });
+  const current = validated(kind, summary.book, summary.lines);
+  const prior = validated(kind, summary.comparative.book, summary.comparative.lines);
+  return {
+    ...current,
+    product: "ltd",
+    comparative: { book: prior.book, lines: prior.lines },
+    accounts,
+    unmapped: accounts.unmapped,
+    differences: summary.differences,
+  };
+}
+
 /**
- * Turn a byte array into D: the book and its lines, whichever of the six
- * kinds it sniffs as. The CLI's --file mode, the MCP server's extract_book
+ * Turn a byte array into D: the book and its lines, whichever of the kinds
+ * it sniffs as. The CLI's --file mode, the MCP server's extract_book
  * tool and the books page all call this, so a file that loads in one loads
  * in all.
  * @param {Uint8Array} bytes
  * @param {string} [name] - a hint for error messages
  * @param {Object} [deps] - {products}: product id to product module
  *   (CELL_MAP, cellLabels()) for the products this caller can read;
- *   defaults to app/products/bst.js alone
- * @returns {Promise<{kind: string, product?: string, book: Object, lines: Array, overtyped?: Object, workbookSet?: Object}>}
+ *   defaults to app/products/bst.js alone. {expect, resources} serve an
+ *   iXBRL accounts file: what the page expects of the file (company number,
+ *   period, regime), and the loader of the tax year's data.
+ * @returns {Promise<{kind: string, product?: string, book: Object, lines: Array, overtyped?: Object, workbookSet?: Object, comparative?: {book: Object, lines: Array}, accounts?: Object, unmapped?: Array, differences?: string[]}>}
  */
 export async function readBookSource(bytes, name, deps = {}) {
   const kind = await detectBookSource(bytes, name);
@@ -481,6 +505,9 @@ export async function readBookSource(bytes, name, deps = {}) {
       return readJsonSource(bytes);
     case "json-zip":
       return readJsonZipSource(bytes);
+    case "ixbrl":
+    case "xbrl":
+      return readIxbrlSource(kind, bytes, deps);
     case "xls":
       throw new XlsBookSourceError(name);
     default:

package/dist/app/lib/diya-gl-loader.js

@@ -607,6 +607,7 @@ export function diyaGlToScenario(book, lines, product) {
         }
         const opening = { category, description: asset.description, cost: asset.cost, acc_dep: asset.accumulatedDepreciation };
         if (asset.taxWrittenDownValue !== undefined) opening.tax_wdv = asset.taxWrittenDownValue;
+        if (asset.depreciationRate !== undefined) opening.depreciation_rate = asset.depreciationRate;
         if (asset.capitalAllowancePool === "special") opening.pool = "special";
         // A single asset pool is a fact the book states, never one the loader
         // infers: private use puts an asset in its own pool (CAA 2001 s.206),