@firedrill-tools/quickbooks 0.1.2

package/firedrill/tools/quickbooks/lib/invoice-draft.mjs

@@ -0,0 +1,165 @@
+// Parsing and validation of an invoice body (create, full update, sparse update) into a stored invoice row.
+import { TERMS, clip, dateFromDay, dayNumber, fromCents, lineCents, toCents, toScaled4, utf8Bytes } from "./common.mjs";
+import { checkKeys, has, isObject, optAddr, optDate, optEmail, optEnum, optRef, optString, own } from "./fields.mjs";
+
+const WRITABLE = new Set(["DocNumber", "TxnDate", "DueDate", "CustomerRef", "SalesTermRef", "BillEmail", "BillAddr", "Line", "CustomerMemo", "PrivateNote", "EmailStatus", "PrintStatus", "GlobalTaxCalculation"]);
+const READONLY = new Set(["Id", "SyncToken", "sparse", "domain", "MetaData", "TotalAmt", "Balance", "LinkedTxn", "TxnTaxDetail", "CurrencyRef", "ApplyTaxAfterDiscount", "DeliveryInfo"]);
+const LINE_KEYS = new Set(["Id", "LineNum", "Description", "Amount", "DetailType", "SalesItemLineDetail", "SubTotalLineDetail", "LineEx"]);
+const DETAIL_KEYS = new Set(["ItemRef", "Qty", "UnitPrice", "ServiceDate", "TaxCodeRef"]);
+/**
+ * Upper bound on the JSON-encoded UTF-8 bytes of all line Descriptions on one invoice, measured as the text is returned
+ * (`JSON.stringify` without the surrounding quotes, so `\n`, `"` and `\\` count 2 bytes and control characters 6, while
+ * CJK counts its 3 UTF-8 bytes). Each Description may be 4,000 characters and an invoice 250 lines, so without this bound a
+ * stored invoice could render to 3-6 MB — over the framework's 1 MiB response cap for GET, PDF and query alike. With it, a
+ * maximal invoice (600 KB of encoded descriptions plus at most about 250 KB of other line and header fields) always fits
+ * one query page; `evaluate` in query-eval.mjs stays the last line of defence for any single row over RESPONSE_BYTE_BUDGET.
+ */
+export const INVOICE_DESCRIPTION_BYTES = 600_000;
+/** Bytes a string occupies inside a JSON response, without its two quotes: the size that counts against the response cap. */
+export function encodedBytes(text) {
+  return utf8Bytes(JSON.stringify(text)) - 2;
+}
+export const INACTIVE_DETAIL = "Invalid Reference Id : Something you're trying to use has been made inactive. Check the fields with accounts, customers, items, vendors or employees.";
+
+/** Sales lines → stored lines and total cents. SubTotalLineDetail lines echoed back by clients are ignored. */
+export function parseLines(s, raw, currentLines) {
+  if (!Array.isArray(raw)) s.fail("BUSINESS_VALIDATION", "Invalid value for Line: expected an array of lines", "Line");
+  if (raw.length > 251) s.fail("BUSINESS_VALIDATION", "An invoice can have at most 250 lines.", "Line");
+  const existing = new Set((currentLines ?? []).map((line) => line.SalesItemLineDetail.ItemRef.value));
+  const lines = [];
+  let total = 0;
+  let descriptionBytes = 0;
+  for (const [index, line] of raw.entries()) {
+    const at = `Line[${index}]`;
+    if (!isObject(line)) s.fail("BUSINESS_VALIDATION", `Invalid value for ${at}: expected a line object`, at);
+    for (const key of Object.keys(line)) if (!LINE_KEYS.has(key)) s.fail("BUSINESS_VALIDATION", `Request has invalid or unsupported property : Property Name:${clip(key, 80)} specified is unsupported or invalid`, at);
+    if (line.DetailType === "SubTotalLineDetail") continue;
+    if (!has(line, "DetailType") || line.DetailType === null) s.fail("REQUIRED_PARAM_MISSING", "Required param missing, need to supply the required value for the API: Line.DetailType", `${at}.DetailType`);
+    if (line.DetailType !== "SalesItemLineDetail") s.fail("BUSINESS_VALIDATION", "Only SalesItemLineDetail lines are supported by this company (no discount, group or description-only lines).", `${at}.DetailType`);
+    const detail = own(line, "SalesItemLineDetail");
+    if (!isObject(detail)) s.fail("REQUIRED_PARAM_MISSING", "Required param missing, need to supply the required value for the API: SalesItemLineDetail", `${at}.SalesItemLineDetail`);
+    for (const key of Object.keys(detail)) if (!DETAIL_KEYS.has(key)) s.fail("BUSINESS_VALIDATION", `Request has invalid or unsupported property : Property Name:${clip(key, 80)} specified is unsupported or invalid`, at);
+    const itemId = optRef(s, detail, "ItemRef");
+    if (typeof itemId !== "string") s.fail("REQUIRED_PARAM_MISSING", "Required param missing, need to supply the required value for the API: ItemRef", `${at}.SalesItemLineDetail.ItemRef`);
+    const item = s.get("items", itemId);
+    if (item === null) s.fail("INVALID_REFERENCE", `Invalid Reference Id : Item assigned to line ${index + 1} does not exist: ${clip(itemId, 64)}`, `${at}.SalesItemLineDetail.ItemRef`);
+    if (!item.Active && !existing.has(item.Id)) s.fail("INVALID_REFERENCE", INACTIVE_DETAIL, `${at}.SalesItemLineDetail.ItemRef`);
+    const qty = has(detail, "Qty") && detail.Qty !== null ? detail.Qty : 1;
+    const qtyScaled = toScaled4(qty, 999_999);
+    if (qtyScaled === null || qtyScaled === 0) s.fail("BUSINESS_VALIDATION", "Qty must be a number greater than zero with at most four decimals.", `${at}.SalesItemLineDetail.Qty`);
+    const price = has(detail, "UnitPrice") && detail.UnitPrice !== null ? detail.UnitPrice : item.UnitPrice;
+    const priceScaled = toScaled4(price, 999_999_999);
+    if (priceScaled === null) s.fail("BUSINESS_VALIDATION", "UnitPrice must be a non-negative number with at most four decimals.", `${at}.SalesItemLineDetail.UnitPrice`);
+    const cents = lineCents(qtyScaled, priceScaled);
+    if (has(line, "Amount") && line.Amount !== null && toCents(line.Amount) !== cents) {
+      s.fail("BUSINESS_VALIDATION", `Amount is not equal to UnitPrice * Qty. Supplied value:${clip(String(line.Amount), 40)}`, `${at}.Amount`);
+    }
+    const description = optString(s, line, "Description", 4000);
+    const serviceDate = optDate(s, detail, "ServiceDate");
+    const taxCode = optRef(s, detail, "TaxCodeRef");
+    if (typeof taxCode === "string" && taxCode !== "TAX" && taxCode !== "NON") s.fail("BUSINESS_VALIDATION", "TaxCodeRef must be TAX or NON for this US company.", `${at}.SalesItemLineDetail.TaxCodeRef`);
+    total += cents;
+    const storedDescription = description === undefined ? item.Description : description;
+    if (typeof storedDescription === "string") descriptionBytes += encodedBytes(storedDescription);
+    if (descriptionBytes > INVOICE_DESCRIPTION_BYTES) {
+      s.fail("BUSINESS_VALIDATION", `The line descriptions on this invoice total more than 600,000 bytes of text as returned (JSON-encoded, including descriptions inherited from items); shorten the descriptions or split the invoice.`, `${at}.Description`);
+    }
+    lines.push({
+      Id: String(lines.length + 1),
+      LineNum: lines.length + 1,
+      Description: storedDescription,
+      Amount: fromCents(cents),
+      DetailType: "SalesItemLineDetail",
+      SalesItemLineDetail: {
+        ItemRef: { value: item.Id, name: item.Name },
+        Qty: qty,
+        UnitPrice: price,
+        ServiceDate: serviceDate ?? null,
+        TaxCodeRef: { value: typeof taxCode === "string" ? taxCode : item.Taxable ? "TAX" : "NON" },
+      },
+    });
+  }
+  if (lines.length === 0) s.fail("BUSINESS_VALIDATION", "You must fill out at least one split line.", "Line");
+  if (lines.length > 250) s.fail("BUSINESS_VALIDATION", "An invoice can have at most 250 lines.", "Line");
+  if (total > 99_999_999_999) s.fail("BUSINESS_VALIDATION", "The invoice total exceeds the supported maximum.", "Line");
+  return { lines, total };
+}
+
+/** Body → next invoice row fields (Id, SyncToken, MetaData, DocNumber, balances are completed by the caller). */
+export function draftInvoice(s, body, current, sparse) {
+  if (!isObject(body)) s.fail("REQUIRED_PARAM_MISSING", "Required param missing, need to supply the required value for the API: Invoice object", "Invoice");
+  checkKeys(s, body, WRITABLE, READONLY);
+  if (current !== null && current.voided) s.fail("BUSINESS_VALIDATION", "A voided invoice can't be changed.", "Id");
+  const keep = (key) => current !== null && sparse && !has(body, key);
+  const next = current === null ? { voided: false, DeliveryInfo: null, EmailStatus: "NotSet", PrintStatus: "NotSet" } : { ...current };
+
+  let customer;
+  if (keep("CustomerRef")) customer = s.get("customers", current.CustomerRef.value);
+  else {
+    const customerId = optRef(s, body, "CustomerRef");
+    if (typeof customerId !== "string") s.fail("REQUIRED_PARAM_MISSING", "Required param missing, need to supply the required value for the API: CustomerRef", "CustomerRef");
+    customer = s.get("customers", customerId);
+    if (customer === null) s.fail("INVALID_REFERENCE", `Invalid Reference Id : Customer assigned to this transaction does not exist: ${clip(customerId, 64)}`, "CustomerRef");
+    const changed = current === null || current.CustomerRef.value !== customer.Id;
+    if (!customer.Active && changed) s.fail("INVALID_REFERENCE", INACTIVE_DETAIL, "CustomerRef");
+    next.CustomerRef = { value: customer.Id, name: customer.DisplayName };
+  }
+  if (!keep("Line")) {
+    if (!has(body, "Line") || body.Line === null) s.fail("REQUIRED_PARAM_MISSING", "Required param missing, need to supply the required value for the API: Line", "Line");
+    const parsed = parseLines(s, body.Line, current === null ? null : current.Line);
+    next.Line = parsed.lines;
+    next.TotalAmt = fromCents(parsed.total);
+  }
+  const txnDate = optDate(s, body, "TxnDate");
+  if (txnDate !== undefined && txnDate !== null) next.TxnDate = txnDate;
+  else if (current === null) next.TxnDate = s.clock.date;
+
+  const term = optRef(s, body, "SalesTermRef");
+  if (typeof term === "string" && !TERMS.has(term)) s.fail("INVALID_REFERENCE", `Invalid Reference Id : Term assigned to this transaction does not exist: ${clip(term, 64)}`, "SalesTermRef");
+  if (term !== undefined) next.SalesTermRef = typeof term === "string" ? { value: term, name: TERMS.get(term).name } : null;
+  else if (current === null) next.SalesTermRef = customer !== null && customer.SalesTermRef !== null ? customer.SalesTermRef : null;
+  else if (!sparse) next.SalesTermRef = null;
+
+  const due = optDate(s, body, "DueDate");
+  if (due !== undefined && due !== null) next.DueDate = due;
+  else if (current === null || !sparse || due === null) {
+    const days = next.SalesTermRef === null ? 30 : (TERMS.get(next.SalesTermRef.value)?.days ?? 30);
+    next.DueDate = dateFromDay(dayNumber(next.TxnDate) + days);
+  }
+  if (dayNumber(next.DueDate) < dayNumber(next.TxnDate)) s.fail("BUSINESS_VALIDATION", "The due date can't be earlier than the invoice date.", "DueDate");
+
+  const email = optEmail(s, body, "BillEmail");
+  if (email !== undefined) next.BillEmail = email;
+  else if (current === null) next.BillEmail = customer !== null ? customer.PrimaryEmailAddr : null;
+  else if (!sparse) next.BillEmail = null;
+  const addr = optAddr(s, body, "BillAddr");
+  if (addr !== undefined) next.BillAddr = addr;
+  else if (current === null) next.BillAddr = customer !== null ? customer.BillAddr : null;
+  else if (!sparse) next.BillAddr = null;
+
+  if (has(body, "CustomerMemo")) {
+    const memo = body.CustomerMemo;
+    if (memo === null) next.CustomerMemo = null;
+    else {
+      if (!isObject(memo) || Object.keys(memo).some((key) => key !== "value")) s.fail("BUSINESS_VALIDATION", "Invalid value for CustomerMemo: expected { value }", "CustomerMemo");
+      const text = optString(s, memo, "value", 1000);
+      next.CustomerMemo = typeof text === "string" ? { value: text } : null;
+    }
+  } else if (current === null || !sparse) next.CustomerMemo = null;
+  const note = optString(s, body, "PrivateNote", 4000);
+  if (note !== undefined) next.PrivateNote = note;
+  else if (current === null || !sparse) next.PrivateNote = null;
+
+  const emailStatus = optEnum(s, body, "EmailStatus", ["NotSet", "NeedToSend", "EmailSent"]);
+  if (emailStatus === "EmailSent" && next.EmailStatus !== "EmailSent") s.fail("BUSINESS_VALIDATION", "EmailStatus EmailSent is set by sending the invoice.", "EmailStatus");
+  if (emailStatus !== undefined) next.EmailStatus = emailStatus;
+  const printStatus = optEnum(s, body, "PrintStatus", ["NotSet", "NeedToPrint", "PrintComplete"]);
+  if (printStatus !== undefined) next.PrintStatus = printStatus;
+  if (has(body, "GlobalTaxCalculation") && body.GlobalTaxCalculation !== "NotApplicable") {
+    s.fail("BUSINESS_VALIDATION", "GlobalTaxCalculation is not applicable to this US company; only NotApplicable is accepted.", "GlobalTaxCalculation");
+  }
+  const currency = own(body, "CurrencyRef");
+  if (currency !== undefined && currency !== null && own(currency, "value") !== "USD") s.fail("BUSINESS_VALIDATION", "Multicurrency is not enabled for this company: CurrencyRef must be USD.", "CurrencyRef");
+  const docNumber = optString(s, body, "DocNumber", 21);
+  return { next, docNumber, customer };
+}

package/firedrill/tools/quickbooks/lib/invoices.mjs

@@ -0,0 +1,229 @@
+// Invoice entity: rendering (computed LinkedTxn and subtotal line), create / update / void / delete / send, and the
+// MCP argument mappings. Balances follow linked payments; every write bumps SyncToken and emits invoice.changed.
+import { NOT_FOUND_DETAIL, bumpToken, load, staleCheck } from "./access.mjs";
+import { RESERVED_KEYS, USD, clip, fromCents, padId, toCents } from "./common.mjs";
+import { updateTarget } from "./customers.mjs";
+import { has, isObject, own, validEmail } from "./fields.mjs";
+import { draftInvoice } from "./invoice-draft.mjs";
+import { refName } from "./items.mjs";
+
+export function renderInvoice(s, row) {
+  const links = s.applied().get(row.Id)?.paymentIds ?? [];
+  let subtotal = 0;
+  const lines = row.Line.map((line) => {
+    subtotal += toCents(line.Amount) ?? 0;
+    const detail = line.SalesItemLineDetail;
+    const out = {
+      Id: line.Id,
+      LineNum: line.LineNum,
+      Amount: line.Amount,
+      DetailType: "SalesItemLineDetail",
+      SalesItemLineDetail: { ItemRef: refName(s, "items", detail.ItemRef, "Name"), Qty: detail.Qty, UnitPrice: detail.UnitPrice, TaxCodeRef: detail.TaxCodeRef },
+    };
+    if (line.Description !== null) out.Description = line.Description;
+    if (detail.ServiceDate !== null) out.SalesItemLineDetail.ServiceDate = detail.ServiceDate;
+    return out;
+  });
+  lines.push({ Amount: fromCents(subtotal), DetailType: "SubTotalLineDetail", SubTotalLineDetail: {} });
+  const out = {
+    Id: row.Id,
+    SyncToken: row.SyncToken,
+    domain: "QBO",
+    sparse: false,
+    MetaData: row.MetaData,
+    DocNumber: row.DocNumber,
+    TxnDate: row.TxnDate,
+    DueDate: row.DueDate,
+    CurrencyRef: USD,
+    LinkedTxn: links.map((id) => ({ TxnId: id, TxnType: "Payment" })),
+    Line: lines,
+    TxnTaxDetail: { TotalTax: 0 },
+    CustomerRef: refName(s, "customers", row.CustomerRef, "DisplayName"),
+    TotalAmt: row.TotalAmt,
+    ApplyTaxAfterDiscount: false,
+    PrintStatus: row.PrintStatus,
+    EmailStatus: row.EmailStatus,
+    Balance: row.Balance,
+  };
+  for (const key of ["SalesTermRef", "BillEmail", "BillAddr", "CustomerMemo", "PrivateNote", "DeliveryInfo"]) if (row[key] !== null) out[key] = row[key];
+  return out;
+}
+
+export function saveInvoice(s, body, current, sparse, allowDuplicate) {
+  const { next, docNumber } = draftInvoice(s, body, current, sparse);
+  const applied = current === null ? 0 : (s.applied().get(current.Id)?.cents ?? 0);
+  if (current !== null && applied > 0 && next.CustomerRef.value !== current.CustomerRef.value) {
+    s.fail("BUSINESS_VALIDATION", "The customer can't be changed while payments are applied to this invoice.", "CustomerRef");
+  }
+  const total = toCents(next.TotalAmt) ?? 0;
+  if (total < applied) s.fail("BUSINESS_VALIDATION", `The invoice total can't be less than the ${fromCents(applied).toFixed(2)} already received for it.`, "Line");
+  next.Balance = fromCents(total - applied);
+  const invoices = s.rows("invoices");
+  if (typeof docNumber === "string") {
+    if (!allowDuplicate && (current === null || current.DocNumber !== docNumber)) {
+      const other = invoices.find((row) => row.DocNumber === docNumber && (current === null || row.Id !== current.Id));
+      if (other !== undefined) {
+        s.fail("DUPLICATE_DOC_NUMBER", `Duplicate Document Number Error : You must specify a different number. This number has already been used. DocNumber=${clip(docNumber, 21)} is assigned to TxnType=Invoice with TxnId=${other.Id}`, "DocNumber");
+      }
+    }
+    next.DocNumber = docNumber;
+  } else if (current === null) {
+    const used = new Set(invoices.map((row) => row.DocNumber));
+    let n = s.counter("docNumber");
+    while (used.has(String(n))) n += 1;
+    next.DocNumber = String(n);
+    s.setCounter("docNumber", n + 1);
+  }
+  if (current === null) {
+    next.Id = s.nextId("invoice", "invoices");
+    next.SyncToken = "0";
+    next.MetaData = { CreateTime: s.clock.meta, LastUpdatedTime: s.clock.meta };
+  } else {
+    next.SyncToken = bumpToken(current);
+    next.MetaData = { CreateTime: current.MetaData.CreateTime, LastUpdatedTime: s.clock.meta };
+  }
+  s.put("invoices", next);
+  s.emit("invoice.changed", "Invoice", next.Id, current === null ? "Create" : "Update");
+  return { row: next, action: current === null ? "create" : "update" };
+}
+
+/** Remove this invoice's lines from every payment linked to it (payments keep TotalAmt and become unapplied). */
+function unlinkPayments(s, invoiceId) {
+  const paymentIds = [...(s.applied().get(invoiceId)?.paymentIds ?? [])];
+  for (const paymentId of paymentIds) {
+    const payment = s.get("payments", paymentId);
+    if (payment === null) continue;
+    const lines = payment.Line.filter((line) => line.LinkedTxn[0].TxnId !== invoiceId);
+    s.put("payments", { ...payment, Line: lines, SyncToken: bumpToken(payment), MetaData: { ...payment.MetaData, LastUpdatedTime: s.clock.meta } });
+    s.emit("payment.changed", "Payment", paymentId, "Update");
+  }
+}
+
+export function voidInvoice(s, current) {
+  if (current.voided) s.fail("BUSINESS_VALIDATION", "This invoice is already voided.", "Id");
+  unlinkPayments(s, current.Id);
+  const next = {
+    ...current,
+    Line: current.Line.map((line) => ({ ...line, Amount: 0 })),
+    TotalAmt: 0,
+    Balance: 0,
+    voided: true,
+    PrivateNote: current.PrivateNote === null ? "Voided" : `Voided - ${current.PrivateNote}`.slice(0, 4000),
+    SyncToken: bumpToken(current),
+    MetaData: { ...current.MetaData, LastUpdatedTime: s.clock.meta },
+  };
+  s.put("invoices", next);
+  s.emit("invoice.changed", "Invoice", current.Id, "Void");
+  return { row: next, action: "void" };
+}
+
+export function deleteInvoice(s, current) {
+  unlinkPayments(s, current.Id);
+  s.remove("invoices", current.Id);
+  s.emit("invoice.changed", "Invoice", current.Id, "Delete");
+  return { row: current, action: "delete" };
+}
+
+export function sendInvoice(s, id, sendTo) {
+  const current = load(s, "invoices", id);
+  if (sendTo !== undefined) {
+    if (sendTo.includes(",") || sendTo.includes(";")) s.fail("BUSINESS_VALIDATION", "Only one e-mail address can be specified in sendTo.", "sendTo");
+    if (sendTo.includes("\uFFFD")) s.fail("BUSINESS_VALIDATION", "Invalid Email Address format : Please enter a valid email address.", "sendTo");
+    if (!validEmail(sendTo)) s.fail("BUSINESS_VALIDATION", "Invalid Email Address format : Please enter a valid email address.", "sendTo");
+  }
+  const address = sendTo ?? current.BillEmail?.Address;
+  if (address === undefined) s.fail("BUSINESS_VALIDATION", "Email address is missing: supply sendTo or set BillEmail on the invoice before sending it.", "BillEmail");
+  const prefix = `${padId(current.Id)}/`;
+  let count = 0;
+  for (const record of s.context.state.scan("deliveries", { afterRowId: prefix, limit: 10000 })) {
+    if (!record.rowId.startsWith(prefix)) break;
+    count += 1;
+  }
+  if (count >= 9999) s.fail("BUSINESS_VALIDATION", "This invoice has reached the supported number of sends.", "Id");
+  const next = {
+    ...current,
+    BillEmail: { Address: address },
+    EmailStatus: "EmailSent",
+    DeliveryInfo: { DeliveryType: "Email", DeliveryTime: s.clock.meta },
+    SyncToken: bumpToken(current),
+    MetaData: { ...current.MetaData, LastUpdatedTime: s.clock.meta },
+  };
+  s.put("invoices", next);
+  s.context.state.put("deliveries", `${prefix}${String(count + 1).padStart(4, "0")}`, {
+    invoiceId: current.Id,
+    sendTo: address,
+    deliveryTime: s.clock.meta,
+    actorId: s.context.actor.id,
+    source: "invoices.send",
+  });
+  s.emit("invoice.changed", "Invoice", current.Id, "Emailed");
+  return next;
+}
+
+export function invoicesPost(s, input) {
+  const operation = input.operation;
+  const body = input.body;
+  if (operation === undefined || operation === "update") {
+    const hasId = has(body, "Id") && body.Id !== null;
+    if (operation === "update" && !hasId) s.fail("REQUIRED_PARAM_MISSING", "Required param missing, need to supply the required value for the API: Id", "Id");
+    const current = hasId ? updateTarget(s, "invoices", body, "Id") : null;
+    if (has(body, "sparse") && typeof body.sparse !== "boolean") s.fail("BUSINESS_VALIDATION", "Invalid value for sparse: expected true or false", "sparse");
+    return saveInvoice(s, body, current, current !== null && body.sparse === true, input.include === "allowduplicatedocnum");
+  }
+  if (operation === "void" || operation === "delete") {
+    if (!isObject(body)) s.fail("REQUIRED_PARAM_MISSING", "Required param missing, need to supply the required value for the API: Invoice object", "Invoice");
+    const current = updateTarget(s, "invoices", body, "Id");
+    return operation === "void" ? voidInvoice(s, current) : deleteInvoice(s, current);
+  }
+  return s.fail("BUSINESS_VALIDATION", `Operation ${clip(String(operation), 32)} is not supported for Invoice.`, "operation");
+}
+
+/** create_invoice (MCP argument shape) → Invoice body. */
+export function invoiceBodyFromMcp(input) {
+  const body = {
+    CustomerRef: { value: input.customer_ref },
+    Line: (Array.isArray(input.line_items) ? input.line_items : []).map((item) => {
+      const detail = { ItemRef: { value: own(item, "item_ref") }, Qty: own(item, "qty"), UnitPrice: own(item, "unit_price") };
+      if (own(item, "tax_code_ref") !== undefined) detail.TaxCodeRef = { value: item.tax_code_ref };
+      if (own(item, "service_date") !== undefined) detail.ServiceDate = item.service_date;
+      const line = { DetailType: "SalesItemLineDetail", SalesItemLineDetail: detail };
+      if (own(item, "description") !== undefined) line.Description = item.description;
+      return line;
+    }),
+  };
+  if (input.doc_number !== undefined) body.DocNumber = input.doc_number;
+  if (input.txn_date !== undefined) body.TxnDate = input.txn_date;
+  if (input.customer_memo !== undefined) body.CustomerMemo = { value: input.customer_memo };
+  if (input.sales_term_ref !== undefined) body.SalesTermRef = { value: input.sales_term_ref };
+  if (input.bill_email !== undefined) body.BillEmail = { Address: input.bill_email };
+  if (input.global_tax_calculation !== undefined) body.GlobalTaxCalculation = input.global_tax_calculation;
+  return body;
+}
+
+/** update_invoice: sparse update of `patch`; a missing SyncToken means the current one (the MCP server reads it first). */
+export function updateInvoiceFromMcp(s, invoiceId, patch) {
+  const current = load(s, "invoices", invoiceId, "invoice_id");
+  if (!isObject(patch)) s.fail("BUSINESS_VALIDATION", "Invalid value for patch: expected an object", "patch");
+  for (const key of Object.keys(patch)) if (RESERVED_KEYS.has(key)) s.fail("BUSINESS_VALIDATION", `Request has invalid or unsupported property : Property Name:${key} specified is unsupported or invalid`, key);
+  const body = { ...patch, Id: current.Id, sparse: true };
+  const token = own(patch, "SyncToken");
+  body.SyncToken = token === undefined || token === null ? current.SyncToken : typeof token === "string" || typeof token === "number" ? String(token) : null;
+  staleCheck(s, current, body.SyncToken);
+  return saveInvoice(s, body, current, true, false);
+}
+
+export function entityRef(s, namespace, idOrEntity) {
+  let id = "";
+  let token;
+  if (typeof idOrEntity === "string") id = idOrEntity;
+  else if (isObject(idOrEntity)) {
+    const rawId = own(idOrEntity, "Id");
+    id = typeof rawId === "string" || typeof rawId === "number" ? String(rawId) : "";
+    const rawToken = own(idOrEntity, "SyncToken");
+    if (rawToken !== undefined) token = typeof rawToken === "string" || typeof rawToken === "number" ? String(rawToken) : null;
+  }
+  const row = s.get(namespace, id);
+  if (row === null) s.fail("OBJECT_NOT_FOUND", NOT_FOUND_DETAIL, "Id");
+  if (token !== undefined) staleCheck(s, row, token);
+  return row;
+}

package/firedrill/tools/quickbooks/lib/items.mjs

@@ -0,0 +1,117 @@
+// Item entity (Service and NonInventory only): rendering and create / full update / sparse update.
+import { bumpToken } from "./access.mjs";
+import { updateTarget } from "./customers.mjs";
+import { toScaled4 } from "./common.mjs";
+import { checkKeys, has, isObject, optBool, optRef, optString } from "./fields.mjs";
+
+const WRITABLE = new Set(["Name", "Sku", "Description", "Type", "UnitPrice", "IncomeAccountRef", "ExpenseAccountRef", "Taxable", "Active", "TrackQtyOnHand"]);
+const READONLY = new Set(["Id", "SyncToken", "sparse", "domain", "MetaData", "FullyQualifiedName", "PurchaseCost", "Level", "SubItem"]);
+
+export function refName(s, namespace, ref, field) {
+  if (ref === null) return null;
+  const target = s.get(namespace, ref.value);
+  return { value: ref.value, name: target === null ? ref.name : target[field] };
+}
+
+export function renderItem(s, row) {
+  const out = {
+    Name: row.Name,
+    Active: row.Active,
+    FullyQualifiedName: row.Name,
+    Taxable: row.Taxable,
+    UnitPrice: row.UnitPrice,
+    Type: row.Type,
+    IncomeAccountRef: refName(s, "accounts", row.IncomeAccountRef, "Name"),
+    PurchaseCost: 0,
+    TrackQtyOnHand: false,
+    domain: "QBO",
+    sparse: false,
+    Id: row.Id,
+    SyncToken: row.SyncToken,
+    MetaData: row.MetaData,
+  };
+  if (row.Description !== null) out.Description = row.Description;
+  if (row.Sku !== null) out.Sku = row.Sku;
+  if (row.ExpenseAccountRef !== null) out.ExpenseAccountRef = refName(s, "accounts", row.ExpenseAccountRef, "Name");
+  return out;
+}
+
+function accountRef(s, id, types, element) {
+  const account = s.get("accounts", id);
+  if (account === null || !account.Active || !types.includes(account.AccountType)) {
+    s.fail("INVALID_REFERENCE", `Invalid Reference Id : Account ${id} does not exist, is inactive or is not a ${types.join(" or ")} account.`, element);
+  }
+  return { value: account.Id, name: account.Name };
+}
+
+export function saveItem(s, body) {
+  if (!isObject(body)) s.fail("REQUIRED_PARAM_MISSING", "Required param missing, need to supply the required value for the API: Item object", "Item");
+  checkKeys(s, body, WRITABLE, READONLY);
+  const hasId = has(body, "Id") && body.Id !== null;
+  const current = hasId ? updateTarget(s, "items", body, "Id") : null;
+  if (has(body, "sparse") && typeof body.sparse !== "boolean") s.fail("BUSINESS_VALIDATION", "Invalid value for sparse: expected true or false", "sparse");
+  const sparse = current !== null && body.sparse === true;
+  const keep = (key) => sparse && !has(body, key);
+  const next = current === null ? { Id: "", SyncToken: "0", MetaData: null } : { ...current };
+
+  const name = optString(s, body, "Name", 100);
+  if (!keep("Name")) {
+    if (typeof name !== "string" || name.trim().length === 0) s.fail("REQUIRED_PARAM_MISSING", "Required param missing, need to supply the required value for the API: Name", "Name");
+    if (name.includes(":")) s.fail("BUSINESS_VALIDATION", "Invalid character in name : A name can't contain a colon (:).", "Name");
+    next.Name = name.trim();
+  }
+  if (!keep("Type")) {
+    const type = has(body, "Type") ? body.Type : null;
+    if (type === null || type === undefined) s.fail("REQUIRED_PARAM_MISSING", "Required param missing, need to supply the required value for the API: Type", "Type");
+    if (type === "Inventory" || type === "Group" || type === "Category") {
+      s.fail("BUSINESS_VALIDATION", `Item Type ${type} is not supported by this company. Use Service or NonInventory.`, "Type");
+    }
+    if (type !== "Service" && type !== "NonInventory") s.fail("BUSINESS_VALIDATION", "Invalid value for Type: expected Service or NonInventory", "Type");
+    if (current !== null && current.Type !== type) s.fail("BUSINESS_VALIDATION", "You can't change the type of an existing product or service.", "Type");
+    next.Type = type;
+  }
+  if (!keep("UnitPrice")) {
+    const price = has(body, "UnitPrice") && body.UnitPrice !== null ? body.UnitPrice : 0;
+    if (toScaled4(price, 999_999_999) === null) s.fail("BUSINESS_VALIDATION", "Invalid value for UnitPrice: expected a non-negative amount with at most four decimals", "UnitPrice");
+    next.UnitPrice = price;
+  }
+  if (!keep("IncomeAccountRef")) {
+    const income = optRef(s, body, "IncomeAccountRef");
+    if (typeof income !== "string") s.fail("REQUIRED_PARAM_MISSING", "Required param missing, need to supply the required value for the API: IncomeAccountRef", "IncomeAccountRef");
+    next.IncomeAccountRef = accountRef(s, income, ["Income"], "IncomeAccountRef");
+  }
+  if (!keep("ExpenseAccountRef")) {
+    const expense = optRef(s, body, "ExpenseAccountRef");
+    next.ExpenseAccountRef = typeof expense === "string" ? accountRef(s, expense, ["Cost of Goods Sold", "Expense"], "ExpenseAccountRef") : null;
+  }
+  for (const [key, max] of [["Sku", 100], ["Description", 4000]]) {
+    if (!keep(key)) {
+      const value = optString(s, body, key, max);
+      next[key] = value === undefined ? null : value;
+    }
+  }
+  for (const [key, fallback] of [["Taxable", false], ["Active", true]]) {
+    if (!keep(key)) {
+      const value = optBool(s, body, key);
+      next[key] = value === undefined ? fallback : value;
+    }
+  }
+  if (optBool(s, body, "TrackQtyOnHand") === true) {
+    s.fail("BUSINESS_VALIDATION", "Quantity on hand can only be tracked for Inventory items, which this company does not support.", "TrackQtyOnHand");
+  }
+  const fold = next.Name.toLowerCase();
+  for (const other of s.rows("items")) {
+    if (other.Id !== next.Id && other.Name.toLowerCase() === fold) {
+      s.fail("DUPLICATE_NAME", "The name supplied already exists. : Another product or service is already using this name. Please use a different name.", "Name");
+    }
+  }
+  if (current === null) {
+    next.Id = s.nextId("item", "items");
+    next.MetaData = { CreateTime: s.clock.meta, LastUpdatedTime: s.clock.meta };
+  } else {
+    next.SyncToken = bumpToken(current);
+    next.MetaData = { CreateTime: current.MetaData.CreateTime, LastUpdatedTime: s.clock.meta };
+  }
+  s.put("items", next);
+  return { row: next, action: current === null ? "create" : "update" };
+}

package/firedrill/tools/quickbooks/lib/like.mjs

@@ -0,0 +1,49 @@
+// LIKE matching with `%` wildcards in time linear in the value length: the pattern is split into
+// wildcard-free segments and each segment is located with a Knuth-Morris-Pratt search.
+
+function failureTable(segment) {
+  const table = new Array(segment.length).fill(0);
+  let k = 0;
+  for (let i = 1; i < segment.length; i += 1) {
+    while (k > 0 && segment[i] !== segment[k]) k = table[k - 1];
+    if (segment[i] === segment[k]) k += 1;
+    table[i] = k;
+  }
+  return table;
+}
+
+/** First index >= from where segment occurs in text, or -1. */
+function kmpFind(text, segment, from) {
+  if (segment.length === 0) return from;
+  const table = failureTable(segment);
+  let k = 0;
+  for (let i = from; i < text.length; i += 1) {
+    while (k > 0 && text[i] !== segment[k]) k = table[k - 1];
+    if (text[i] === segment[k]) k += 1;
+    if (k === segment.length) return i - segment.length + 1;
+  }
+  return -1;
+}
+
+/** Compile a LIKE pattern once (case-folded). */
+export function compileLike(pattern) {
+  const folded = pattern.toLowerCase();
+  const segments = folded.split("%");
+  return { segments, anchoredStart: !folded.startsWith("%"), anchoredEnd: !folded.endsWith("%") };
+}
+
+export function likeMatches(compiled, value) {
+  const text = value.toLowerCase();
+  const { segments } = compiled;
+  if (segments.length === 1) return text === segments[0];
+  const head = segments[0];
+  const tail = segments[segments.length - 1];
+  if (!text.startsWith(head)) return false;
+  let cursor = head.length;
+  for (let i = 1; i < segments.length - 1; i += 1) {
+    const found = kmpFind(text, segments[i], cursor);
+    if (found < 0) return false;
+    cursor = found + segments[i].length;
+  }
+  return text.length - tail.length >= cursor && text.endsWith(tail);
+}