icedcoffee-sync 0.1.0.dev5__py3-none-any.whl

icedcoffee_sync/erpnext/accounts.py

@@ -0,0 +1,183 @@
+"""ERPNext Account facts: how accounts are named, and what types exist.
+
+The constants here are a snapshot of ERPNext 16's Select options, measured on
+2026-08-25. They exist so a chart can be validated offline, before any request
+is sent. `icedcoffee_sync.erpnext.accounts.live_account_types` reads the same list from
+a running site, and a live test asserts the two agree -- that is what catches an
+ERPNext upgrade adding or removing a type.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Any, Protocol
+
+from icedcoffee_sync.apply.model import LiveAccount
+
+ROOT_TYPES: frozenset[str] = frozenset({"Asset", "Liability", "Income", "Expense", "Equity"})
+
+ACCOUNT_TYPES: frozenset[str] = frozenset({
+    "Accumulated Depreciation",
+    "Asset Received But Not Billed",
+    "Bank",
+    "Capital Work in Progress",
+    "Cash",
+    "Chargeable",
+    "Cost of Goods Sold",
+    "Current Asset",
+    "Current Liability",
+    "Depreciation",
+    "Direct Expense",
+    "Direct Income",
+    "Equity",
+    "Expense Account",
+    "Expenses Included In Asset Valuation",
+    "Expenses Included In Valuation",
+    "Fixed Asset",
+    "Income Account",
+    "Indirect Expense",
+    "Indirect Income",
+    "Liability",
+    "Payable",
+    "Receivable",
+    "Round Off",
+    "Round Off for Opening",
+    "Service Received But Not Billed",
+    "Stock",
+    "Stock Adjustment",
+    "Stock Received But Not Billed",
+    "Tax",
+    "Temporary",
+})
+
+
+class UnknownAccountTypeError(ValueError):
+    """An account_type outside ERPNext's Select options.
+
+    Raised locally so a bad chart fails before a request is built, rather than
+    surfacing as a server-side ValidationError halfway through an apply.
+    """
+
+
+def validate_account_type(value: str | None) -> None:
+    """Refuse an account_type ERPNext would reject. Absent is allowed."""
+    if not value:
+        return
+    if value not in ACCOUNT_TYPES:
+        allowed = ", ".join(sorted(ACCOUNT_TYPES))
+        raise UnknownAccountTypeError(f"unknown account_type {value!r}; ERPNext allows: {allowed}")
+
+
+def document_name(account_name: str, abbr: str, account_number: str | None = None) -> str:
+    """Derive an Account's document name the way ERPNext does.
+
+    Numbered accounts are `{number} - {name} - {abbr}`; unnumbered ones drop
+    the number and its separator. Frappe returns "" for an unset number, so an
+    empty string counts as absent -- treating it as present would produce a
+    leading " - " that matches no document.
+    """
+    if not account_name:
+        raise ValueError("account_name must not be empty")
+    if not abbr:
+        raise ValueError("abbr must not be empty")
+    if account_number:
+        return f"{account_number} - {account_name} - {abbr}"
+    return f"{account_name} - {abbr}"
+
+
+_CHART_FIELDS = [
+    "name",
+    "account_number",
+    "account_name",
+    "parent_account",
+    "is_group",
+    "root_type",
+    "account_type",
+    "disabled",
+]
+
+
+class _Reader(Protocol):
+    """The slice of Client these reads need. Keeps the test doubles honest."""
+
+    def list(self, doctype: str, **kwargs: Any) -> Any: ...
+    def get(self, doctype: str, name: str) -> Any: ...
+    def iter_all(self, doctype: str, **kwargs: Any) -> Iterator[dict[str, Any]]: ...
+
+
+def company_abbr(client: _Reader, company: str) -> str:
+    """The company's abbreviation, which every account's document name ends in."""
+    rows = client.list("Company", fields=["name", "abbr"], filters=[["name", "=", company]], limit=1)
+    if not rows:
+        raise LookupError(f"no Company named {company!r} on this site")
+    abbr = rows[0].get("abbr")
+    if not abbr:
+        raise LookupError(f"Company {company!r} has no abbreviation set")
+    return str(abbr)
+
+
+def read_chart(client: _Reader, company: str) -> list[LiveAccount]:
+    """Every account on the site for one company.
+
+    Frappe returns "" rather than null for unset links and selects, normalised
+    to None here -- leaving "" in place would make an unparented root look
+    like a child of an account named "". Paged through `iter_all`, not a
+    single capped `list` call: a silently truncated read would make every
+    account past the cutoff look absent and get it created again as a duplicate.
+    """
+    rows = client.iter_all(
+        "Account",
+        fields=_CHART_FIELDS,
+        filters=[["company", "=", company]],
+        order_by="name asc",
+    )
+    return [
+        LiveAccount(
+            document_name=row["name"],
+            number=row.get("account_number") or "",
+            name=row["account_name"],
+            parent_document_name=row.get("parent_account") or None,
+            is_group=bool(row.get("is_group")),
+            root_type=row.get("root_type") or "",
+            account_type=row.get("account_type") or None,
+            disabled=bool(row.get("disabled")),
+        )
+        for row in rows
+    ]
+
+
+def accounts_with_entries(client: _Reader, document_names: list[str]) -> set[str]:
+    """Which of these accounts already carry ledger entries.
+
+    One `limit=1` presence probe per account, not a single batched `IN`
+    query: a shared `limit` over an `IN` filter caps total ROWS, not
+    accounts, so one account with heavy history could starve the presence
+    signal for every other name in the batch and report them as entry-free
+    when they are not -- exactly what this guard exists to prevent. The
+    honest cost: one request per account, acceptable for a tool a human
+    runs and reads, not a hot path.
+    """
+    found: set[str] = set()
+    for name in document_names:
+        rows = client.list(
+            "GL Entry",
+            fields=["account"],
+            filters=[["account", "=", name]],
+            limit=1,
+        )
+        if rows:
+            found.add(name)
+    return found
+
+
+def live_account_types(client: _Reader) -> frozenset[str]:
+    """The account_type Select options this site actually offers.
+
+    Used by a live test to catch an ERPNext upgrade drifting from the checked-in
+    ACCOUNT_TYPES snapshot.
+    """
+    meta = client.get("DocType", "Account")
+    for field in meta.get("fields", []):
+        if field.get("fieldname") == "account_type":
+            return frozenset(o for o in (field.get("options") or "").split("\n") if o)
+    raise LookupError("Account doctype has no account_type field")

icedcoffee_sync/erpnext/comment.py

@@ -0,0 +1,62 @@
+"""Comments on a Frappe document.
+
+Frappe exposes `frappe.desk.form.utils.add_comment(reference_doctype,
+reference_name, content, comment_email, comment_by)` (verified on
+version-16-hotfix), which checks read permission on the document and creates a
+`Comment` of type "Comment". It is not a committing method, so a client
+without submit capability may call it. Listing goes through the `Comment`
+doctype directly, filtered to the document, which is how idempotency-by-content
+is checked before adding one.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any, Protocol
+
+ADD_COMMENT = "frappe.desk.form.utils.add_comment"
+DOCTYPE_COMMENT = "Comment"
+DEFAULT_EMAIL = "integration@example.com"
+DEFAULT_BY = "Transpire"
+
+
+class _Caller(Protocol):
+    def call(self, dotted_path: str, params: dict[str, Any] | None = None) -> Any: ...
+    def iter_all(self, doctype: str, **kwargs: Any) -> Iterable[dict[str, Any]]: ...
+
+
+def add_comment(
+    client: _Caller,
+    doctype: str,
+    name: str,
+    content: str,
+    *,
+    email: str = DEFAULT_EMAIL,
+    by: str = DEFAULT_BY,
+) -> dict[str, Any]:
+    """Add a Comment to `doctype`/`name`. Returns the created Comment document."""
+    return client.call(
+        ADD_COMMENT,
+        {
+            "reference_doctype": doctype,
+            "reference_name": name,
+            "content": content,
+            "comment_email": email,
+            "comment_by": by,
+        },
+    )
+
+
+def list_comments(client: _Caller, doctype: str, name: str) -> list[dict[str, Any]]:
+    """Every "Comment"-type Comment on the document, with its content.
+
+    Pages to the end: a busy document's comment history outgrows any one page,
+    and a truncated read is what makes an already-posted comment look absent.
+    """
+    return list(
+        client.iter_all(
+            DOCTYPE_COMMENT,
+            fields=["name", "content", "comment_email", "creation"],
+            filters={"reference_doctype": doctype, "reference_name": name, "comment_type": "Comment"},
+        )
+    )

icedcoffee_sync/erpnext/company.py

@@ -0,0 +1,102 @@
+"""Company's default-account links.
+
+ERPNext posts automatically to whichever account Company names, and Frappe
+silently drops an update naming a field that doesn't exist. Validated by
+reading Company itself, not `DocType` meta -- a role permission there
+doesn't take effect the way it does elsewhere (measured live).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any, Protocol
+
+# Company Link-to-Account fields without "account" in the name -- measured live.
+_ACCOUNT_FIELD_NAME_EXCEPTIONS: frozenset[str] = frozenset({
+    "round_off_for_opening",
+    "stock_received_but_not_billed",
+    "asset_received_but_not_billed",
+})
+
+
+def _plausibly_an_account_field(field: str) -> bool:
+    """Whether `field` is plausibly a Link-to-Account field, by name (e.g. not `default_warehouse`)."""
+    return "account" in field or field in _ACCOUNT_FIELD_NAME_EXCEPTIONS
+
+
+class UnknownCompanyFieldError(ValueError):
+    """A default-account field this ERPNext build does not have."""
+
+
+class DefaultNotAppliedError(ValueError):
+    """A default-account field exists but did not read back as requested."""
+
+
+class _CompanyClient(Protocol):
+    def get(self, doctype: str, name: str) -> Any: ...
+    def update(self, doctype: str, name: str, doc: dict[str, Any]) -> Any: ...
+
+
+def clear_defaults_pointing_at(client: _CompanyClient, company: str, account_names: frozenset[str]) -> list[str]:
+    """Null out every Company default pointing at one of `account_names`, for `--allow-unapplied` prune.
+
+    Returns:
+        The cleared field names, sorted. No matches makes no request.
+    """
+    doc = client.get("Company", company)
+    cleared = sorted(
+        field
+        for field, value in doc.items()
+        if field != "name"
+        and not field.startswith("_")
+        and isinstance(value, str)
+        and value in account_names
+        and _plausibly_an_account_field(field)
+    )
+    if not cleared:
+        return []
+    client.update("Company", company, dict.fromkeys(cleared))
+    return cleared
+
+
+def require_default_fields(client: _CompanyClient, company: str, fields: Iterable[str]) -> None:
+    """Raise `UnknownCompanyFieldError` naming any of `fields` absent from `company`. A pre-flight; writes nothing."""
+    doc = client.get("Company", company)
+    missing = sorted(field for field in fields if field not in doc)
+    if missing:
+        raise UnknownCompanyFieldError(
+            f"Company {company!r} has no field(s): {', '.join(missing)} -- "
+            f"absent from the document read before applying anything"
+        )
+
+
+def set_default_accounts(client: _CompanyClient, company: str, defaults: dict[str, str]) -> list[str]:
+    """Point Company's defaults at specific accounts, then confirm each one landed.
+
+    Rejects any field absent from Company before writing, and reads back
+    after to confirm each value actually stuck.
+
+    Returns:
+        The field names written, sorted. Empty input makes no request.
+    """
+    if not defaults:
+        return []
+
+    pre = client.get("Company", company)
+    missing = sorted(field for field in defaults if field not in pre)
+    if missing:
+        raise UnknownCompanyFieldError(
+            f"Company {company!r} has no field(s): {', '.join(missing)} -- "
+            f"absent from the document read before writing anything"
+        )
+
+    client.update("Company", company, dict(defaults))
+    doc = client.get("Company", company)
+
+    for field in sorted(defaults):
+        wanted = defaults[field]
+        got = doc[field]
+        if got != wanted:
+            raise DefaultNotAppliedError(f"{field}: wanted {wanted!r}, got {got!r} on Company {company!r}")
+
+    return sorted(defaults)

icedcoffee_sync/erpnext/documents.py

@@ -0,0 +1,179 @@
+"""The ERPNext documents Transpire writes, as dataclasses with `as_document()`.
+
+Shared by `graft` (which pushes a tenant's curated data onto a demo site) and
+phloem's connector (which stamps identity markers onto a customer's site and
+drafts documents there). One definition, so the two never drift on a field
+name or a marker value.
+
+Every document carries `transpire_source = transpire`, which is what keeps a
+row we wrote distinguishable from a site's native data and from anything a
+person types later.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+from typing import Any
+
+# What every document this connector writes is stamped with, so a pushed row
+# stays distinguishable from the site's own ERPNext demo data and from
+# anything a person types in later.
+SOURCE_MARKER = "transpire"
+
+FIELD_SOURCE = "transpire_source"
+FIELD_REF = "transpire_ref"
+FIELD_ORDER_NO = "transpire_order_no"
+
+# Present on every ERPNext site out of the box, so the connector needs no
+# site configuration of its own.
+DEFAULT_ITEM_GROUP = "All Item Groups"
+DEFAULT_UOM = "Nos"
+
+
+@dataclasses.dataclass(frozen=True)
+class DesiredCustomField:
+    """One Custom Field the connector needs before it can key anything.
+
+    `document_name` is deterministic (`<dt>-<fieldname>`), which is what makes
+    ensuring these idempotent without a query on anything but the name.
+
+    Deliberately NOT `unique`: a unique index over an existing doctype whose
+    rows all carry an empty string for the new column is rejected by MariaDB
+    on the second empty row, so marking the marker unique would fail on any
+    site that already holds suppliers -- which is every site.
+    """
+
+    dt: str
+    fieldname: str
+    label: str
+    insert_after: str
+    fieldtype: str = "Data"
+
+    @property
+    def document_name(self) -> str:
+        return f"{self.dt}-{self.fieldname}"
+
+    def as_document(self) -> dict[str, Any]:
+        return {
+            "dt": self.dt,
+            "fieldname": self.fieldname,
+            "label": self.label,
+            "fieldtype": self.fieldtype,
+            "insert_after": self.insert_after,
+            # Machine-owned: editable through the API, not through the form.
+            "read_only": 1,
+            # An amended document starts as a copy; carrying the marker onto
+            # it would claim Transpire wrote a row it has never seen.
+            "no_copy": 1,
+        }
+
+
+CUSTOM_FIELDS: tuple[DesiredCustomField, ...] = (
+    DesiredCustomField("Supplier", FIELD_SOURCE, "Transpire Source", insert_after="supplier_name"),
+    DesiredCustomField("Supplier", FIELD_REF, "Transpire Vendor ID", insert_after=FIELD_SOURCE),
+    # An Item needs no `transpire_ref`: its `item_code` IS the reference, and
+    # Frappe names the document from it. The source marker is what a site's own
+    # demo Items lack, which is what makes a reused one recognisable.
+    DesiredCustomField("Item", FIELD_SOURCE, "Transpire Source", insert_after="item_name"),
+    DesiredCustomField("Purchase Order", FIELD_SOURCE, "Transpire Source", insert_after="supplier"),
+    DesiredCustomField("Purchase Order", FIELD_REF, "Transpire Order ID", insert_after=FIELD_SOURCE),
+    DesiredCustomField("Purchase Order", FIELD_ORDER_NO, "Vendor Order Number", insert_after=FIELD_REF),
+)
+
+# The one marker phloem's onboarding stamps onto a customer's Suppliers.
+SUPPLIER_REF_FIELD = next(f for f in CUSTOM_FIELDS if f.dt == "Supplier" and f.fieldname == FIELD_REF)
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class DesiredSupplier:
+    """One Supplier, keyed by the tenant's vendor id rather than by its name."""
+
+    vendor_id: str
+    supplier_name: str
+    disabled: bool = False
+
+    def as_document(self) -> dict[str, Any]:
+        return {
+            "supplier_name": self.supplier_name,
+            "disabled": 1 if self.disabled else 0,
+            FIELD_SOURCE: SOURCE_MARKER,
+            FIELD_REF: self.vendor_id,
+        }
+
+
+@dataclasses.dataclass(frozen=True)
+class DesiredItem:
+    """One Item, named by a deterministic slug so creating it is idempotent.
+
+    Stock-maintained: these are parts a shop holds in inventory, and ERPNext
+    writes no stock ledger entry for an item with Maintain Stock off -- so a
+    Purchase Receipt against a non-stock item moves nothing, which is the half
+    of the demo that matters. The warehouse and valuation rate this drags in
+    are answered by the site's company defaults and by the line's own rate.
+    """
+
+    item_code: str
+    item_name: str
+    description: str | None
+
+    def as_document(self) -> dict[str, Any]:
+        return {
+            "item_code": self.item_code,
+            "item_name": self.item_name,
+            "description": self.description or self.item_name,
+            "item_group": DEFAULT_ITEM_GROUP,
+            "stock_uom": DEFAULT_UOM,
+            "is_stock_item": 1,
+            FIELD_SOURCE: SOURCE_MARKER,
+        }
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class DesiredPurchaseOrderItem:
+    """One Purchase Order line.
+
+    `rate` is the unit price in the site's company currency, or 0 when the
+    caller has no price it can vouch for: the connector never invents one.
+    """
+
+    item_code: str
+    item_name: str = ""
+    description: str | None = None
+    qty: int
+    schedule_date: str
+    rate: float = 0
+
+    def as_document(self) -> dict[str, Any]:
+        return {
+            "item_code": self.item_code,
+            "item_name": self.item_name,
+            "description": self.description or self.item_name,
+            "qty": self.qty,
+            "rate": self.rate,
+            "uom": DEFAULT_UOM,
+            "conversion_factor": 1,
+            "schedule_date": self.schedule_date,
+        }
+
+
+@dataclasses.dataclass(frozen=True)
+class DesiredPurchaseOrder:
+    """One Purchase Order, minus the Supplier name only the site can assign."""
+
+    order_id: str
+    vendor_id: str
+    order_number: str | None
+    transaction_date: str
+    schedule_date: str
+    items: tuple[DesiredPurchaseOrderItem, ...]
+
+    def as_document(self, supplier: str) -> dict[str, Any]:
+        return {
+            "supplier": supplier,
+            "transaction_date": self.transaction_date,
+            "schedule_date": self.schedule_date,
+            "items": [item.as_document() for item in self.items],
+            FIELD_SOURCE: SOURCE_MARKER,
+            FIELD_REF: self.order_id,
+            FIELD_ORDER_NO: self.order_number or "",
+        }

icedcoffee_sync/erpnext/ensure.py

@@ -0,0 +1,34 @@
+"""Get-or-insert by document name.
+
+Frappe addresses a document by its name, and for the doctypes we provision
+(Custom Field, Webhook) the name is deterministic -- either Frappe derives it
+from the content or the caller sets it. So "make sure this exists" is one
+`get` that is allowed to miss, then one `insert`. An existing document is
+left exactly as it is: re-running setup must never rewrite what a person
+changed on the site.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol
+
+from icedcoffee_sync.frappe.errors import DoesNotExistError
+
+
+class _Writer(Protocol):
+    def get(self, doctype: str, name: str) -> Any: ...
+    def insert(self, doctype: str, doc: dict[str, Any]) -> Any: ...
+
+
+def ensure_by_name(client: _Writer, doctype: str, name: str, doc: dict[str, Any]) -> bool:
+    """Insert `doc` as `doctype` unless a document named `name` already exists.
+
+    Returns:
+        True when this call inserted it; False when it was already there.
+    """
+    try:
+        client.get(doctype, name)
+    except DoesNotExistError:
+        client.insert(doctype, doc)
+        return True
+    return False