@firedrill-tools/quickbooks 0.1.2

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

@@ -0,0 +1,107 @@
+// MCP search criteria → query AST. Accepted forms: a simple object of equalities, an array of
+// { field, value, operator? } (or legacy { key, value }), or { filters | criteria: [...], asc, desc, limit, offset,
+// count, fetchAll }. Option names inside the array form are options, not conditions. Values never become query text.
+import { dayNumber } from "./common.mjs";
+import { isObject, own } from "./fields.mjs";
+
+const OPTIONS = new Set(["limit", "offset", "asc", "desc", "count", "fetchAll"]);
+const OPERATORS = new Map([["=", "="], ["<", "<"], [">", ">"], ["<=", "<="], [">=", ">="], ["like", "like"], ["in", "in"]]);
+
+function bad(s, detail) {
+  return s.fail("QUERY_VALIDATION_ERROR", `QueryValidationError: ${detail}`, "criteria");
+}
+
+function literal(s, field, value) {
+  if (typeof value === "string") return { kind: "string", value };
+  if (typeof value === "number" && Number.isFinite(value)) return { kind: "number", value: String(value) };
+  if (typeof value === "boolean") return { kind: "bool", value };
+  return bad(s, `value for '${String(field).slice(0, 64)}' must be a string, number or boolean`);
+}
+
+function condition(s, field, value, operator) {
+  if (typeof field !== "string" || field.length === 0 || field.length > 64) return bad(s, "each criterion needs a field name");
+  const op = operator === undefined || operator === null ? (Array.isArray(value) ? "in" : "=") : typeof operator === "string" ? OPERATORS.get(operator.toLowerCase()) : undefined;
+  if (op === undefined) return bad(s, `operator ${JSON.stringify(String(operator)).slice(0, 40)} is not supported`);
+  if (op === "in") {
+    if (!Array.isArray(value) || value.length === 0 || value.length > 100) return bad(s, `IN for '${field}' needs 1 to 100 values`);
+    return { prop: field, op, values: value.map((item) => literal(s, field, item)) };
+  }
+  return { prop: field, op, values: [literal(s, field, value)] };
+}
+
+function applyOption(s, options, name, value) {
+  if (name === "limit") {
+    if (!Number.isInteger(value) || value < 1 || value > 1000) bad(s, "limit must be an integer between 1 and 1000");
+    options.limit = value;
+  } else if (name === "offset") {
+    if (!Number.isInteger(value) || value < 0 || value > 1_000_000) bad(s, "offset must be a non-negative integer");
+    options.offset = value;
+  } else if (name === "asc" || name === "desc") {
+    if (typeof value !== "string" || value.length === 0 || value.length > 64) bad(s, `${name} must name a sortable property`);
+    options.order.push({ prop: value, dir: name });
+    if (options.order.length > 3) bad(s, "at most 3 sort keys are supported");
+  } else {
+    if (typeof value !== "boolean") bad(s, `${name} must be true or false`);
+    options[name] = value;
+  }
+}
+
+function fromArray(s, entries, options, where) {
+  if (entries.length > 50) bad(s, "at most 50 criteria entries are supported");
+  for (const entry of entries) {
+    if (!isObject(entry)) bad(s, "each criterion must be an object");
+    const field = own(entry, "field") ?? own(entry, "key");
+    const value = own(entry, "value");
+    if (typeof field === "string" && OPTIONS.has(field)) applyOption(s, options, field, value);
+    else where.push(condition(s, field, value, own(entry, "operator")));
+  }
+}
+
+/** Compile criteria plus optional top-level options (search_customers) into { ast, all, count }. */
+export function compileCriteria(s, entity, criteria, topLevel = {}) {
+  const options = { limit: undefined, offset: undefined, order: [], count: false, fetchAll: false };
+  const where = [];
+  if (Array.isArray(criteria)) fromArray(s, criteria, options, where);
+  else if (isObject(criteria)) {
+    const list = own(criteria, "filters") ?? own(criteria, "criteria");
+    if (Array.isArray(list)) {
+      fromArray(s, list, options, where);
+      for (const name of OPTIONS) if (own(criteria, name) !== undefined) applyOption(s, options, name, criteria[name]);
+    } else {
+      const keys = Object.keys(criteria);
+      if (keys.length > 50) bad(s, "at most 50 criteria entries are supported");
+      for (const key of keys) {
+        if (key === "filters" || key === "criteria") bad(s, `${key} must be an array`);
+        if (OPTIONS.has(key)) applyOption(s, options, key, criteria[key]);
+        else where.push(condition(s, key, criteria[key], undefined));
+      }
+    }
+  } else if (criteria !== undefined && criteria !== null) bad(s, "criteria must be an object or an array");
+  for (const name of OPTIONS) if (topLevel[name] !== undefined) applyOption(s, options, name, topLevel[name]);
+  if (where.length > 20) bad(s, "at most 20 conditions are supported");
+  const ast = {
+    entity,
+    select: { kind: options.count ? "count" : "all" },
+    where,
+    order: options.order,
+    start: (options.offset ?? 0) + 1,
+    max: options.limit ?? 100,
+  };
+  return { ast, all: options.fetchAll, count: options.count };
+}
+
+/** search_payments { customer_ref, txn_date_from, txn_date_to, limit } → AST (dates inclusive). */
+export function paymentSearchAst(s, input) {
+  const where = [];
+  if (input.customer_ref !== undefined) where.push({ prop: "CustomerRef", op: "=", values: [{ kind: "string", value: input.customer_ref }] });
+  const from = input.txn_date_from === undefined ? null : dayNumber(input.txn_date_from);
+  const to = input.txn_date_to === undefined ? null : dayNumber(input.txn_date_to);
+  if (input.txn_date_from !== undefined && from === null) bad(s, "txn_date_from must be a valid YYYY-MM-DD date");
+  if (input.txn_date_to !== undefined && to === null) bad(s, "txn_date_to must be a valid YYYY-MM-DD date");
+  if (from !== null && to !== null && from > to) bad(s, "txn_date_from is after txn_date_to");
+  if (from !== null) where.push({ prop: "TxnDate", op: ">=", values: [{ kind: "string", value: input.txn_date_from }] });
+  if (to !== null) where.push({ prop: "TxnDate", op: "<=", values: [{ kind: "string", value: input.txn_date_to }] });
+  const limit = input.limit ?? 100;
+  if (!Number.isInteger(limit) || limit < 1 || limit > 1000) bad(s, "limit must be an integer between 1 and 1000");
+  return { entity: "Payment", select: { kind: "all" }, where, order: [{ prop: "TxnDate", dir: "desc" }], start: 1, max: limit };
+}

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

@@ -0,0 +1,140 @@
+// Customer entity: rendering (computed Balance) and create / full update / sparse update / make inactive.
+import { bumpToken, load, staleCheck } from "./access.mjs";
+import { TERMS, USD, fromCents, toCents } from "./common.mjs";
+import { checkKeys, has, isObject, optAddr, optBool, optEmail, optEnum, optPhone, optRef, optString, own } from "./fields.mjs";
+
+const TEXT_FIELDS = [["DisplayName", 500], ["Title", 16], ["GivenName", 100], ["MiddleName", 100], ["FamilyName", 100], ["Suffix", 16], ["CompanyName", 100], ["PrintOnCheckName", 110], ["Notes", 2000]];
+const NULLABLE = ["Title", "GivenName", "MiddleName", "FamilyName", "Suffix", "CompanyName", "PrimaryEmailAddr", "PrimaryPhone", "Mobile", "BillAddr", "ShipAddr", "Notes", "SalesTermRef", "PaymentMethodRef"];
+const WRITABLE = new Set([...TEXT_FIELDS.map(([name]) => name), "PrimaryEmailAddr", "PrimaryPhone", "Mobile", "BillAddr", "ShipAddr", "Taxable", "PreferredDeliveryMethod", "SalesTermRef", "PaymentMethodRef", "Active"]);
+const READONLY = new Set(["Id", "SyncToken", "sparse", "domain", "MetaData", "FullyQualifiedName", "Balance", "BalanceWithJobs", "Job", "BillWithParent", "CurrencyRef"]);
+
+export function renderCustomer(s, row) {
+  const balance = fromCents(s.balances().get(row.Id) ?? 0);
+  const out = {
+    Taxable: row.Taxable,
+    Job: false,
+    BillWithParent: false,
+    Balance: balance,
+    BalanceWithJobs: balance,
+    CurrencyRef: USD,
+    PreferredDeliveryMethod: row.PreferredDeliveryMethod,
+    domain: "QBO",
+    sparse: false,
+    Id: row.Id,
+    SyncToken: row.SyncToken,
+    MetaData: row.MetaData,
+    FullyQualifiedName: row.DisplayName,
+    DisplayName: row.DisplayName,
+    PrintOnCheckName: row.PrintOnCheckName ?? row.DisplayName,
+    Active: row.Active,
+  };
+  for (const key of NULLABLE) if (row[key] !== null) out[key] = row[key];
+  if (row.SalesTermRef !== null) out.SalesTermRef = { value: row.SalesTermRef.value, name: TERMS.get(row.SalesTermRef.value)?.name ?? row.SalesTermRef.name };
+  return out;
+}
+
+function blank() {
+  const row = { Id: "", SyncToken: "0", DisplayName: null, PrintOnCheckName: null, Taxable: false, PreferredDeliveryMethod: "Print", Active: true, MetaData: null };
+  for (const key of NULLABLE) row[key] = null;
+  return row;
+}
+
+/** Id + SyncToken of an update body, loaded and stale-checked. */
+export function updateTarget(s, namespace, body, element) {
+  if (!has(body, "Id") || body.Id === null) s.fail("REQUIRED_PARAM_MISSING", "Required param missing, need to supply the required value for the API: Id", "Id");
+  if (!has(body, "SyncToken") || body.SyncToken === null) s.fail("REQUIRED_PARAM_MISSING", "Required param missing, need to supply the required value for the API: SyncToken", "SyncToken");
+  const id = typeof body.Id === "string" || typeof body.Id === "number" ? String(body.Id) : "";
+  const row = load(s, namespace, id, element);
+  staleCheck(s, row, typeof body.SyncToken === "string" || typeof body.SyncToken === "number" ? String(body.SyncToken) : null);
+  return row;
+}
+
+/** Create (no Id) or update (Id + SyncToken). `intent` "create" refuses an Id, "update" requires one. */
+export function saveCustomer(s, body, intent) {
+  if (!isObject(body)) s.fail("REQUIRED_PARAM_MISSING", "Required param missing, need to supply the required value for the API: Customer object", "Customer");
+  checkKeys(s, body, WRITABLE, READONLY);
+  const hasId = has(body, "Id") && body.Id !== null;
+  if (intent === "create" && hasId) s.fail("BUSINESS_VALIDATION", "Id is assigned by QuickBooks and cannot be supplied when creating a customer.", "Id");
+  const current = intent === "update" || hasId ? updateTarget(s, "customers", 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 next = { ...(current ?? blank()) };
+  const assign = (key, value, reset) => {
+    if (value !== undefined) next[key] = value;
+    else if (current !== null && !sparse) next[key] = reset;
+  };
+  for (const [key, max] of TEXT_FIELDS) assign(key, optString(s, body, key, max), null);
+  assign("PrimaryEmailAddr", optEmail(s, body, "PrimaryEmailAddr"), null);
+  assign("PrimaryPhone", optPhone(s, body, "PrimaryPhone"), null);
+  assign("Mobile", optPhone(s, body, "Mobile"), null);
+  assign("BillAddr", optAddr(s, body, "BillAddr"), null);
+  assign("ShipAddr", optAddr(s, body, "ShipAddr"), null);
+  assign("Taxable", optBool(s, body, "Taxable"), false);
+  assign("PreferredDeliveryMethod", optEnum(s, body, "PreferredDeliveryMethod", ["Print", "Email", "None"]), "Print");
+  assign("Active", optBool(s, body, "Active"), true);
+  const term = optRef(s, body, "SalesTermRef");
+  if (typeof term === "string" && !TERMS.has(term)) s.fail("INVALID_REFERENCE", `Invalid Reference Id : Term assigned to this customer does not exist: ${term}`, "SalesTermRef");
+  assign("SalesTermRef", typeof term === "string" ? { value: term, name: TERMS.get(term).name } : term, null);
+  const method = optRef(s, body, "PaymentMethodRef");
+  const methodName = own(body.PaymentMethodRef, "name");
+  assign("PaymentMethodRef", typeof method === "string" ? { value: method, name: typeof methodName === "string" ? methodName.slice(0, 100) : null } : method, null);
+  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");
+  }
+  let display = typeof next.DisplayName === "string" ? next.DisplayName.trim() : "";
+  if (display.length === 0) {
+    display = ["Title", "GivenName", "MiddleName", "FamilyName", "Suffix"].map((key) => next[key]).filter((part) => typeof part === "string" && part.trim().length > 0).map((part) => part.trim()).join(" ");
+    if (display.length === 0 && typeof next.CompanyName === "string") display = next.CompanyName.trim();
+  }
+  if (display.length === 0) s.fail("REQUIRED_PARAM_MISSING", "Required param missing, need to supply the required value for the API: DisplayName or a name part", "DisplayName");
+  if (display.includes(":")) s.fail("BUSINESS_VALIDATION", "Invalid character in name : A name can't contain a colon (:).", "DisplayName");
+  next.DisplayName = display.slice(0, 500);
+  const fold = next.DisplayName.toLowerCase();
+  for (const other of s.rows("customers")) {
+    if (other.Id !== next.Id && other.DisplayName.trim().toLowerCase() === fold) {
+      s.fail("DUPLICATE_NAME", "The name supplied already exists. : Another customer is already using this name. Please use a different name.", "DisplayName");
+    }
+  }
+  const openCents = current === null ? 0 : (s.balances().get(current.Id) ?? 0);
+  if (has(body, "Balance") && toCents(body.Balance, { allowNegative: true }) !== openCents) {
+    s.fail("BUSINESS_VALIDATION", "Balance is read-only: it is computed from open invoices and cannot be set on a customer.", "Balance");
+  }
+  if (current !== null && current.Active && next.Active === false && openCents > 0) {
+    s.fail("BUSINESS_VALIDATION", "This customer has an open balance. Receive payment or void the open invoices before making the customer inactive.", "Active");
+  }
+  return commitCustomer(s, current, next);
+}
+
+function commitCustomer(s, current, next) {
+  if (current === null) {
+    next.Id = s.nextId("customer", "customers");
+    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("customers", next);
+  s.emit("customer.changed", "Customer", next.Id, current === null ? "Create" : "Update");
+  return { row: next, action: current === null ? "create" : "update" };
+}
+
+/** delete_customer: QuickBooks has no customer delete, so this makes the customer inactive. */
+export function deactivateCustomer(s, 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 current = load(s, "customers", id);
+  if (token !== undefined) staleCheck(s, current, token);
+  if ((s.balances().get(current.Id) ?? 0) > 0) {
+    s.fail("BUSINESS_VALIDATION", "This customer has an open balance. Receive payment or void the open invoices before making the customer inactive.", "Active");
+  }
+  return commitCustomer(s, current, { ...current, Active: false });
+}

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

@@ -0,0 +1,157 @@
+// Validation of caller-supplied QuickBooks entity JSON. Every helper reads own properties only and answers the
+// provider's business-validation fault for a wrong shape, so no caller value can crash a handler.
+import { RESERVED_KEYS, clip, dayNumber, isId, toCents } from "./common.mjs";
+
+export function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+export function has(object, key) {
+  return isObject(object) && Object.hasOwn(object, key);
+}
+
+export function own(object, key) {
+  return has(object, key) ? object[key] : undefined;
+}
+
+/** Refuse unknown or reserved top-level properties. `readonly` names are accepted and ignored. */
+export function checkKeys(s, body, writable, readonly) {
+  for (const key of Object.keys(body)) {
+    if (RESERVED_KEYS.has(key) || (!writable.has(key) && !readonly.has(key))) {
+      s.fail("BUSINESS_VALIDATION", `Request has invalid or unsupported property : Property Name:${clip(key, 80)} specified is unsupported or invalid`, clip(key, 80));
+    }
+  }
+}
+
+function invalid(s, key, what) {
+  return s.fail("BUSINESS_VALIDATION", `Invalid value for ${key}: ${what}`, key);
+}
+
+/** undefined when absent, null when null or empty, otherwise a string no longer than max. */
+export function optString(s, body, key, max) {
+  if (!has(body, key)) return undefined;
+  const value = body[key];
+  if (value === null) return null;
+  if (typeof value !== "string") return invalid(s, key, "expected a string");
+  if (value.length > max) return s.fail("BUSINESS_VALIDATION", `String length is either shorter or longer than supported by specification. Min:0 Max:${max} supported. Supplied length:${value.length}`, key);
+  return value.length === 0 ? null : value;
+}
+
+export function optBool(s, body, key) {
+  if (!has(body, key)) return undefined;
+  const value = body[key];
+  if (typeof value !== "boolean") return invalid(s, key, "expected true or false");
+  return value;
+}
+
+export function optEnum(s, body, key, allowed) {
+  if (!has(body, key)) return undefined;
+  const value = body[key];
+  if (typeof value !== "string" || !allowed.includes(value)) return invalid(s, key, `expected one of ${allowed.join(", ")}`);
+  return value;
+}
+
+export function optDate(s, body, key) {
+  if (!has(body, key)) return undefined;
+  const value = body[key];
+  if (value === null) return null;
+  if (dayNumber(value) === null) return invalid(s, key, "expected a date formatted YYYY-MM-DD");
+  return value;
+}
+
+/** Reference `{ value, name? }`; returns undefined / null / the id string. */
+export function optRef(s, body, key) {
+  if (!has(body, key)) return undefined;
+  const value = body[key];
+  if (value === null) return null;
+  if (!isObject(value)) return invalid(s, key, "expected an object with a value");
+  for (const inner of Object.keys(value)) {
+    if (inner !== "value" && inner !== "name" && inner !== "type") return invalid(s, key, `unsupported property ${clip(inner, 40)}`);
+  }
+  const id = value.value;
+  if (typeof id !== "string" || id.length === 0 || id.length > 64) return invalid(s, key, "value must be a non-empty string");
+  return id;
+}
+
+export function validEmail(text) {
+  if (typeof text !== "string" || text.length < 3 || text.length > 100) return false;
+  const at = text.indexOf("@");
+  if (at <= 0 || at !== text.lastIndexOf("@") || at === text.length - 1) return false;
+  for (const char of text) {
+    const code = char.charCodeAt(0);
+    if (code <= 32 || char === "," || char === ";" || char === "<" || char === ">" || char === "\"") return false;
+  }
+  const domain = text.slice(at + 1);
+  return domain.includes(".") && !domain.startsWith(".") && !domain.endsWith(".");
+}
+
+export function optEmail(s, body, key) {
+  if (!has(body, key)) return undefined;
+  const value = body[key];
+  if (value === null) return null;
+  if (!isObject(value) || Object.keys(value).some((inner) => inner !== "Address")) return invalid(s, key, "expected { Address }");
+  if (value.Address === null || value.Address === undefined || value.Address === "") return null;
+  if (!validEmail(value.Address)) return s.fail("BUSINESS_VALIDATION", "Invalid Email Address format : Please enter a valid email address.", `${key}.Address`);
+  return { Address: value.Address };
+}
+
+export function optPhone(s, body, key) {
+  if (!has(body, key)) return undefined;
+  const value = body[key];
+  if (value === null) return null;
+  if (!isObject(value) || Object.keys(value).some((inner) => inner !== "FreeFormNumber")) return invalid(s, key, "expected { FreeFormNumber }");
+  const number = value.FreeFormNumber;
+  if (number === null || number === undefined || number === "") return null;
+  if (typeof number !== "string" || number.length > 30) return invalid(s, `${key}.FreeFormNumber`, "expected a string of at most 30 characters");
+  return { FreeFormNumber: number };
+}
+
+const ADDR_FIELDS = [["Line1", 500], ["Line2", 500], ["City", 255], ["CountrySubDivisionCode", 255], ["PostalCode", 30], ["Country", 255]];
+
+export function optAddr(s, body, key) {
+  if (!has(body, key)) return undefined;
+  const value = body[key];
+  if (value === null) return null;
+  if (!isObject(value)) return invalid(s, key, "expected an address object");
+  const out = { Id: null, Line1: null, Line2: null, City: null, CountrySubDivisionCode: null, PostalCode: null, Country: null };
+  for (const inner of Object.keys(value)) {
+    if (inner === "Id") {
+      if (value.Id !== null && !isId(value.Id)) return invalid(s, `${key}.Id`, "expected a numeric id");
+      out.Id = value.Id;
+      continue;
+    }
+    const spec = ADDR_FIELDS.find(([name]) => name === inner);
+    if (spec === undefined) return invalid(s, key, `unsupported property ${clip(inner, 40)}`);
+    const text = optString(s, value, inner, spec[1]);
+    out[inner] = text === undefined ? null : text;
+  }
+  return out;
+}
+
+/** Money: number with at most two decimals. */
+export function optMoney(s, body, key, { allowNegative = false } = {}) {
+  if (!has(body, key)) return undefined;
+  const cents = toCents(body[key], { allowNegative });
+  if (cents === null) return invalid(s, key, "expected an amount with at most two decimals");
+  return cents;
+}
+
+/** Deep-check a caller object for reserved keys (iterative; bounded by the framework body size). */
+export function reservedKeyIn(value) {
+  const stack = [value];
+  let visited = 0;
+  while (stack.length > 0) {
+    const current = stack.pop();
+    if (++visited > 100_000) return "the request body has too many values";
+    if (Array.isArray(current)) {
+      for (const item of current) if (item !== null && typeof item === "object") stack.push(item);
+    } else if (current !== null && typeof current === "object") {
+      for (const key of Object.keys(current)) {
+        if (RESERVED_KEYS.has(key)) return `the property name ${key} is not allowed`;
+        const inner = current[key];
+        if (inner !== null && typeof inner === "object") stack.push(inner);
+      }
+    }
+  }
+  return null;
+}

package/firedrill/tools/quickbooks/lib/handlers-read.mjs

@@ -0,0 +1,81 @@
+// Read operations: company info, the query endpoint, entity reads, MCP-shaped searches and the invoice PDF.
+import { NOT_FOUND_DETAIL, load, open } from "./access.mjs";
+import { compileCriteria, paymentSearchAst } from "./criteria.mjs";
+import { renderCustomer } from "./customers.mjs";
+import { renderInvoice } from "./invoices.mjs";
+import { renderItem } from "./items.mjs";
+import { base64FromBinary, invoicePdf } from "./pdf.mjs";
+import { renderPayment } from "./payments.mjs";
+import { parseQuery } from "./query-parse.mjs";
+import { evaluate } from "./query-eval.mjs";
+import { renderAccount, renderCompany } from "./views.mjs";
+
+function search(s, entity, criteria, topLevel) {
+  const { ast, all, count } = compileCriteria(s, entity, criteria, topLevel);
+  const { entities, total } = evaluate(s, ast, { all });
+  return count ? { results: [], totalCount: total } : { results: entities };
+}
+
+export const readOperations = {
+  "company-info.get": (input, context) => {
+    const s = open(context, input, "company.read");
+    if (input.company_id !== undefined && input.company_id !== s.company.Id && input.company_id !== s.realmId) {
+      s.fail("OBJECT_NOT_FOUND", NOT_FOUND_DETAIL, "Id");
+    }
+    return { CompanyInfo: renderCompany(s.company), time: s.clock.time };
+  },
+  "query.run": (input, context) => {
+    const s = open(context, input, "query");
+    const ast = parseQuery(input.query, (detail) => s.fail("QUERY_PARSE_ERROR", detail, "query"));
+    const { meta, entities, total } = evaluate(s, ast);
+    let response;
+    if (ast.select.kind === "count") response = { totalCount: total };
+    else if (entities.length === 0) response = {};
+    else {
+      response = { startPosition: ast.start, maxResults: entities.length };
+      response[meta.name] = entities;
+    }
+    return { QueryResponse: response, time: s.clock.time };
+  },
+  "customers.get": (input, context) => {
+    const s = open(context, input, "customers.read");
+    return { Customer: renderCustomer(s, load(s, "customers", input.id)), time: s.clock.time };
+  },
+  "customers.search": (input, context) => {
+    const s = open(context, input, "customers.read");
+    const topLevel = { limit: input.limit, offset: input.offset, asc: input.asc, desc: input.desc, fetchAll: input.fetchAll, count: input.count };
+    return search(s, "Customer", input.criteria, topLevel);
+  },
+  "items.get": (input, context) => {
+    const s = open(context, input, "items.read");
+    return { Item: renderItem(s, load(s, "items", input.item_id, "item_id")), time: s.clock.time };
+  },
+  "items.search": (input, context) => search(open(context, input, "items.read"), "Item", input.criteria, {}),
+  "invoices.get": (input, context) => {
+    const s = open(context, input, "invoices.read");
+    return { Invoice: renderInvoice(s, load(s, "invoices", input.invoice_id, "invoice_id")), time: s.clock.time };
+  },
+  "invoices.search": (input, context) => search(open(context, input, "invoices.read"), "Invoice", input.criteria, {}),
+  "invoices.pdf": (input, context) => {
+    const s = open(context, input, "invoices.read");
+    const row = load(s, "invoices", input.invoice_id, "invoice_id");
+    if (input.output_path !== undefined) {
+      s.fail("BUSINESS_VALIDATION", "output_path is not supported: a Firedrill Tool cannot write files; use the returned base64 content.", "output_path");
+    }
+    const file = invoicePdf(s.company, renderInvoice(s, row));
+    return { invoice_id: row.Id, content_type: "application/pdf", size_bytes: file.length, base64: base64FromBinary(file) };
+  },
+  "payments.get": (input, context) => {
+    const s = open(context, input, "payments.read");
+    return { Payment: renderPayment(s, load(s, "payments", input.id)), time: s.clock.time };
+  },
+  "payments.search": (input, context) => {
+    const s = open(context, input, "payments.read");
+    return { results: evaluate(s, paymentSearchAst(s, input)).entities };
+  },
+  "accounts.get": (input, context) => {
+    const s = open(context, input, "accounts.read");
+    return { Account: renderAccount(s, load(s, "accounts", input.id)), time: s.clock.time };
+  },
+  "accounts.search": (input, context) => search(open(context, input, "accounts.read"), "Account", input.criteria, {}),
+};

package/firedrill/tools/quickbooks/lib/handlers-write.mjs

@@ -0,0 +1,95 @@
+// Write operations: REST dispatchers (`*.post`) and the MCP-shaped create / update / delete / send variants.
+import { open } from "./access.mjs";
+import { clip } from "./common.mjs";
+import { deactivateCustomer, renderCustomer, saveCustomer } from "./customers.mjs";
+import { has, reservedKeyIn } from "./fields.mjs";
+import { deleteInvoice, entityRef, invoiceBodyFromMcp, invoicesPost, renderInvoice, saveInvoice, sendInvoice, updateInvoiceFromMcp } from "./invoices.mjs";
+import { renderItem, saveItem } from "./items.mjs";
+import { paymentBodyFromMcp, paymentsPost, renderPayment, savePayment } from "./payments.mjs";
+
+function guardBody(s, value) {
+  const problem = reservedKeyIn(value);
+  if (problem !== null) s.fail("BUSINESS_VALIDATION", `Request has invalid or unsupported property : ${problem}`, "body");
+}
+
+function onlyUpdate(s, input, entity) {
+  if (input.operation !== undefined && input.operation !== "update") {
+    s.fail("BUSINESS_VALIDATION", `Operation ${clip(String(input.operation), 32)} is not supported for ${entity}.`, "operation");
+  }
+  if (input.operation === "update" && !(has(input.body, "Id") && input.body.Id !== null)) {
+    s.fail("REQUIRED_PARAM_MISSING", "Required param missing, need to supply the required value for the API: Id", "Id");
+  }
+}
+
+const deleted = (row) => ({ Id: row.Id, status: "Deleted", domain: "QBO" });
+
+export const writeOperations = {
+  "customers.post": (input, context) => {
+    const s = open(context, input, "customers.write");
+    guardBody(s, input.body);
+    onlyUpdate(s, input, "Customer");
+    const { row, action } = saveCustomer(s, input.body, input.operation === "update" ? "update" : undefined);
+    return { Customer: renderCustomer(s, row), action, time: s.clock.time };
+  },
+  "customers.create": (input, context) => {
+    const s = open(context, input, "customers.write");
+    guardBody(s, input.customer);
+    return renderCustomer(s, saveCustomer(s, input.customer, "create").row);
+  },
+  "customers.update": (input, context) => {
+    const s = open(context, input, "customers.write");
+    guardBody(s, input.customer);
+    return renderCustomer(s, saveCustomer(s, input.customer, "update").row);
+  },
+  "customers.delete": (input, context) => {
+    const s = open(context, input, "customers.write");
+    return renderCustomer(s, deactivateCustomer(s, input.idOrEntity).row);
+  },
+  "items.post": (input, context) => {
+    const s = open(context, input, "items.write");
+    guardBody(s, input.body);
+    onlyUpdate(s, input, "Item");
+    const { row, action } = saveItem(s, input.body);
+    return { Item: renderItem(s, row), action, time: s.clock.time };
+  },
+  "invoices.post": (input, context) => {
+    const s = open(context, input, "invoices.write");
+    guardBody(s, input.body);
+    const { row, action } = invoicesPost(s, input);
+    return { Invoice: action === "delete" ? deleted(row) : renderInvoice(s, row), action, time: s.clock.time };
+  },
+  "invoices.create": (input, context) => {
+    const s = open(context, input, "invoices.write");
+    if (input.linked_txn !== undefined && input.linked_txn.length > 0) {
+      s.fail("BUSINESS_VALIDATION", "linked_txn is not supported: estimates and other linkable transactions are not modelled by this company.", "linked_txn");
+    }
+    const body = invoiceBodyFromMcp(input);
+    guardBody(s, body);
+    return renderInvoice(s, saveInvoice(s, body, null, false, false).row);
+  },
+  "invoices.update": (input, context) => {
+    const s = open(context, input, "invoices.write");
+    guardBody(s, input.patch);
+    return renderInvoice(s, updateInvoiceFromMcp(s, input.invoice_id, input.patch).row);
+  },
+  "invoices.delete": (input, context) => {
+    const s = open(context, input, "invoices.write");
+    return deleted(deleteInvoice(s, entityRef(s, "invoices", input.idOrEntity)).row);
+  },
+  "invoices.send": (input, context) => {
+    const s = open(context, input, "invoices.write");
+    return { Invoice: renderInvoice(s, sendInvoice(s, input.invoice_id, input.sendTo)), time: s.clock.time };
+  },
+  "payments.post": (input, context) => {
+    const s = open(context, input, "payments.write");
+    guardBody(s, input.body);
+    const { row, action } = paymentsPost(s, input);
+    return { Payment: action === "delete" ? deleted(row) : renderPayment(s, row), action, time: s.clock.time };
+  },
+  "payments.create": (input, context) => {
+    const s = open(context, input, "payments.write");
+    const body = paymentBodyFromMcp(input);
+    guardBody(s, body);
+    return renderPayment(s, savePayment(s, body, null, false).row);
+  },
+};