qbwc-kit 0.1.0__py3-none-any.whl

qbwc_kit/__init__.py

@@ -0,0 +1,69 @@
+"""qbwc-kit: talk to QuickBooks Desktop over the Web Connector.
+
+QuickBooks Desktop has no HTTP API. The only supported way in is the Web
+Connector: a Windows service that polls *your* SOAP endpoint on a schedule,
+asks it for qbXML, hands that to QuickBooks over COM, and posts the response
+back. Every integration therefore has to implement the same eight callbacks and
+the same request/response loop before it can read a single invoice.
+
+This package is that plumbing:
+
+* :mod:`qbwc_kit.soap` - the small SOAP slice QBWC actually uses
+* :mod:`qbwc_kit.qbxml` - qbXML request building and status-aware parsing
+* :mod:`qbwc_kit.session` - generator-based tasks spanning many round trips
+* :mod:`qbwc_kit.service` - the eight callbacks, framework-agnostic
+* :mod:`qbwc_kit.server` - optional FastAPI adapter and WSDL hosting
+* :mod:`qbwc_kit.testing` - a fake Web Connector and a fake QuickBooks
+
+The core has no dependencies outside the standard library.
+"""
+
+from . import qbxml
+from .qbxml import (
+    QBXMLRequest,
+    QBXMLStatusError,
+    Request,
+    Response,
+    ResponseSet,
+    add,
+    mod,
+    parse_response,
+    query,
+)
+from .service import QBWCService
+from .session import (
+    Authenticator,
+    Session,
+    SessionStore,
+    SimpleTask,
+    StaticAuthenticator,
+    Task,
+    TaskContext,
+)
+from .wsdl import build_qwc, build_wsdl
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Authenticator",
+    "QBWCService",
+    "QBXMLRequest",
+    "QBXMLStatusError",
+    "Request",
+    "Response",
+    "ResponseSet",
+    "Session",
+    "SessionStore",
+    "SimpleTask",
+    "StaticAuthenticator",
+    "Task",
+    "TaskContext",
+    "__version__",
+    "add",
+    "build_qwc",
+    "build_wsdl",
+    "mod",
+    "parse_response",
+    "qbxml",
+    "query",
+]

qbwc_kit/qbxml/__init__.py

@@ -0,0 +1,40 @@
+"""qbXML request building and response parsing."""
+
+from .builder import QBXMLRequest, Request, add, element, elements, mod, query, ref
+from .parser import (
+    QBXMLParseError,
+    QBXMLStatusError,
+    Response,
+    ResponseSet,
+    parse_response,
+)
+from .types import (
+    ITERATOR_ENTITIES,
+    STATUS_NOTHING_FOUND,
+    STATUS_OK,
+    STATUS_UNSUPPORTED_REQUEST,
+    OnError,
+    Severity,
+)
+
+__all__ = [
+    "ITERATOR_ENTITIES",
+    "OnError",
+    "QBXMLParseError",
+    "QBXMLRequest",
+    "QBXMLStatusError",
+    "Request",
+    "Response",
+    "ResponseSet",
+    "STATUS_NOTHING_FOUND",
+    "STATUS_OK",
+    "STATUS_UNSUPPORTED_REQUEST",
+    "Severity",
+    "add",
+    "element",
+    "elements",
+    "mod",
+    "parse_response",
+    "query",
+    "ref",
+]

qbwc_kit/qbxml/builder.py

@@ -0,0 +1,202 @@
+"""qbXML request construction.
+
+QuickBooks Desktop only accepts a very particular document: a ``?qbxml``
+processing instruction, a ``QBXML`` root, and a ``QBXMLMsgsRq`` element whose
+``onError`` attribute decides whether the whole batch aborts on the first bad
+request. Getting any of that wrong produces an unhelpful parse error from
+QuickBooks, so it is worth building rather than templating by hand.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping, Sequence
+from dataclasses import dataclass, field
+from typing import Any
+
+from .types import OnError, iterator_supported
+
+_ESCAPES = (
+    ("&", "&"),
+    ("<", "&lt;"),
+    (">", "&gt;"),
+    ('"', "&quot;"),
+)
+
+
+def escape(value: Any) -> str:
+    text = "" if value is None else str(value)
+    for char, replacement in _ESCAPES:
+        text = text.replace(char, replacement)
+    return text
+
+
+def element(name: str, value: Any) -> str:
+    """One leaf element. ``None`` renders nothing so optional fields can be passed through."""
+    if value is None:
+        return ""
+    if isinstance(value, bool):
+        value = "true" if value else "false"
+    return f"<{name}>{escape(value)}</{name}>"
+
+
+def elements(fields: Mapping[str, Any] | Sequence[tuple[str, Any]]) -> str:
+    """Render an ordered mapping of leaf elements.
+
+    qbXML is order-sensitive: the schema is a sequence, not a set. Python dicts
+    preserve insertion order, which is exactly the guarantee this relies on.
+    """
+    items = fields.items() if isinstance(fields, Mapping) else fields
+    return "".join(element(name, value) for name, value in items)
+
+
+def ref(name: str, full_name: str | None = None, list_id: str | None = None) -> str:
+    """A ``*Ref`` aggregate. QuickBooks accepts either a ListID or a FullName."""
+    if full_name is None and list_id is None:
+        return ""
+    body = element("ListID", list_id) + element("FullName", full_name)
+    return f"<{name}>{body}</{name}>"
+
+
+@dataclass
+class Request:
+    """A single ``*Rq`` element inside the batch."""
+
+    name: str
+    body: str = ""
+    request_id: str | None = None
+    iterator: str | None = None
+    iterator_id: str | None = None
+    max_returned: int | None = None
+
+    def render(self) -> str:
+        attrs = ""
+        if self.request_id is not None:
+            attrs += f' requestID="{escape(self.request_id)}"'
+        if self.iterator is not None:
+            if not iterator_supported(self.name):
+                raise ValueError(f"{self.name} does not support iterators")
+            attrs += f' iterator="{escape(self.iterator)}"'
+        if self.iterator_id is not None:
+            attrs += f' iteratorID="{escape(self.iterator_id)}"'
+
+        body = self.body
+        if self.max_returned is not None:
+            # MaxReturned must lead the query body per the schema sequence.
+            body = element("MaxReturned", self.max_returned) + body
+
+        return f"<{self.name}{attrs}>{body}</{self.name}>"
+
+
+@dataclass
+class QBXMLRequest:
+    """A qbXML batch, ready to hand back from ``sendRequestXML``."""
+
+    requests: list[Request] = field(default_factory=list)
+    on_error: OnError = OnError.STOP
+    version: str = "13.0"
+
+    def add(self, request: Request) -> QBXMLRequest:
+        self.requests.append(request)
+        return self
+
+    def extend(self, requests: Iterable[Request]) -> QBXMLRequest:
+        self.requests.extend(requests)
+        return self
+
+    def render(self) -> str:
+        if not self.requests:
+            raise ValueError("a qbXML batch needs at least one request")
+        body = "".join(request.render() for request in self.requests)
+        return (
+            '<?xml version="1.0" encoding="utf-8"?>'
+            f'<?qbxml version="{escape(self.version)}"?>'
+            "<QBXML>"
+            f'<QBXMLMsgsRq onError="{self.on_error.value}">'
+            f"{body}"
+            "</QBXMLMsgsRq>"
+            "</QBXML>"
+        )
+
+    def __str__(self) -> str:  # pragma: no cover - convenience only
+        return self.render()
+
+
+def query(
+    entity: str,
+    *,
+    request_id: str | None = None,
+    max_returned: int | None = None,
+    iterator: str | None = None,
+    iterator_id: str | None = None,
+    modified_after: str | None = None,
+    modified_before: str | None = None,
+    active_status: str | None = None,
+    include_fields: Sequence[str] | None = None,
+    owner_id: str | None = None,
+    extra: Mapping[str, Any] | None = None,
+) -> Request:
+    """Build a ``<Entity>QueryRq``.
+
+    ``modified_after`` is the workhorse for incremental syncs: pair it with the
+    last successful sync timestamp and QuickBooks returns only what changed.
+    """
+    body = ""
+    if modified_after is not None or modified_before is not None:
+        body += (
+            "<ModifiedDateRangeFilter>"
+            + element("FromModifiedDate", modified_after)
+            + element("ToModifiedDate", modified_before)
+            + "</ModifiedDateRangeFilter>"
+        )
+    body += element("ActiveStatus", active_status)
+    if extra:
+        body += elements(extra)
+    if owner_id is not None:
+        body += element("OwnerID", owner_id)
+    if include_fields:
+        body += "".join(element("IncludeRetElement", name) for name in include_fields)
+
+    return Request(
+        name=f"{entity}QueryRq",
+        body=body,
+        request_id=request_id,
+        iterator=iterator,
+        iterator_id=iterator_id,
+        max_returned=max_returned,
+    )
+
+
+def add(entity: str, fields: Mapping[str, Any], *, request_id: str | None = None) -> Request:
+    """Build an ``<Entity>AddRq`` wrapping an ``<Entity>Add`` aggregate."""
+    inner = elements(fields) if isinstance(fields, Mapping) else str(fields)
+    return Request(
+        name=f"{entity}AddRq",
+        body=f"<{entity}Add>{inner}</{entity}Add>",
+        request_id=request_id,
+    )
+
+
+def mod(
+    entity: str,
+    fields: Mapping[str, Any],
+    *,
+    list_id: str | None = None,
+    txn_id: str | None = None,
+    edit_sequence: str,
+    request_id: str | None = None,
+) -> Request:
+    """Build an ``<Entity>ModRq``.
+
+    QuickBooks uses optimistic concurrency: every modification must carry the
+    ``EditSequence`` returned by the last read, and a stale one is rejected
+    rather than silently overwriting somebody else's edit.
+    """
+    if list_id is None and txn_id is None:
+        raise ValueError("a Mod request needs either a ListID or a TxnID")
+    head = element("ListID", list_id) + element("TxnID", txn_id)
+    head += element("EditSequence", edit_sequence)
+    return Request(
+        name=f"{entity}ModRq",
+        body=f"<{entity}Mod>{head}{elements(fields)}</{entity}Mod>",
+        request_id=request_id,
+    )

qbwc_kit/qbxml/parser.py

@@ -0,0 +1,210 @@
+"""qbXML response parsing.
+
+The response side is where integrations quietly break. A request that returns
+``statusCode="1"`` ("nothing found") looks structurally identical to one that
+succeeded with zero rows, and an unsupported request comes back as a *success*
+envelope carrying a non-zero status. Treating the response as "parse the XML,
+take the rows" is how a cache silently degrades into empty results, so this
+parser surfaces status on every response and refuses to hand back rows without
+it.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from dataclasses import dataclass, field
+from typing import Any
+from xml.etree import ElementTree as ET
+
+from .types import STATUS_NOTHING_FOUND, STATUS_OK, Severity
+
+
+class QBXMLParseError(ValueError):
+    pass
+
+
+class QBXMLStatusError(RuntimeError):
+    """Raised by :meth:`Response.raise_for_status` on a non-OK response."""
+
+    def __init__(self, response: Response) -> None:
+        super().__init__(f"{response.name}: [{response.status_code}] {response.status_message}")
+        self.response = response
+
+
+def _text(node: ET.Element) -> str:
+    return (node.text or "").strip()
+
+
+def _to_dict(node: ET.Element) -> Any:
+    """Convert a qbXML aggregate into plain Python.
+
+    Repeated sibling tags become lists, which is how line items, addresses with
+    multiple lines, and custom fields all arrive.
+    """
+    children = list(node)
+    if not children:
+        return _text(node)
+
+    result: dict[str, Any] = {}
+    for child in children:
+        value = _to_dict(child)
+        tag = child.tag
+        if tag in result:
+            existing = result[tag]
+            if isinstance(existing, list):
+                existing.append(value)
+            else:
+                result[tag] = [existing, value]
+        else:
+            result[tag] = value
+    return result
+
+
+@dataclass
+class Response:
+    """One ``*Rs`` element out of the batch."""
+
+    name: str
+    status_code: int
+    status_severity: str
+    status_message: str
+    request_id: str | None = None
+    records: list[dict[str, Any]] = field(default_factory=list)
+    iterator_remaining_count: int | None = None
+    iterator_id: str | None = None
+
+    @property
+    def ok(self) -> bool:
+        """True when QuickBooks actually processed the request.
+
+        Status 1 ("nothing found") counts as OK: an empty result set is a valid
+        answer, unlike status 3100 which means the request never ran.
+        """
+        return self.status_code in (STATUS_OK, STATUS_NOTHING_FOUND)
+
+    @property
+    def empty(self) -> bool:
+        return self.status_code == STATUS_NOTHING_FOUND or not self.records
+
+    @property
+    def has_more(self) -> bool:
+        return bool(self.iterator_remaining_count)
+
+    @property
+    def entity(self) -> str:
+        """``CustomerQueryRs`` -> ``Customer``."""
+        name = self.name
+        for suffix in ("QueryRs", "AddRs", "ModRs", "DelRs", "VoidRs", "Rs"):
+            if name.endswith(suffix):
+                return name[: -len(suffix)]
+        return name
+
+    def raise_for_status(self) -> Response:
+        if not self.ok:
+            raise QBXMLStatusError(self)
+        return self
+
+    def __iter__(self) -> Iterator[dict[str, Any]]:
+        return iter(self.records)
+
+    def __len__(self) -> int:
+        return len(self.records)
+
+
+@dataclass
+class ResponseSet:
+    """The whole ``QBXMLMsgsRs`` batch."""
+
+    responses: list[Response] = field(default_factory=list)
+
+    def __iter__(self) -> Iterator[Response]:
+        return iter(self.responses)
+
+    def __len__(self) -> int:
+        return len(self.responses)
+
+    def __getitem__(self, index: int) -> Response:
+        return self.responses[index]
+
+    @property
+    def ok(self) -> bool:
+        return all(response.ok for response in self.responses)
+
+    @property
+    def failures(self) -> list[Response]:
+        return [response for response in self.responses if not response.ok]
+
+    def by_request_id(self, request_id: str) -> Response | None:
+        for response in self.responses:
+            if response.request_id == request_id:
+                return response
+        return None
+
+    def first(self, name: str | None = None) -> Response:
+        for response in self.responses:
+            if name is None or response.name == name or response.entity == name:
+                return response
+        raise KeyError(name)
+
+    def raise_for_status(self) -> ResponseSet:
+        for response in self.responses:
+            response.raise_for_status()
+        return self
+
+
+#: Elements inside a ``*Rs`` that are metadata rather than returned records.
+_NON_RECORD_TAGS = frozenset({"ErrorRecovery"})
+
+
+def parse_response(payload: str | bytes) -> ResponseSet:
+    """Parse a full qbXML response document.
+
+    An empty payload is not an error: QBWC passes an empty string through
+    ``receiveResponseXML`` when a request was skipped.
+    """
+    if isinstance(payload, bytes):
+        payload = payload.decode("utf-8")
+    payload = payload.strip()
+    if not payload:
+        return ResponseSet()
+
+    try:
+        root = ET.fromstring(payload)
+    except ET.ParseError as exc:
+        raise QBXMLParseError(f"malformed qbXML: {exc}") from exc
+
+    if root.tag != "QBXML":
+        raise QBXMLParseError(f"expected a QBXML root, got {root.tag!r}")
+
+    msgs = root.find("QBXMLMsgsRs")
+    if msgs is None:
+        raise QBXMLParseError("response has no QBXMLMsgsRs")
+
+    responses = [_parse_one(node) for node in msgs]
+    return ResponseSet(responses=responses)
+
+
+def _parse_one(node: ET.Element) -> Response:
+    try:
+        status_code = int(node.get("statusCode", "0"))
+    except ValueError as exc:
+        raise QBXMLParseError(f"non-numeric statusCode on {node.tag}") from exc
+
+    remaining = node.get("iteratorRemainingCount")
+    response = Response(
+        name=node.tag,
+        status_code=status_code,
+        status_severity=node.get("statusSeverity", Severity.INFO.value),
+        status_message=node.get("statusMessage", ""),
+        request_id=node.get("requestID"),
+        iterator_remaining_count=int(remaining) if remaining is not None else None,
+        iterator_id=node.get("iteratorID"),
+    )
+
+    for child in node:
+        if child.tag in _NON_RECORD_TAGS:
+            continue
+        value = _to_dict(child)
+        response.records.append(value if isinstance(value, dict) else {child.tag: value})
+
+    return response

qbwc_kit/qbxml/types.py

@@ -0,0 +1,63 @@
+"""Shared qbXML vocabulary."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class OnError(str, Enum):
+    """``QBXMLMsgsRq/@onError``.
+
+    ``STOP`` aborts the batch at the first failing request. ``CONTINUE`` runs
+    every request and reports per-request status, which is what you want for a
+    read-only sync where one unsupported entity should not blank the rest.
+    """
+
+    STOP = "stopOnError"
+    CONTINUE = "continueOnError"
+
+
+class Severity(str, Enum):
+    INFO = "Info"
+    WARN = "Warn"
+    ERROR = "Error"
+
+
+#: Status codes worth branching on. QuickBooks defines several hundred; these
+#: are the ones that change control flow rather than just being logged.
+STATUS_OK = 0
+STATUS_NOTHING_FOUND = 1
+STATUS_UNSUPPORTED_REQUEST = 3100
+STATUS_INSUFFICIENT_PERMISSION = 3260
+STATUS_STALE_EDIT_SEQUENCE = 3200
+STATUS_OBJECT_NOT_FOUND = 500
+
+#: Entities whose Query requests accept ``iterator``/``iteratorID`` attributes.
+#: Asking for an iterator on anything else is a parse error from QuickBooks,
+#: so it is checked at build time instead.
+ITERATOR_ENTITIES = frozenset(
+    {
+        "AccountQueryRq",
+        "BillQueryRq",
+        "CheckQueryRq",
+        "CreditMemoQueryRq",
+        "CustomerQueryRq",
+        "DepositQueryRq",
+        "EstimateQueryRq",
+        "InvoiceQueryRq",
+        "ItemInventoryQueryRq",
+        "ItemQueryRq",
+        "ItemReceiptQueryRq",
+        "JournalEntryQueryRq",
+        "PurchaseOrderQueryRq",
+        "ReceivePaymentQueryRq",
+        "SalesOrderQueryRq",
+        "SalesReceiptQueryRq",
+        "TimeTrackingQueryRq",
+        "VendorQueryRq",
+    }
+)
+
+
+def iterator_supported(request_name: str) -> bool:
+    return request_name in ITERATOR_ENTITIES

qbwc_kit/server.py

@@ -0,0 +1,59 @@
+"""FastAPI adapter.
+
+Kept deliberately thin: the protocol lives in :mod:`qbwc_kit.service`, and this
+module only maps HTTP verbs onto it. FastAPI is an optional dependency, so
+importing this module without it raises a clear error instead of an
+``ImportError`` from three frames down.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .service import QBWCService
+from .wsdl import build_wsdl
+
+if TYPE_CHECKING:  # pragma: no cover
+    from fastapi import FastAPI
+
+try:
+    from fastapi import FastAPI, Request, Response
+except ModuleNotFoundError as exc:  # pragma: no cover - exercised by install shape, not tests
+    raise ModuleNotFoundError(
+        "qbwc_kit.server needs FastAPI. Install it with: pip install fastapi"
+    ) from exc
+
+#: QBWC sends this exact content type and expects it back.
+SOAP_CONTENT_TYPE = "text/xml; charset=utf-8"
+
+
+def create_app(
+    service: QBWCService,
+    *,
+    endpoint_url: str,
+    path: str = "/qbwc",
+    app: FastAPI | None = None,
+    service_name: str = "QBWebConnectorSvc",
+) -> FastAPI:
+    """Mount ``service`` on a FastAPI app.
+
+    ``endpoint_url`` is the externally reachable URL of ``path``. QBWC reads it
+    out of the WSDL and posts there, so behind a reverse proxy it must be the
+    public URL, not ``http://localhost``.
+    """
+    app = app or FastAPI(title="QuickBooks Web Connector service", docs_url=None, redoc_url=None)
+    wsdl = build_wsdl(endpoint_url, service_name=service_name)
+
+    @app.get(path)
+    async def get_wsdl(request: Request) -> Response:
+        # QBWC asks for the WSDL as "?wsdl"; browsers and health checks hit the
+        # bare path. Serving the WSDL for both is harmless and saves a support
+        # round trip when someone pastes the URL into a browser to check it.
+        return Response(content=wsdl, media_type=SOAP_CONTENT_TYPE)
+
+    @app.post(path)
+    async def handle_soap(request: Request) -> Response:
+        body = await request.body()
+        return Response(content=service.dispatch(body), media_type=SOAP_CONTENT_TYPE)
+
+    return app