qbd-agent-kit 0.2.0__py3-none-any.whl

qbd_agent_kit/errors.py

@@ -0,0 +1,130 @@
+"""Errors from QuickBooks and from the kit, each with the one thing a merchant can do about it."""
+from __future__ import annotations
+
+from .jsutil import num_str
+
+# What to do for the connection errors people actually hit. QuickBooks' own message is always shown too.
+HINTS = {
+    "0x80040154": "The QuickBooks SDK is not registered for this program. QuickBooks Desktop must be installed on this PC; "
+    "if it is, run `qbd doctor` to see what is missing.",
+    "0x800401F3": "The QuickBooks SDK is not installed on this PC. Run qbd on the PC where QuickBooks Desktop is installed.",
+    "0x80040401": "Open QuickBooks Desktop on this PC, open the company file, then try again.",
+    "0x80040403": "Check the company file path in QBD_COMPANY_FILE, or leave it empty to use the file open in QuickBooks.",
+    "0x80040408": "QuickBooks could not be started. Open QuickBooks Desktop and the company file yourself, then try again.",
+    "0x80040410": "The company file is open in a different mode than requested. Switch QuickBooks to multi-user mode "
+    "(File > Switch to Multi-user Mode) or close other apps connected to it.",
+    "0x80040414": "A window or message box is open in QuickBooks. Close it (look for a dialog behind other windows), then try again. "
+    "If it is the 'Application permission' dialog, answer it as described in docs/setup.md.",
+    "0x80040416": "No company file is open. Open the company file in QuickBooks, or set QBD_COMPANY_FILE to its full path.",
+    "0x80040418": "This app has not been allowed into this company file yet. Log into QuickBooks as the Admin user in single-user mode "
+    "and run `qbd authorize`.",
+    "0x8004041A": "This app is not allowed into this company file. In QuickBooks: Edit > Preferences > Integrated Applications > "
+    "Company Preferences, select the app and allow access.",
+    "0x8004041D": "This app is not allowed to log in automatically. In QuickBooks: Edit > Preferences > Integrated Applications > "
+    "Company Preferences > Properties, tick 'Allow this application to login automatically'.",
+    "0x80040420": "Access was refused in QuickBooks. Run `qbd authorize` and choose a 'Yes' option in the dialog.",
+    "0x80040422": "Another app holds the company file in single-user mode. Close it or switch QuickBooks to multi-user mode.",
+    "0x80040424": "QuickBooks is still starting up. Wait until the company file is fully open, then try again.",
+}
+
+# Connection errors only a person at the PC can clear: a dialog, QuickBooks closed, a permission.
+NEEDS_PERSON = {
+    "0x80040401", "0x80040403", "0x80040408", "0x80040410", "0x80040414", "0x80040416", "0x80040418",
+    "0x8004041A", "0x8004041D", "0x80040420", "0x80040422", "0x80040424", "no-session",
+}
+
+STATUS_HINTS = {
+    1030: "This edition or country version of QuickBooks does not support this request; some exist only in the US edition.",
+    3100: "A record with this name already exists. Search for it and update it instead of adding a new one.",
+    3120: "The record was not found. Search first and use the exact ListID, TxnID or full name it returns.",
+    3140: "A referenced customer, vendor, item or account does not exist. Search for the exact name first.",
+    3180: "QuickBooks could not save the record. Check that the record is not open in QuickBooks and the values are valid.",
+    3200: "The record changed after it was read. Read it again and redo the change.",
+    3220: "The feature is turned off in this company file, or the QuickBooks user this app logs in as may not use it. QuickBooks' message says which.",
+    3250: "This feature is turned off in this company file or not available in this edition of QuickBooks.",
+    3260: "The QuickBooks user this app logs in as is not allowed to do this. Change it in Integrated Applications preferences.",
+}
+
+
+def _hresult(code: str) -> str:
+    return "0x" + code[2:].upper() if code[:2].lower() == "0x" else code
+
+
+class QbConnectionError(Exception):
+    """The QuickBooks SDK connection failed; code is the HRESULT such as 0x80040416, or a word such as timeout."""
+
+    def __init__(self, code: str, message: str, hint: str | None = None):
+        super().__init__(message)
+        self.code = _hresult(code)
+        self.message = message
+        self.hint = hint if hint is not None else HINTS.get(self.code)
+
+    @property
+    def needs_person(self) -> bool:
+        return self.code in NEEDS_PERSON
+
+    def __str__(self) -> str:
+        return f"{self.message}{chr(10) + 'What to do: ' + self.hint if self.hint else ''} ({self.code})"
+
+
+class QbTimeoutError(QbConnectionError):
+    """QuickBooks did not answer in time. The request may still be running inside QuickBooks."""
+
+    def __init__(self, seconds: float, message: str | None = None):
+        super().__init__(
+            "timeout",
+            message or f"QuickBooks did not answer within {num_str(seconds)} s. The request may still be running inside QuickBooks.",
+            "Wait until QuickBooks is responsive again, then retry with a smaller date range or limit. If QuickBooks stays "
+            "frozen, it may have stopped working: close it (with Task Manager if needed) and open the company file again.",
+        )
+
+
+class QbNoSessionError(QbConnectionError):
+    """QuickBooks did not open a session in time, most likely because a dialog is waiting for a person."""
+
+    def __init__(self, seconds: float):
+        super().__init__(
+            "no-session",
+            f"QuickBooks did not open a session within {num_str(seconds)} s. It is most likely waiting for someone at this "
+            "PC to answer a dialog, such as 'Application permission' the first time qbd connects.",
+            "Find the QuickBooks dialog on this PC; it may be behind other windows. For 'Application permission' choose "
+            "'Yes, whenever my QuickBooks company file is open' and click Continue, then run the command again. "
+            "`qbd authorize` waits 10 minutes for the answer.",
+        )
+
+
+class QbStatusError(Exception):
+    """A qbXML status error, e.g. 3120 "object not found"."""
+
+    def __init__(self, status_code: int, message: str):
+        super().__init__(message)
+        self.status_code = status_code
+        self.message = message
+        self.hint = STATUS_HINTS.get(status_code)
+
+    def __str__(self) -> str:
+        return f"QuickBooks status {self.status_code}: {self.message}{chr(10) + 'What to do: ' + self.hint if self.hint else ''}"
+
+
+class QbxmlInputError(Exception):
+    """A request that does not fit the qbXML schema."""
+
+
+class QbxmlParseError(Exception):
+    """QuickBooks sent something that is not readable qbXML."""
+
+
+class ToolError(Exception):
+    """A request the kit refuses, with a message that says what to change."""
+
+
+class WriteUnconfirmed(Exception):
+    """A change was sent but QuickBooks did not confirm it, so it may or may not be saved."""
+
+
+class InvalidArguments(Exception):
+    """Arguments that do not fit a command; issues are (path, message) pairs."""
+
+    def __init__(self, issues: list[tuple[str, str]]):
+        self.issues = issues
+        super().__init__("; ".join(f"{p or 'input'}: {m}" for p, m in issues))

qbd_agent_kit/jsutil.py

@@ -0,0 +1,261 @@
+"""Numbers, text and JSON written the same way every time: amounts as 1,234.50, no "48.0" for
+whole numbers, JSON keys in the order they were set.
+
+MISSING stands for "no value at all": dictionary entries holding it are left out of the JSON,
+while None is written as null.
+"""
+from __future__ import annotations
+
+import json
+import math
+import re
+from decimal import ROUND_HALF_UP, Decimal
+from typing import Any, Iterable
+
+
+class _Missing:
+    __slots__ = ()
+
+    def __bool__(self) -> bool:
+        return False
+
+    def __repr__(self) -> str:
+        return "MISSING"
+
+    def __reduce__(self) -> str:
+        return "MISSING"  # copies stay the one MISSING
+
+
+MISSING: Any = _Missing()
+
+
+def is_num(v: Any) -> bool:
+    """A real number (bool is not one, unlike in Python's own idea of int)."""
+    return isinstance(v, (int, float)) and not isinstance(v, bool)
+
+
+def truthy(v: Any) -> bool:
+    """Whether a value counts as set: empty text, 0, NaN, None and MISSING do not; any dict or list does."""
+    if v is None or v is MISSING or v is False:
+        return False
+    if isinstance(v, float):
+        return v == v and v != 0
+    if isinstance(v, (int, str)):
+        return bool(v)
+    return True
+
+
+def nz(*values: Any) -> Any:
+    """The first value that is neither None nor MISSING; the last one otherwise."""
+    for v in values[:-1]:
+        if v is not None and v is not MISSING:
+            return v
+    return values[-1]
+
+
+def get(obj: Any, key: str) -> Any:
+    """obj[key] for a dict, MISSING for anything else or an absent key."""
+    return obj.get(key, MISSING) if isinstance(obj, dict) else MISSING
+
+
+def add_up(values: Iterable[float]) -> float:
+    """Adds from left to right. sum() may compensate rounding on newer Pythons, which changes the last digit."""
+    total: float = 0
+    for v in values:
+        total = total + v
+    return total
+
+
+def js_round(x: float) -> float:
+    """Rounds halves up, towards +infinity: 2.5 -> 3, -2.5 -> -2."""
+    if not math.isfinite(x):
+        return x
+    f = math.floor(x)
+    return float(f + 1 if x - f >= 0.5 else f)
+
+
+def round2(x: float) -> float:
+    return js_round(x * 100) / 100
+
+
+def _digits(x: float) -> tuple[str, int]:
+    """Shortest digits of x > 0 and the position of the decimal point: x = 0.DIGITS * 10**n."""
+    mant, _, exp = repr(x).partition("e")
+    whole, _, frac = mant.partition(".")
+    digits = whole + frac
+    n = len(whole) + (int(exp) if exp else 0)
+    stripped = digits.lstrip("0")
+    n -= len(digits) - len(stripped)
+    return stripped.rstrip("0") or "0", n
+
+
+def num_str(x: Any) -> str:
+    """A number as text: 48 not 48.0, 0.1 not 0.1000000000000000055, 1e-7 for tiny values."""
+    if isinstance(x, bool):
+        return "true" if x else "false"
+    if isinstance(x, int):
+        return str(x)
+    if math.isnan(x):
+        return "NaN"
+    if math.isinf(x):
+        return "Infinity" if x > 0 else "-Infinity"
+    if x == 0:
+        return "0"
+    if x < 0:
+        return "-" + num_str(-x)
+    digits, n = _digits(x)
+    k = len(digits)
+    if k <= n <= 21:
+        return digits + "0" * (n - k)
+    if 0 < n <= 21:
+        return f"{digits[:n]}.{digits[n:]}"
+    if -6 < n <= 0:
+        return "0." + "0" * -n + digits
+    e = n - 1
+    mantissa = digits[0] + (f".{digits[1:]}" if k > 1 else "")
+    return f"{mantissa}e{'+' if e >= 0 else '-'}{abs(e)}"
+
+
+def to_fixed(x: float, places: int) -> str:
+    """Rounds the exact stored value, halves away from zero, so 1.005 (stored as 1.00499...) gives 1.00."""
+    if isinstance(x, float) and (math.isnan(x) or abs(x) >= 1e21):
+        return num_str(x)
+    if x < 0:
+        return "-" + to_fixed(-x, places)
+    q = Decimal(float(x) if x else 0.0).quantize(Decimal(1).scaleb(-places), rounding=ROUND_HALF_UP)
+    return format(q, "f")
+
+
+def money(x: float) -> str:
+    """1234.5 -> '1,234.50'. Rounds the shortest decimal form, so 1.005 shows as 1.01."""
+    if isinstance(x, float) and not math.isfinite(x):
+        return num_str(x).replace("Infinity", "∞")
+    q = Decimal(repr(float(x))).quantize(Decimal("0.01"), rounding=ROUND_HALF_UP)
+    return format(q, ",f")
+
+
+_WS = " \t\n\v\f\r             

  　"
+_DECIMAL = re.compile(r"[+-]?(?:[0-9]+\.?[0-9]*(?:[eE][+-]?[0-9]+)?|\.[0-9]+(?:[eE][+-]?[0-9]+)?)\Z")
+_RADIX = re.compile(r"0([xXoObB])([0-9a-fA-F]+)\Z")
+
+
+def to_number(s: str) -> float:
+    """A strict reading of text as a number: '12.50' -> 12.5, '' -> 0, 'abc' or '1_000' -> NaN."""
+    s = s.strip(_WS)
+    if not s:
+        return 0.0
+    if _DECIMAL.match(s):
+        return float(s)
+    if s in ("Infinity", "+Infinity"):
+        return math.inf
+    if s == "-Infinity":
+        return -math.inf
+    m = _RADIX.match(s)
+    if m:
+        try:
+            return float(int(m.group(2), {"x": 16, "o": 8, "b": 2}[m.group(1).lower()]))
+        except ValueError:
+            return math.nan
+    return math.nan
+
+
+def to_num(v: Any) -> float:
+    """Any value as a number: text is read strictly, None counts as 0, anything unreadable is NaN."""
+    if v is MISSING:
+        return math.nan
+    if v is None:
+        return 0.0
+    if isinstance(v, bool):
+        return 1.0 if v else 0.0
+    if isinstance(v, (int, float)):
+        return v
+    if isinstance(v, str):
+        return to_number(v)
+    if isinstance(v, list) and len(v) <= 1:
+        return to_number(text(v[0])) if v else 0.0
+    return math.nan
+
+
+def finite(v: Any) -> bool:
+    return is_num(v) and math.isfinite(v)
+
+
+_INT_PREFIX = re.compile(r"[+-]?[0-9]+")
+
+
+def parse_int(s: str) -> float:
+    """The leading whole number of a text: '12abc' -> 12, '3.7' -> 3, 'x' -> NaN."""
+    m = _INT_PREFIX.match(s.lstrip(_WS))
+    return int(m.group(0)) if m else math.nan
+
+
+def text(v: Any) -> str:
+    """Any value as text, the way it would print in a message."""
+    if v is None:
+        return "null"
+    if v is MISSING:
+        return "undefined"
+    if isinstance(v, str):
+        return v
+    if isinstance(v, (bool, int, float)):
+        return num_str(v)
+    if isinstance(v, (list, tuple)):
+        return ",".join("" if x is None or x is MISSING else text(x) for x in v)
+    return "[object Object]"
+
+
+def _write(v: Any, out: list[str], indent: str | None, level: int) -> None:
+    if v is None or v is MISSING:
+        out.append("null")
+    elif v is True:
+        out.append("true")
+    elif v is False:
+        out.append("false")
+    elif isinstance(v, str):
+        out.append(json.dumps(v, ensure_ascii=False))
+    elif isinstance(v, int):
+        out.append(str(v))
+    elif isinstance(v, float):
+        out.append(num_str(v) if math.isfinite(v) else "null")
+    elif isinstance(v, dict):
+        items = [(k, x) for k, x in v.items() if x is not MISSING]
+        if not items:
+            out.append("{}")
+            return
+        inner = None if indent is None else "\n" + indent * (level + 1)
+        out.append("{")
+        for i, (k, x) in enumerate(items):
+            if i:
+                out.append(",")
+            if inner:
+                out.append(inner)
+            out.append(json.dumps(str(k), ensure_ascii=False))
+            out.append(":" if indent is None else ": ")
+            _write(x, out, indent, level + 1)
+        if indent is not None:
+            out.append("\n" + indent * level)
+        out.append("}")
+    elif isinstance(v, (list, tuple)):
+        if not v:
+            out.append("[]")
+            return
+        inner = None if indent is None else "\n" + indent * (level + 1)
+        out.append("[")
+        for i, x in enumerate(v):
+            if i:
+                out.append(",")
+            if inner:
+                out.append(inner)
+            _write(x, out, indent, level + 1)
+        if indent is not None:
+            out.append("\n" + indent * level)
+        out.append("]")
+    else:
+        raise TypeError(f"cannot write {type(v).__name__} as JSON")
+
+
+def dumps(v: Any, pretty: bool = False) -> str:
+    """JSON with numbers as num_str writes them; entries holding MISSING are left out."""
+    out: list[str] = []
+    _write(v, out, "  " if pretty else None, 0)
+    return "".join(out)

qbd_agent_kit/qb/catalog.py

@@ -0,0 +1,164 @@
+"""The records an agent can search, under plain names. Everything else (which filters a query takes,
+which fields a record has) is read from the schema, so the catalog stays a list of names."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from functools import lru_cache
+from typing import Any
+
+from ..errors import ToolError
+from ..jsutil import MISSING, is_num, nz
+from ..qbxml.schema import message_model, model
+
+
+@dataclass(frozen=True)
+class Entity:
+    key: str            # "invoice"
+    base: str           # qbXML name, "Invoice"
+    kind: str           # "list" or "txn"
+    label: str
+    query: str          # "InvoiceQueryRq"
+    fields: tuple       # every field the record can have, in schema order
+
+
+LISTS = [
+    ("customer", "Customer", "customers and jobs"),
+    ("vendor", "Vendor", "vendors"),
+    ("employee", "Employee", "employees (no payroll data)"),
+    ("other_name", "OtherName", "other names"),
+    ("item", "Item", "all items of every type"),
+    ("item_inventory", "ItemInventory", "inventory parts"),
+    ("item_assembly", "ItemInventoryAssembly", "inventory assemblies"),
+    ("item_non_inventory", "ItemNonInventory", "non-inventory parts"),
+    ("item_service", "ItemService", "service items"),
+    ("item_other_charge", "ItemOtherCharge", "other charges"),
+    ("item_group", "ItemGroup", "item groups"),
+    ("item_discount", "ItemDiscount", "discount items"),
+    ("account", "Account", "chart of accounts with balances"),
+    ("class", "Class", "classes"),
+    ("terms", "Terms", "payment terms"),
+    ("payment_method", "PaymentMethod", "payment methods"),
+    ("sales_rep", "SalesRep", "sales reps"),
+    ("sales_tax_code", "SalesTaxCode", "sales tax codes"),
+    ("price_level", "PriceLevel", "price levels"),
+    ("inventory_site", "InventorySite", "inventory sites (Enterprise)"),
+    ("ship_method", "ShipMethod", "shipping methods"),
+    ("customer_type", "CustomerType", "customer types"),
+    ("vendor_type", "VendorType", "vendor types"),
+    ("currency", "Currency", "currencies"),
+]
+
+TXNS = [
+    ("invoice", "Invoice", "invoices"),
+    ("estimate", "Estimate", "estimates / quotes"),
+    ("sales_order", "SalesOrder", "sales orders"),
+    ("sales_receipt", "SalesReceipt", "sales receipts"),
+    ("credit_memo", "CreditMemo", "credit memos"),
+    ("receive_payment", "ReceivePayment", "customer payments"),
+    ("deposit", "Deposit", "bank deposits"),
+    ("charge", "Charge", "statement charges"),
+    ("bill", "Bill", "vendor bills"),
+    ("vendor_credit", "VendorCredit", "vendor credits"),
+    ("bill_payment_check", "BillPaymentCheck", "bill payments by check"),
+    ("bill_payment_credit_card", "BillPaymentCreditCard", "bill payments by credit card"),
+    ("check", "Check", "checks / expenses"),
+    ("credit_card_charge", "CreditCardCharge", "credit card charges"),
+    ("credit_card_credit", "CreditCardCredit", "credit card credits"),
+    ("purchase_order", "PurchaseOrder", "purchase orders"),
+    ("item_receipt", "ItemReceipt", "item receipts (received inventory)"),
+    ("journal_entry", "JournalEntry", "journal entries"),
+    ("inventory_adjustment", "InventoryAdjustment", "inventory adjustments"),
+    ("build_assembly", "BuildAssembly", "assembly builds"),
+    ("transfer", "Transfer", "transfers between accounts"),
+    ("transfer_inventory", "TransferInventory", "inventory transfers between sites"),
+    ("sales_tax_payment", "SalesTaxPaymentCheck", "sales tax payments"),
+    ("time_tracking", "TimeTracking", "time entries"),
+    ("transaction", "Transaction", "any transaction type (summary only)"),
+]
+
+
+def _make(kind: str, key: str, base: str, label: str) -> Entity | None:
+    query = f"{base}QueryRq"
+    rs = message_model(f"{base}QueryRs")
+    if message_model(query) is None or rs is None:
+        return None
+    fields: list[str] = []
+    for name in rs.o:
+        if not name.endswith("Ret"):
+            continue
+        m = model(rs.c[name][0])
+        for f in m.o if m else []:
+            if f not in fields:
+                fields.append(f)
+    return Entity(key, base, kind, label, query, tuple(fields))
+
+
+@lru_cache(maxsize=None)
+def entities() -> tuple[Entity, ...]:
+    made = [_make("list", *e) for e in LISTS] + [_make("txn", *e) for e in TXNS]
+    return tuple(e for e in made if e is not None)
+
+
+def entity(key: str) -> Entity:
+    for e in entities():
+        if e.key == key:
+            return e
+    raise ToolError(f'Unknown record type "{key}". Use one of: {", ".join(x.key for x in entities())}')
+
+
+# Fields shown in search results, in this order when the record has them.
+SUMMARY = [
+    "_type", "ListID", "TxnID", "TxnType", "FullName", "Name", "CompanyName", "AccountType", "AccountNumber",
+    "RefNumber", "TxnDate", "DueDate", "CustomerRef", "VendorRef", "PayeeEntityRef", "EntityRef",
+    "AccountRef", "DepositToAccountRef", "BankAccountRef", "CreditCardAccountRef", "Email", "Phone", "Contact",
+    "Balance", "TotalBalance", "Subtotal", "SalesTaxTotal", "TotalAmount", "Amount", "AmountDue", "DepositTotal",
+    "OpenAmount", "BalanceRemaining", "AppliedAmount", "UnusedPayment", "UnusedCredits", "CreditRemaining",
+    "IsPaid", "IsPending", "IsManuallyClosed", "IsFullyInvoiced", "IsFullyReceived", "IsActive",
+    "QuantityOnHand", "QuantityOnOrder", "QuantityOnSalesOrder", "ReorderPoint", "Max", "SalesPrice",
+    "PurchaseCost", "AverageCost", "PrefVendorRef", "SalesOrPurchase", "SalesAndPurchase", "Memo",
+]
+
+
+def summary_fields(e: Entity) -> list[str]:
+    has = set(e.fields)
+    # QuickBooks can fill a bill's OpenAmount with the vendor's whole open balance, which reads like the bill's own.
+    return [f for f in SUMMARY if f in has and not (f == "Name" and "FullName" in has) and not (f == "OpenAmount" and e.base == "Bill")]
+
+
+def party_field(e: Entity) -> str | None:
+    """The party a transaction belongs to (customer, vendor, payee), as a field name."""
+    return next((f for f in ("CustomerRef", "VendorRef", "PayeeEntityRef", "EntityRef") if f in e.fields), None)
+
+
+def amount_of(row: dict) -> Any:
+    """A transaction's total, whichever field holds it for this type; MISSING when it has none."""
+    for f in ("TotalAmount", "AmountDue", "Amount", "DepositTotal"):
+        if is_num(row.get(f)):
+            return row[f]
+    if is_num(row.get("Subtotal")):
+        tax = row.get("SalesTaxTotal")
+        return row["Subtotal"] + (tax if is_num(tax) and tax == tax else 0)
+    return MISSING
+
+
+def ref_value(ref: dict) -> Any:
+    return nz(ref.get("FullName", MISSING), ref.get("ListID", MISSING), ref.get("TxnID", MISSING))
+
+
+def compact(row: dict, fields: list[str] | None = None) -> dict:
+    """{ListID, FullName} references read as their name; everything else is kept."""
+    out = {}
+    for k, v in row.items():
+        if fields is not None and k not in fields:
+            continue
+        if isinstance(v, dict) and k.endswith("Ref"):
+            out[k[:-3]] = ref_value(v)
+        else:
+            out[k] = v
+    return out
+
+
+def ref_name(v: Any) -> Any:
+    if isinstance(v, (dict, list)):
+        return nz(v.get("FullName", MISSING), v.get("ListID", MISSING)) if isinstance(v, dict) else MISSING
+    return v if isinstance(v, str) else MISSING