@diy-accounting-uk/diya-gl 1.2.56 → 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

@@ -1689,6 +1689,32 @@
           "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/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/provenance-data.js

@@ -12,7 +12,7 @@
 
 export const PROVENANCE_DATA = {
   formatVersion: "diya-gl/1",
-  engineVersion: "1.2.56+4d61d48a",
+  engineVersion: "1.2.57+6768c2fe",
   taxDataHash: "51bdff60e993",
   reconciledCommit: "54e8731a91279975e61b1a232fbb67fda89515f0",
   templates: {

package/dist/web/spreadsheets.diyaccounting.co.uk/public/schema/diya-gl-book-v2.schema.json

@@ -1112,6 +1112,34 @@
           "minimum": 1,
           "maximum": 9,
           "description": "diya-gl: extension \u2014 VAT return box number (1-9) this account contributes to"
+        },
+        "diya-gl:ukPropertyField": {
+          "type": "string",
+          "enum": [
+            "income.periodAmount",
+            "income.premiumsOfLeaseGrant",
+            "income.reversePremiums",
+            "income.otherIncome",
+            "income.taxDeducted",
+            "expenses.premisesRunningCosts",
+            "expenses.repairsAndMaintenance",
+            "expenses.financialCosts",
+            "expenses.professionalFees",
+            "expenses.costOfServices",
+            "expenses.other",
+            "expenses.residentialFinancialCost",
+            "expenses.travelCosts",
+            "expenses.consolidatedExpenses",
+            "adjustments.balancingCharge",
+            "adjustments.privateUseAdjustment",
+            "adjustments.businessPremisesRenovationAllowanceBalancingCharges",
+            "allowances.annualInvestmentAllowance",
+            "allowances.businessPremisesRenovationAllowance",
+            "allowances.otherCapitalAllowance",
+            "allowances.costOfReplacingDomesticItems",
+            "allowances.zeroEmissionsCarAllowance"
+          ],
+          "description": "diya-gl: extension \u2014 the HMRC UK property field (Property Business API names) this sales or purchases account feeds, so deriveUkPropertyPeriod and deriveUkPropertyAnnual can sum its postings"
         }
       }
     },

package/dist/web/spreadsheets.diyaccounting.co.uk/public/schema/diya-gl-docs.md

@@ -572,6 +572,7 @@ metadata needed for the spreadsheet mapping:
 | `diya-gl:sa103sBox`          | SA103S box reference (e.g. 'box10')          | book.toml |
 | `diya-gl:ct600Box`           | CT600 box reference                          | book.toml |
 | `diya-gl:vatBox`             | VAT return box number (1-9)                  | book.toml |
+| `diya-gl:ukPropertyField`   | HMRC UK property field this account feeds    | book.toml |
 | `diya-gl:bankCode`           | Bank receipt/payment code (DR/CR/W/RP/RV...) | .jsonl    |
 | `diya-gl:bankAccountID`      | Bank account code from chart of accounts     | .jsonl    |
 | `diya-gl:employeeID`         | Employee identifier (matches employees[])    | .jsonl    |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diy-accounting-uk/diya-gl",
-  "version": "1.2.56",
+  "version": "1.2.57",
   "type": "module",
   "description": "Recalculate, read and write DIYA-GL books from the command line",
   "license": "Apache-2.0",