@firedrill-tools/quickbooks 0.1.2

package/firedrill/tools/quickbooks/lib/query-parse.mjs

@@ -0,0 +1,229 @@
+// QuickBooks query language: hand-written tokenizer and parser (no regular expressions over caller text).
+// select (* | count(*) | prop[, prop]) from Entity [where cond (and cond)*] [orderby prop [asc|desc], …]
+// [startposition n] [maxresults n]. Failures raise QUERY_PARSE_ERROR with QuickBooks' parser wording.
+
+export const MAX_QUERY_LENGTH = 20000;
+const MAX_CONDITIONS = 20;
+const MAX_IN_VALUES = 100;
+const MAX_SORT_KEYS = 3;
+
+function isLetter(code) {
+  return (code >= 65 && code <= 90) || (code >= 97 && code <= 122) || code === 95;
+}
+function isDigit(code) {
+  return code >= 48 && code <= 57;
+}
+
+/** Tokens: { type: "word" | "string" | "number" | "punct", value, column }. */
+export function tokenize(text, parseFail) {
+  const tokens = [];
+  let i = 0;
+  while (i < text.length) {
+    const code = text.charCodeAt(i);
+    const column = i + 1;
+    if (code === 32 || code === 9 || code === 10 || code === 13) {
+      i += 1;
+    } else if (code === 0xfffd) {
+      parseFail(`QueryParserError: Invalid character in query at line 1, column ${column}.`);
+    } else if (isLetter(code)) {
+      let j = i + 1;
+      while (j < text.length) {
+        const c = text.charCodeAt(j);
+        if (isLetter(c) || isDigit(c) || c === 46) j += 1;
+        else break;
+      }
+      tokens.push({ type: "word", value: text.slice(i, j), column });
+      i = j;
+    } else if (isDigit(code) || (code === 45 && i + 1 < text.length && isDigit(text.charCodeAt(i + 1)))) {
+      let j = i + 1;
+      while (j < text.length && (isDigit(text.charCodeAt(j)) || text.charCodeAt(j) === 46)) j += 1;
+      tokens.push({ type: "number", value: text.slice(i, j), column });
+      i = j;
+    } else if (code === 39) {
+      let value = "";
+      let j = i + 1;
+      let closed = false;
+      while (j < text.length) {
+        const c = text.charCodeAt(j);
+        if (c === 92 && j + 1 < text.length) {
+          value += text[j + 1];
+          j += 2;
+        } else if (c === 39) {
+          closed = true;
+          j += 1;
+          break;
+        } else {
+          value += text[j];
+          j += 1;
+        }
+      }
+      if (!closed) parseFail(`QueryParserError: Lexical error at line 1, column ${text.length + 1}.  Encountered: <EOF> after : "'"`);
+      tokens.push({ type: "string", value, column });
+      i = j;
+    } else {
+      const two = text.slice(i, i + 2);
+      if (two === "<=" || two === ">=" || two === "!=" || two === "<>") {
+        tokens.push({ type: "punct", value: two, column });
+        i += 2;
+      } else if ("=<>(),*".includes(text[i])) {
+        tokens.push({ type: "punct", value: text[i], column });
+        i += 1;
+      } else {
+        parseFail(`QueryParserError: Lexical error at line 1, column ${column}.  Encountered: "${text[i]}"`);
+      }
+    }
+  }
+  return tokens;
+}
+
+const KEYWORDS = new Set(["select", "from", "where", "and", "or", "not", "orderby", "asc", "desc", "startposition", "maxresults", "in", "like", "count"]);
+
+/** Parse query text into { entity, select, where, order, start, max }. */
+export function parseQuery(text, parseFail) {
+  if (typeof text !== "string" || text.trim().length === 0) parseFail("QueryParserError: Encountered \"<EOF>\" at line 1, column 1.");
+  if (text.length > MAX_QUERY_LENGTH) parseFail(`QueryParserError: Query exceeds the supported length of ${MAX_QUERY_LENGTH} characters.`);
+  const mangled = text.indexOf("\uFFFD");
+  if (mangled >= 0) parseFail(`QueryParserError: Invalid character in query at line 1, column ${mangled + 1}.`);
+  const tokens = tokenize(text, parseFail);
+  let at = 0;
+  const peek = () => tokens[at];
+  const lower = (token) => (token !== undefined && token.type === "word" ? token.value.toLowerCase() : null);
+  const unexpected = (token) => {
+    if (token === undefined) return parseFail(`QueryParserError: Encountered " <EOF> "" at line 1, column ${text.length + 1}.`);
+    const kind = token.type === "string" ? "<STRING>" : token.type === "number" ? "<INTEGER>" : token.type === "word" ? "<IDENTIFIER>" : token.value;
+    return parseFail(`QueryParserError: Encountered " ${kind} "${token.value.slice(0, 64)} "" at line 1, column ${token.column}.`);
+  };
+  const expectWord = (word) => {
+    const token = peek();
+    if (lower(token) !== word) unexpected(token);
+    at += 1;
+  };
+  const expectPunct = (value) => {
+    const token = peek();
+    if (token === undefined || token.type !== "punct" || token.value !== value) unexpected(token);
+    at += 1;
+  };
+  const property = () => {
+    const token = peek();
+    if (token === undefined || token.type !== "word" || KEYWORDS.has(token.value.toLowerCase())) unexpected(token);
+    at += 1;
+    return token.value;
+  };
+  const integer = () => {
+    const token = peek();
+    if (token === undefined || token.type !== "number" || !isAllDigits(token.value) || token.value.length > 9) unexpected(token);
+    at += 1;
+    return Number(token.value);
+  };
+
+  expectWord("select");
+  let select;
+  const first = peek();
+  if (first !== undefined && first.type === "punct" && first.value === "*") {
+    at += 1;
+    select = { kind: "all" };
+  } else if (lower(first) === "count") {
+    at += 1;
+    expectPunct("(");
+    expectPunct("*");
+    expectPunct(")");
+    select = { kind: "count" };
+  } else {
+    const fields = [property()];
+    while (peek() !== undefined && peek().type === "punct" && peek().value === ",") {
+      at += 1;
+      fields.push(property());
+      if (fields.length > 100) unexpected(peek());
+    }
+    select = { kind: "fields", fields };
+  }
+  expectWord("from");
+  const entityToken = peek();
+  if (entityToken === undefined || entityToken.type !== "word" || KEYWORDS.has(entityToken.value.toLowerCase())) unexpected(entityToken);
+  at += 1;
+  const where = [];
+  if (lower(peek()) === "where") {
+    at += 1;
+    where.push(condition());
+    while (lower(peek()) === "and") {
+      at += 1;
+      if (where.length >= MAX_CONDITIONS) parseFail(`QueryParserError: A query supports at most ${MAX_CONDITIONS} conditions.`);
+      where.push(condition());
+    }
+  }
+  const order = [];
+  if (lower(peek()) === "orderby") {
+    at += 1;
+    for (;;) {
+      const prop = property();
+      let dir = "asc";
+      if (lower(peek()) === "asc" || lower(peek()) === "desc") {
+        dir = lower(peek());
+        at += 1;
+      }
+      order.push({ prop, dir });
+      if (peek() === undefined || peek().type !== "punct" || peek().value !== ",") break;
+      at += 1;
+      if (order.length >= MAX_SORT_KEYS) parseFail(`QueryParserError: A query supports at most ${MAX_SORT_KEYS} sort keys.`);
+    }
+  }
+  let start = 1;
+  let max = 100;
+  if (lower(peek()) === "startposition") {
+    at += 1;
+    start = integer();
+    if (start < 1) parseFail("QueryParserError: STARTPOSITION must be 1 or greater.");
+  }
+  if (lower(peek()) === "maxresults") {
+    at += 1;
+    max = integer();
+    if (max < 1 || max > 1000) parseFail("QueryParserError: MAXRESULTS must be between 1 and 1000.");
+  }
+  if (at < tokens.length) unexpected(peek());
+  return { entity: entityToken.value, select, where, order, start, max };
+
+  function condition() {
+    const prop = property();
+    const token = peek();
+    const word = lower(token);
+    if (word === "in") {
+      at += 1;
+      expectPunct("(");
+      const values = [literal()];
+      while (peek() !== undefined && peek().type === "punct" && peek().value === ",") {
+        at += 1;
+        if (values.length >= MAX_IN_VALUES) parseFail(`QueryParserError: IN supports at most ${MAX_IN_VALUES} values.`);
+        values.push(literal());
+      }
+      expectPunct(")");
+      return { prop, op: "in", values };
+    }
+    if (word === "like") {
+      at += 1;
+      return { prop, op: "like", values: [literal()] };
+    }
+    if (token === undefined || token.type !== "punct" || !["=", "<", ">", "<=", ">="].includes(token.value)) unexpected(token);
+    at += 1;
+    return { prop, op: token.value, values: [literal()] };
+  }
+
+  function literal() {
+    const token = peek();
+    if (token === undefined) unexpected(token);
+    if (token.type === "string" || token.type === "number") {
+      at += 1;
+      return { kind: token.type, value: token.value };
+    }
+    const word = lower(token);
+    if (word === "true" || word === "false") {
+      at += 1;
+      return { kind: "bool", value: word === "true" };
+    }
+    return unexpected(token);
+  }
+}
+
+function isAllDigits(text) {
+  for (let i = 0; i < text.length; i += 1) if (!isDigit(text.charCodeAt(i))) return false;
+  return text.length > 0;
+}

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

@@ -0,0 +1,88 @@
+// Read-only entities: CompanyInfo and Account (with CurrentBalance computed from the ledger on read).
+import { USD, fromCents, toCents } from "./common.mjs";
+
+export function renderCompany(company) {
+  const out = {
+    CompanyName: company.CompanyName,
+    LegalName: company.LegalName,
+    CompanyAddr: compactAddr(company.CompanyAddr),
+    Email: company.Email,
+    PrimaryPhone: company.PrimaryPhone,
+    WebAddr: company.WebAddr,
+    Country: company.Country,
+    FiscalYearStartMonth: company.FiscalYearStartMonth,
+    CompanyStartDate: company.CompanyStartDate,
+    SupportedLanguages: company.SupportedLanguages,
+    DefaultTimeZone: company.DefaultTimeZone,
+    domain: "QBO",
+    sparse: false,
+    Id: company.Id,
+    SyncToken: company.SyncToken,
+    MetaData: company.MetaData,
+  };
+  return out;
+}
+
+export function compactAddr(addr) {
+  if (addr === null) return null;
+  const out = {};
+  for (const key of ["Id", "Line1", "Line2", "City", "CountrySubDivisionCode", "PostalCode", "Country"]) if (addr[key] !== null) out[key] = addr[key];
+  return out;
+}
+
+/** Per-request ledger totals for account balances (one pass over invoices, payments and items). */
+function accountTotals(s) {
+  const key = "#accountTotals";
+  if (s.memo.has(key)) return s.memo.get(key);
+  const totals = { receivable: 0, deposits: new Map(), income: new Map() };
+  const items = new Map();
+  for (const item of s.rows("items")) items.set(item.Id, item);
+  for (const invoice of s.rows("invoices")) {
+    totals.receivable += toCents(invoice.Balance) ?? 0;
+    if (invoice.voided) continue;
+    for (const line of invoice.Line) {
+      const item = items.get(line.SalesItemLineDetail.ItemRef.value);
+      if (item === undefined) continue;
+      const account = item.IncomeAccountRef.value;
+      totals.income.set(account, (totals.income.get(account) ?? 0) + (toCents(line.Amount) ?? 0));
+    }
+  }
+  for (const payment of s.rows("payments")) {
+    const account = payment.DepositToAccountRef.value;
+    totals.deposits.set(account, (totals.deposits.get(account) ?? 0) + (toCents(payment.TotalAmt) ?? 0));
+  }
+  s.memo.set(key, totals);
+  return totals;
+}
+
+export function accountBalanceCents(s, row) {
+  const opening = toCents(row.openingBalance, { allowNegative: true }) ?? 0;
+  if (row.AccountType === "Accounts Receivable") return opening + accountTotals(s).receivable;
+  if (row.AccountType === "Bank" || row.AccountSubType === "UndepositedFunds") return opening + (accountTotals(s).deposits.get(row.Id) ?? 0);
+  if (row.AccountType === "Income") return opening + (accountTotals(s).income.get(row.Id) ?? 0);
+  return opening;
+}
+
+export function renderAccount(s, row) {
+  const balance = fromCents(accountBalanceCents(s, row));
+  const out = {
+    Name: row.Name,
+    SubAccount: false,
+    FullyQualifiedName: row.FullyQualifiedName,
+    Active: row.Active,
+    Classification: row.Classification,
+    AccountType: row.AccountType,
+    AccountSubType: row.AccountSubType,
+    CurrentBalance: balance,
+    CurrentBalanceWithSubAccounts: balance,
+    CurrencyRef: USD,
+    domain: "QBO",
+    sparse: false,
+    Id: row.Id,
+    SyncToken: row.SyncToken,
+    MetaData: row.MetaData,
+  };
+  if (row.AcctNum !== null) out.AcctNum = row.AcctNum;
+  if (row.Description !== null) out.Description = row.Description;
+  return out;
+}

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

@@ -0,0 +1,147 @@
+// QuickBooks Online Accounting API v3 wire codecs: pure decode (path, query, body → operation arguments) and
+// encode (outcome → QuickBooks body or Fault envelope). No state, no clock; `time` comes from handler outputs.
+import { faultInfo } from "./common.mjs";
+import { bytesFromBase64 } from "./pdf.mjs";
+
+const MAX_DEPTH = 512;
+
+function last(query, name) {
+  const values = Object.hasOwn(query, name) ? query[name] : undefined;
+  return values === undefined || values.length === 0 ? undefined : values[values.length - 1];
+}
+
+const cap = (value, max) => (typeof value === "string" && value.length > max ? value.slice(0, max) : value);
+
+function checkDepth(value) {
+  const stack = [[value, 1]];
+  while (stack.length > 0) {
+    const [current, depth] = stack.pop();
+    if (current === null || typeof current !== "object") continue;
+    if (depth > MAX_DEPTH) throw new Error(`Request body nesting exceeds the supported depth of ${MAX_DEPTH} levels.`);
+    for (const inner of Array.isArray(current) ? current : Object.values(current)) {
+      if (inner !== null && typeof inner === "object") stack.push([inner, depth + 1]);
+    }
+  }
+}
+
+function args(entries) {
+  const out = {};
+  for (const [key, value] of entries) if (value !== undefined) out[key] = value;
+  return out;
+}
+
+function withKey(request, argumentsObject) {
+  const key = last(request.query, "requestid");
+  if (key === undefined || key.length === 0) return { arguments: argumentsObject };
+  if (key.length > 255) throw new Error("requestid must be at most 255 characters.");
+  return { arguments: argumentsObject, idempotencyKey: key };
+}
+
+const realm = (request) => cap(request.path.realmId, 64);
+
+function jsonBody(request) {
+  if (request.body.kind !== "json") return undefined;
+  checkDepth(request.body.value);
+  return request.body.value;
+}
+
+const ERROR_TEXT = new Map([
+  ["THROTTLE_EXCEEDED", "Throttling limits exceeded."],
+  ["SERVICE_UNAVAILABLE", "Service Unavailable"],
+]);
+
+/** QuickBooks Fault envelope for any unsuccessful outcome. */
+export function faultBody(outcome) {
+  const error = outcome.error ?? {};
+  const message = typeof error.message === "string" ? error.message : "";
+  if (outcome.status === "denied") {
+    return envelope("message=ApplicationAuthorizationFailed; errorCode=003100; statusCode=403", "This operation is not granted to the calling actor in this Firedrill world.", "3100", "", "AuthorizationFault");
+  }
+  if (outcome.status === "unsupported") return envelope("Unsupported Operation", "Operation is not supported by this Tool.", "500", "", "ValidationFault");
+  if (outcome.status === "invalid") {
+    return envelope("A business validation error has occurred while processing your request", `Business Validation Error: ${message.slice(0, 500)}`, "6000", "", "ValidationFault");
+  }
+  const code = String(error.code ?? "").replace(/^tool\./, "");
+  const info = faultInfo(code) ?? ["10000", "An application error has occurred while processing your request", "SystemFault"];
+  const details = error.details !== null && typeof error.details === "object" ? error.details : {};
+  const body = envelope(
+    code === "SERVICE_UNAVAILABLE" ? info[1] : message.length > 0 ? message : info[1],
+    typeof details.detail === "string" ? details.detail : (ERROR_TEXT.get(code) ?? message),
+    typeof details.qboCode === "string" ? details.qboCode : info[0],
+    typeof details.element === "string" ? details.element : "",
+    typeof details.faultType === "string" ? details.faultType : info[2],
+  );
+  if (typeof details.time === "string") body.time = details.time;
+  return body;
+}
+
+function envelope(Message, Detail, code, element, type) {
+  return { Fault: { Error: [{ Message, Detail, code, element }], type } };
+}
+
+function encodeJson({ invocation, outcome }) {
+  const headers = { intuit_tid: invocation.callId };
+  if (outcome.status !== "ok") return { headers, body: { kind: "json", value: faultBody(outcome) } };
+  const value = {};
+  for (const [key, inner] of Object.entries(outcome.value)) if (key !== "action") value[key] = inner;
+  return { headers, body: { kind: "json", value } };
+}
+
+function encodePdf(result) {
+  const { outcome, invocation } = result;
+  if (outcome.status !== "ok") return encodeJson(result);
+  const bytes = bytesFromBase64(outcome.value.base64);
+  if (bytes === null) return { headers: { intuit_tid: invocation.callId }, body: { kind: "json", value: envelope("An application error has occurred while processing your request", "PDF rendering failed.", "10000", "", "SystemFault") } };
+  return { headers: { intuit_tid: invocation.callId }, body: { kind: "bytes", value: bytes, contentType: "application/pdf" } };
+}
+
+const getRoute = (idName) => ({
+  decode: (request) => ({ arguments: args([[idName, cap(request.path.id, 64)], ["realmId", realm(request)]]) }),
+  encode: encodeJson,
+});
+
+const postRoute = (withInclude) => ({
+  decode: (request) =>
+    withKey(request, args([
+      ["body", jsonBody(request)],
+      ["operation", cap(last(request.query, "operation"), 64)],
+      ["include", withInclude ? cap(last(request.query, "include"), 64) : undefined],
+      ["realmId", realm(request)],
+    ])),
+  encode: encodeJson,
+});
+
+export const routes = {
+  "companyinfo-get": {
+    decode: (request) => ({ arguments: args([["company_id", cap(request.path.companyId, 64)], ["realmId", realm(request)]]) }),
+    encode: encodeJson,
+  },
+  "query-get": {
+    decode: (request) => ({ arguments: args([["query", cap(last(request.query, "query") ?? "", 20001)], ["realmId", realm(request)]]) }),
+    encode: encodeJson,
+  },
+  "query-post": {
+    decode: (request) => {
+      const text = request.body.kind === "text" ? request.body.value : (last(request.query, "query") ?? "");
+      return { arguments: args([["query", cap(text, 20001)], ["realmId", realm(request)]]) };
+    },
+    encode: encodeJson,
+  },
+  "customer-get": getRoute("id"),
+  "customer-post": postRoute(false),
+  "item-get": getRoute("item_id"),
+  "item-post": postRoute(false),
+  "invoice-get": getRoute("invoice_id"),
+  "invoice-post": postRoute(true),
+  "invoice-send": {
+    decode: (request) => withKey(request, args([["invoice_id", cap(request.path.id, 64)], ["sendTo", cap(last(request.query, "sendTo"), 320)], ["realmId", realm(request)]])),
+    encode: encodeJson,
+  },
+  "invoice-pdf": {
+    decode: (request) => ({ arguments: args([["invoice_id", cap(request.path.id, 64)], ["realmId", realm(request)]]) }),
+    encode: encodePdf,
+  },
+  "payment-get": getRoute("id"),
+  "payment-post": postRoute(false),
+  "account-get": getRoute("id"),
+};