icedcoffee-sync 0.1.0.dev9__tar.gz → 0.1.0.dev13__tar.gz

{icedcoffee_sync-0.1.0.dev9 → icedcoffee_sync-0.1.0.dev13}/.gitignore

@@ -8,3 +8,4 @@ build/
 .ruff_cache/
 .env
 report.xml
+.kata.local.toml

icedcoffee_sync-0.1.0.dev13/.kata.toml

@@ -0,0 +1,4 @@
+version = 1
+
+[project]
+name = "icedcoffee-sync"

{icedcoffee_sync-0.1.0.dev9 → icedcoffee_sync-0.1.0.dev13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: icedcoffee-sync
-Version: 0.1.0.dev9
+Version: 0.1.0.dev13
 Summary: Typed sync and async client for the Frappe and ERPNext REST API
 Author-email: Gavin Carothers <gavin@carothers.name>
 License-Expression: Apache-2.0
@@ -109,10 +109,36 @@ with Client(config) as client:
     print(created)
 ```
 
+- `icedcoffee_sync.erpnext.documents`: Supplier, Item and Purchase Order documents, and the Custom Fields that mark them as yours.
+- `icedcoffee_sync.erpnext.webhook`: provision Purchase Order Webhooks pointed at your receiver.
 - `icedcoffee_sync.erpnext.purchase`: typed Purchase Order reads and draft Purchase Receipt documents.
 - `icedcoffee_sync.erpnext.company`: validate, set and clear Company default-account links.
 - `icedcoffee_sync.erpnext.comment`: add and list comments on documents.
 
+### Your namespace
+
+The documents, Webhooks and Purchase Order reads take a `Namespace`: the names
+your integration leaves on a site. `name` prefixes the Custom Fields
+(`<name>_source`, `<name>_ref`, `<name>_order_no`) and the Webhook names, and
+is the marker stamped on every document you write. `label` prefixes the field
+labels a person sees on the form. `site_header` carries your site id on each
+Webhook delivery, so one receiving URL can tell sites apart.
+
+```python
+from icedcoffee_sync.erpnext.documents import DesiredSupplier, custom_fields
+from icedcoffee_sync.erpnext.namespace import Namespace
+
+ns = Namespace(name="acme", label="Acme", site_header="X-Acme-Site")
+fields = custom_fields(ns)  # ensure these before writing documents
+supplier = DesiredSupplier(vendor_id="v-123", supplier_name="Example Supplier")
+print(supplier.as_document(namespace=ns))
+# {'supplier_name': 'Example Supplier', 'disabled': 0, 'acme_source': 'acme', 'acme_ref': 'v-123'}
+```
+
+Pick the namespace once per site. Documents written under one name are
+invisible to readers under another, and the old fields and Webhooks stay on
+the site.
+
 ## Reconciliation
 
 `icedcoffee_sync.apply` reconciles charts through the synchronous client.

{icedcoffee_sync-0.1.0.dev9 → icedcoffee_sync-0.1.0.dev13}/README.md

@@ -98,10 +98,36 @@ with Client(config) as client:
     print(created)
 ```
 
+- `icedcoffee_sync.erpnext.documents`: Supplier, Item and Purchase Order documents, and the Custom Fields that mark them as yours.
+- `icedcoffee_sync.erpnext.webhook`: provision Purchase Order Webhooks pointed at your receiver.
 - `icedcoffee_sync.erpnext.purchase`: typed Purchase Order reads and draft Purchase Receipt documents.
 - `icedcoffee_sync.erpnext.company`: validate, set and clear Company default-account links.
 - `icedcoffee_sync.erpnext.comment`: add and list comments on documents.
 
+### Your namespace
+
+The documents, Webhooks and Purchase Order reads take a `Namespace`: the names
+your integration leaves on a site. `name` prefixes the Custom Fields
+(`<name>_source`, `<name>_ref`, `<name>_order_no`) and the Webhook names, and
+is the marker stamped on every document you write. `label` prefixes the field
+labels a person sees on the form. `site_header` carries your site id on each
+Webhook delivery, so one receiving URL can tell sites apart.
+
+```python
+from icedcoffee_sync.erpnext.documents import DesiredSupplier, custom_fields
+from icedcoffee_sync.erpnext.namespace import Namespace
+
+ns = Namespace(name="acme", label="Acme", site_header="X-Acme-Site")
+fields = custom_fields(ns)  # ensure these before writing documents
+supplier = DesiredSupplier(vendor_id="v-123", supplier_name="Example Supplier")
+print(supplier.as_document(namespace=ns))
+# {'supplier_name': 'Example Supplier', 'disabled': 0, 'acme_source': 'acme', 'acme_ref': 'v-123'}
+```
+
+Pick the namespace once per site. Documents written under one name are
+invisible to readers under another, and the old fields and Webhooks stay on
+the site.
+
 ## Reconciliation
 
 `icedcoffee_sync.apply` reconciles charts through the synchronous client.

{icedcoffee_sync-0.1.0.dev9 → icedcoffee_sync-0.1.0.dev13}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "icedcoffee-sync"
-version = "0.1.0.dev9"
+version = "0.1.0.dev13"
 description = "Typed sync and async client for the Frappe and ERPNext REST API"
 readme = "README.md"
 authors = [{ name = "Gavin Carothers", email = "gavin@carothers.name" }]

{icedcoffee_sync-0.1.0.dev9 → icedcoffee_sync-0.1.0.dev13}/src/icedcoffee_sync/erpnext/comment.py

@@ -16,8 +16,6 @@ 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):
@@ -31,10 +29,10 @@ def add_comment(
     name: str,
     content: str,
     *,
-    email: str = DEFAULT_EMAIL,
-    by: str = DEFAULT_BY,
+    email: str,
+    by: str,
 ) -> dict[str, Any]:
-    """Add a Comment to `doctype`/`name`. Returns the created Comment document."""
+    """Add a Comment to `doctype`/`name`, signed `by` <`email`>. Returns the created Comment document."""
     return client.call(
         ADD_COMMENT,
         {

{icedcoffee_sync-0.1.0.dev9 → icedcoffee_sync-0.1.0.dev13}/src/icedcoffee_sync/erpnext/documents.py

@@ -1,13 +1,11 @@
-"""The ERPNext documents Transpire writes, as dataclasses with `as_document()`.
+"""The ERPNext documents an integration 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.
+One definition for every writer, so two programs writing to the same site
+under one `Namespace` 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.
+Every document carries `<namespace>_source = <namespace>`, which is what keeps
+a row the integration wrote distinguishable from a site's native data and from
+anything a person types later.
 """
 
 from __future__ import annotations
@@ -15,16 +13,9 @@ 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"
+from icedcoffee_sync.erpnext.namespace import Namespace
 
-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
+# Present on every ERPNext site out of the box, so the integration needs no
 # site configuration of its own.
 DEFAULT_ITEM_GROUP = "All Item Groups"
 DEFAULT_UOM = "Nos"
@@ -32,7 +23,7 @@ DEFAULT_UOM = "Nos"
 
 @dataclasses.dataclass(frozen=True)
 class DesiredCustomField:
-    """One Custom Field the connector needs before it can key anything.
+    """One Custom Field the integration 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.
@@ -63,25 +54,32 @@ class DesiredCustomField:
             # 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.
+            # it would claim the integration 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),
-)
+def custom_fields(namespace: Namespace) -> tuple[DesiredCustomField, ...]:
+    """Every Custom Field the documents below write into, named for `namespace`."""
+    ns = namespace
+    return (
+        DesiredCustomField("Supplier", ns.source_field, f"{ns.label} Source", insert_after="supplier_name"),
+        supplier_ref_field(ns),
+        # An Item needs no ref field: 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", ns.source_field, f"{ns.label} Source", insert_after="item_name"),
+        DesiredCustomField("Purchase Order", ns.source_field, f"{ns.label} Source", insert_after="supplier"),
+        DesiredCustomField("Purchase Order", ns.ref_field, f"{ns.label} Order ID", insert_after=ns.source_field),
+        DesiredCustomField("Purchase Order", ns.order_no_field, "Vendor Order Number", insert_after=ns.ref_field),
+    )
+
 
-# 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)
+def supplier_ref_field(namespace: Namespace) -> DesiredCustomField:
+    """The Supplier's ref field on its own: what links a site's existing Supplier to the caller's vendor id."""
+    return DesiredCustomField(
+        "Supplier", namespace.ref_field, f"{namespace.label} Vendor ID", insert_after=namespace.source_field
+    )
 
 
 @dataclasses.dataclass(frozen=True, kw_only=True)
@@ -92,12 +90,12 @@ class DesiredSupplier:
     supplier_name: str
     disabled: bool = False
 
-    def as_document(self) -> dict[str, Any]:
+    def as_document(self, *, namespace: Namespace) -> 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,
+            namespace.source_field: namespace.marker,
+            namespace.ref_field: self.vendor_id,
         }
 
 
@@ -116,7 +114,7 @@ class DesiredItem:
     item_name: str
     description: str | None
 
-    def as_document(self) -> dict[str, Any]:
+    def as_document(self, *, namespace: Namespace) -> dict[str, Any]:
         return {
             "item_code": self.item_code,
             "item_name": self.item_name,
@@ -124,7 +122,7 @@ class DesiredItem:
             "item_group": DEFAULT_ITEM_GROUP,
             "stock_uom": DEFAULT_UOM,
             "is_stock_item": 1,
-            FIELD_SOURCE: SOURCE_MARKER,
+            namespace.source_field: namespace.marker,
         }
 
 
@@ -133,7 +131,7 @@ 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.
+    caller has no price it can vouch for: the integration never invents one.
     """
 
     item_code: str
@@ -167,13 +165,13 @@ class DesiredPurchaseOrder:
     schedule_date: str
     items: tuple[DesiredPurchaseOrderItem, ...]
 
-    def as_document(self, supplier: str) -> dict[str, Any]:
+    def as_document(self, supplier: str, *, namespace: Namespace) -> 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 "",
+            namespace.source_field: namespace.marker,
+            namespace.ref_field: self.order_id,
+            namespace.order_no_field: self.order_number or "",
         }

icedcoffee_sync-0.1.0.dev13/src/icedcoffee_sync/erpnext/namespace.py

@@ -0,0 +1,64 @@
+"""The names an integration writes onto a site under, supplied by the caller.
+
+An integration that writes to an ERPNext site leaves its own name there: the
+Custom Fields that mark the rows it wrote, the marker value in them, the names
+of the Webhooks it provisions, and the header that tells its receiver which
+site a delivery came from. None of those belong to this library, so every
+function that writes or reads them takes a `Namespace`.
+
+Changing a namespace for a site that already has documents written under it
+orphans them: the old Custom Fields and Webhooks stay on the site under the old
+names, and nothing here recognises them any more.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import re
+
+# A Frappe fieldname: lowercase, starting with a letter. The namespace name
+# prefixes every Custom Field, so it has to be one too.
+_FIELDNAME = re.compile(r"[a-z][a-z0-9_]*")
+# An HTTP header name (RFC 9110 token), narrowed to what a person would type.
+_HEADER = re.compile(r"[A-Za-z0-9][A-Za-z0-9-]*")
+
+
+@dataclasses.dataclass(frozen=True)
+class Namespace:
+    """Who is writing to the site.
+
+    `name` prefixes every Custom Field (`<name>_source`, `<name>_ref`,
+    `<name>_order_no`) and every Webhook name, and is the marker value stamped
+    into `<name>_source`. `label` prefixes the Custom Fields' labels as a
+    person sees them on the form. `site_header` is the request header each
+    Webhook carries the caller's site id in.
+    """
+
+    name: str
+    label: str
+    site_header: str
+
+    def __post_init__(self) -> None:
+        if not _FIELDNAME.fullmatch(self.name):
+            raise ValueError(f"namespace name {self.name!r} is not a Frappe fieldname (lowercase, letters first)")
+        if not self.label.strip():
+            raise ValueError("namespace label is empty")
+        if not _HEADER.fullmatch(self.site_header):
+            raise ValueError(f"site header {self.site_header!r} is not an HTTP header name")
+
+    @property
+    def marker(self) -> str:
+        """The value stamped into `source_field` on every document written."""
+        return self.name
+
+    @property
+    def source_field(self) -> str:
+        return f"{self.name}_source"
+
+    @property
+    def ref_field(self) -> str:
+        return f"{self.name}_ref"
+
+    @property
+    def order_no_field(self) -> str:
+        return f"{self.name}_order_no"

{icedcoffee_sync-0.1.0.dev9 → icedcoffee_sync-0.1.0.dev13}/src/icedcoffee_sync/erpnext/purchase.py

@@ -12,6 +12,8 @@ import dataclasses
 from collections.abc import Iterator
 from typing import Any, Protocol
 
+from icedcoffee_sync.erpnext.namespace import Namespace
+
 DOCTYPE_PURCHASE_ORDER = "Purchase Order"
 DOCTYPE_PURCHASE_RECEIPT = "Purchase Receipt"
 DEFAULT_UOM = "Nos"
@@ -57,7 +59,13 @@ class PurchaseOrderItem:
 
 @dataclasses.dataclass(frozen=True)
 class PurchaseOrder:
-    """A Purchase Order as read from the site."""
+    """A Purchase Order as read from the site.
+
+    The `source_*` fields are the reader's namespace fields: `source_marker`
+    is the namespace's marker when the reader's integration wrote the order,
+    `source_ref` the order id it wrote it under, and `source_order_no` the
+    vendor's order number it carried.
+    """
 
     name: str
     supplier: str
@@ -73,9 +81,9 @@ class PurchaseOrder:
     order_confirmation_date: str | None
     amended_from: str | None
     modified: str
-    transpire_source: str | None
-    transpire_ref: str | None
-    transpire_order_no: str | None
+    source_marker: str | None
+    source_ref: str | None
+    source_order_no: str | None
     items: tuple[PurchaseOrderItem, ...]
 
     @property
@@ -87,8 +95,8 @@ class PurchaseOrder:
         return self.docstatus == 2
 
 
-def purchase_order_from_document(doc: dict[str, Any]) -> PurchaseOrder:
-    """Type a raw `Purchase Order` document. Pure."""
+def purchase_order_from_document(doc: dict[str, Any], namespace: Namespace) -> PurchaseOrder:
+    """Type a raw `Purchase Order` document, reading `namespace`'s fields. Pure."""
     items = tuple(
         PurchaseOrderItem(
             name=str(row.get("name", "")),
@@ -119,16 +127,16 @@ def purchase_order_from_document(doc: dict[str, Any]) -> PurchaseOrder:
         order_confirmation_date=_text(doc.get("order_confirmation_date")),
         amended_from=_text(doc.get("amended_from")),
         modified=str(doc.get("modified", "")),
-        transpire_source=_text(doc.get("transpire_source")),
-        transpire_ref=_text(doc.get("transpire_ref")),
-        transpire_order_no=_text(doc.get("transpire_order_no")),
+        source_marker=_text(doc.get(namespace.source_field)),
+        source_ref=_text(doc.get(namespace.ref_field)),
+        source_order_no=_text(doc.get(namespace.order_no_field)),
         items=items,
     )
 
 
-def read_purchase_order(client: _Getter, name: str) -> PurchaseOrder:
-    """Fetch and type one Purchase Order."""
-    return purchase_order_from_document(client.get(DOCTYPE_PURCHASE_ORDER, name))
+def read_purchase_order(client: _Getter, name: str, namespace: Namespace) -> PurchaseOrder:
+    """Fetch and type one Purchase Order, reading `namespace`'s fields."""
+    return purchase_order_from_document(client.get(DOCTYPE_PURCHASE_ORDER, name), namespace)
 
 
 def list_submitted_purchase_orders(

{icedcoffee_sync-0.1.0.dev9 → icedcoffee_sync-0.1.0.dev13}/src/icedcoffee_sync/erpnext/webhook.py

@@ -2,9 +2,9 @@
 
 A Webhook fires from `Document.run_method`, so a Purchase Order submitted from
 the desk, the REST API, or a script all ring the same bell. The body is a
-two-field template naming the document; phloem fetches the rest. The site id
-rides in a header so the gateway can tell which site's secret signs the
-request without a per-site route.
+two-field template naming the document; the receiver fetches the rest. The
+caller's site id rides in the namespace's site header, so one receiving URL can
+tell which site's secret signs the request without a per-site route.
 
 Field names are ERPNext v16's (`frappe/integrations/doctype/webhook/webhook.json`
 on version-16-hotfix). Frappe names a Webhook by prompt, so the caller sets
@@ -18,12 +18,12 @@ from collections.abc import Iterable
 from typing import Any, Protocol
 
 from icedcoffee_sync.erpnext.ensure import ensure_by_name
+from icedcoffee_sync.erpnext.namespace import Namespace
 
 DOCTYPE_WEBHOOK = "Webhook"
 PURCHASE_ORDER = "Purchase Order"
 PURCHASE_ORDER_EVENTS: tuple[str, ...] = ("on_submit", "on_update_after_submit", "on_cancel")
 
-SITE_HEADER = "X-Transpire-Site"
 TIMEOUT_SECONDS = 10
 
 # A doorbell, not the data. Frappe renders this Jinja against the document.
@@ -36,20 +36,21 @@ class _Writer(Protocol):
     def update(self, doctype: str, name: str, doc: dict[str, Any]) -> Any: ...
 
 
-def webhook_name(site_id: str, doctype: str, event: str) -> str:
-    """`transpire-<site>-<doctype slug>-<event>`; deterministic, so ensure is get-then-insert."""
+def webhook_name(namespace: Namespace, site_id: str, doctype: str, event: str) -> str:
+    """`<namespace>-<site>-<doctype slug>-<event>`; deterministic, so ensure is get-then-insert."""
     slug = doctype.lower().replace(" ", "-")
-    return f"transpire-{site_id}-{slug}-{event}"
+    return f"{namespace.name}-{site_id}-{slug}-{event}"
 
 
 @dataclasses.dataclass(frozen=True)
 class DesiredWebhook:
-    """One Webhook document as Transpire wants it on the site."""
+    """One Webhook document as the integration wants it on the site."""
 
     name: str
     doctype: str
     event: str
     request_url: str
+    site_header: str
     site_id: str
     secret: str = dataclasses.field(repr=False)
     # None means "do not touch the switch": a Webhook this creates starts off
@@ -70,7 +71,7 @@ class DesiredWebhook:
             "webhook_json": DOORBELL_TEMPLATE,
             "webhook_headers": [
                 {"key": "Content-Type", "value": "application/json"},
-                {"key": SITE_HEADER, "value": self.site_id},
+                {"key": self.site_header, "value": self.site_id},
             ],
             "enable_security": 1,
             "webhook_secret": self.secret,
@@ -80,9 +81,9 @@ class DesiredWebhook:
 
 
 def purchase_order_webhooks(
-    *, site_id: str, request_url: str, secret: str, enabled: bool | None = None
+    *, namespace: Namespace, site_id: str, request_url: str, secret: str, enabled: bool | None = None
 ) -> tuple[DesiredWebhook, ...]:
-    """The three Purchase Order Webhooks the connector listens to.
+    """The three Purchase Order Webhooks a receiver listens to, named and headed for `namespace`.
 
     `enabled` left None creates them off and leaves existing ones as they are;
     re-running provisioning with it True, once the inbound route and its topic
@@ -90,10 +91,11 @@ def purchase_order_webhooks(
     """
     return tuple(
         DesiredWebhook(
-            name=webhook_name(site_id, PURCHASE_ORDER, event),
+            name=webhook_name(namespace, site_id, PURCHASE_ORDER, event),
             doctype=PURCHASE_ORDER,
             event=event,
             request_url=request_url,
+            site_header=namespace.site_header,
             site_id=site_id,
             secret=secret,
             enabled=enabled,
@@ -113,13 +115,13 @@ class WebhookReport:
 def ensure_webhooks(client: _Writer, webhooks: Iterable[DesiredWebhook]) -> WebhookReport:
     """Create every Webhook the site lacks; re-assert the machine-owned fields on the rest.
 
-    A Transpire Webhook is ours by name, so an existing one is brought back to
-    the desired document -- URL, headers, template, secret, timeout -- rather
-    than left alone. That is what lets a re-run apply a changed gateway URL or
-    a re-derived secret after the master secret rotates; the secret is a
-    Password field Frappe never reads back, so it is always written. The
-    `enabled` switch is re-asserted only when the desired document says which
-    way (see `DesiredWebhook.enabled`).
+    A Webhook named under the caller's namespace is the caller's, so an
+    existing one is brought back to the desired document -- URL, headers,
+    template, secret, timeout -- rather than left alone. That is what lets a
+    re-run apply a changed receiver URL or a re-derived secret after the master
+    secret rotates; the secret is a Password field Frappe never reads back, so
+    it is always written. The `enabled` switch is re-asserted only when the
+    desired document says which way (see `DesiredWebhook.enabled`).
 
     Returns:
         The names created and the names updated, each in input order.

{icedcoffee_sync-0.1.0.dev9 → icedcoffee_sync-0.1.0.dev13}/tests/fixtures/README.md

@@ -245,7 +245,9 @@ detection.
 Captured 2026-09-03 by a one-off script against `example-demo-sites.invalid`
 (Acmebike's demo ERPNext site): `GET /api/v2/document/Purchase Order/<name>` for
 the Purchase Order carrying `transpire_order_no` `0001ABCD`, written raw and
-unstripped, as `read_purchase_order` needs to parse the real shape.
+unstripped, as `read_purchase_order` needs to parse the real shape. The order
+was written under the namespace `transpire`, so its `transpire_*` fields are
+what a reader in that namespace sees and a reader in any other sees as absent.
 
 Two fields were edited by hand after capture: **`docstatus`** (`0` → `1`) and
 **`status`** (`"Draft"` → `"To Receive and Bill"`). The captured PO is still a

{icedcoffee_sync-0.1.0.dev9 → icedcoffee_sync-0.1.0.dev13}/tests/test_erpnext_comment.py

@@ -21,7 +21,9 @@ class Recorder:
 
 def test_add_comment_goes_through_add_comment_not_a_raw_insert() -> None:
     site = Recorder()
-    out = add_comment(site, "Purchase Order", "PUR-ORD-1", "Tracking 1Z999 via UPS")
+    out = add_comment(
+        site, "Purchase Order", "PUR-ORD-1", "Tracking 1Z999 via UPS", email="sync@acme.example", by="Acme"
+    )
     assert out["name"] == "cmt-1"
     path, params = site.calls[0]
     assert path == "frappe.desk.form.utils.add_comment"
@@ -29,8 +31,8 @@ def test_add_comment_goes_through_add_comment_not_a_raw_insert() -> None:
         "reference_doctype": "Purchase Order",
         "reference_name": "PUR-ORD-1",
         "content": "Tracking 1Z999 via UPS",
-        "comment_email": "integration@example.com",
-        "comment_by": "Transpire",
+        "comment_email": "sync@acme.example",
+        "comment_by": "Acme",
     }
 
 

icedcoffee_sync-0.1.0.dev13/tests/test_erpnext_documents.py

@@ -0,0 +1,68 @@
+"""The ERPNext document shapes an integration writes, under the caller's namespace."""
+
+from icedcoffee_sync.erpnext import documents as d
+from icedcoffee_sync.erpnext.namespace import Namespace
+
+ACME = Namespace(name="acme", label="Acme", site_header="X-Acme-Site")
+
+
+def test_custom_field_is_named_the_way_frappe_names_it() -> None:
+    field = d.DesiredCustomField(dt="Supplier", fieldname="acme_ref", label="Acme Ref", insert_after="supplier_name")
+    assert field.document_name == "Supplier-acme_ref"
+    doc = field.as_document()
+    assert doc["dt"] == "Supplier" and doc["fieldname"] == "acme_ref"
+    assert doc["read_only"] == 1 and doc["no_copy"] == 1
+    assert "unique" not in doc
+
+
+def test_every_pushed_document_carries_the_source_marker() -> None:
+    supplier = d.DesiredSupplier(vendor_id="v1", supplier_name="Shimano")
+    item = d.DesiredItem(item_code="CN-1", item_name="CHAIN", description="CHAIN")
+    line = d.DesiredPurchaseOrderItem(item_code="CN-1", qty=2, schedule_date="2026-04-17")
+    order = d.DesiredPurchaseOrder(
+        order_id="o1",
+        vendor_id="v1",
+        order_number="12672682",
+        transaction_date="2026-04-17",
+        schedule_date="2026-04-17",
+        items=(line,),
+    )
+    for doc in (
+        supplier.as_document(namespace=ACME),
+        item.as_document(namespace=ACME),
+        order.as_document("Shimano", namespace=ACME),
+    ):
+        assert doc["acme_source"] == "acme"
+    assert supplier.as_document(namespace=ACME)["acme_ref"] == "v1"
+    assert order.as_document("Shimano", namespace=ACME)["acme_ref"] == "o1"
+    assert order.as_document("Shimano", namespace=ACME)["acme_order_no"] == "12672682"
+
+
+def test_the_custom_fields_are_named_and_labelled_for_the_namespace() -> None:
+    fields = d.custom_fields(ACME)
+    assert [(f.dt, f.fieldname, f.label) for f in fields] == [
+        ("Supplier", "acme_source", "Acme Source"),
+        ("Supplier", "acme_ref", "Acme Vendor ID"),
+        ("Item", "acme_source", "Acme Source"),
+        ("Purchase Order", "acme_source", "Acme Source"),
+        ("Purchase Order", "acme_ref", "Acme Order ID"),
+        ("Purchase Order", "acme_order_no", "Vendor Order Number"),
+    ]
+    # Each field the documents write into is one the site is given.
+    written = {
+        *d.DesiredSupplier(vendor_id="v1", supplier_name="Shimano").as_document(namespace=ACME),
+    } - {"supplier_name", "disabled"}
+    assert written <= {f.fieldname for f in fields if f.dt == "Supplier"}
+
+
+def test_supplier_ref_field_is_one_of_the_custom_fields() -> None:
+    assert d.supplier_ref_field(ACME) in d.custom_fields(ACME)
+    assert d.supplier_ref_field(ACME).document_name == "Supplier-acme_ref"
+
+
+def test_an_item_is_stock_maintained() -> None:
+    # These are bicycle parts a shop holds in inventory, not services. ERPNext
+    # writes no stock ledger entry for an item with Maintain Stock off, so a
+    # Purchase Receipt against one moves nothing.
+    item = d.DesiredItem(item_code="CN-1", item_name="CHAIN", description="CHAIN")
+    assert item.as_document(namespace=ACME)["is_stock_item"] == 1

icedcoffee_sync-0.1.0.dev13/tests/test_erpnext_namespace.py

@@ -0,0 +1,28 @@
+"""The caller's namespace: every name an integration leaves on a site."""
+
+import pytest
+
+from icedcoffee_sync.erpnext.namespace import Namespace
+
+
+def test_the_field_names_and_marker_come_from_the_name() -> None:
+    ns = Namespace(name="acme", label="Acme", site_header="X-Acme-Site")
+    assert ns.marker == "acme"
+    assert (ns.source_field, ns.ref_field, ns.order_no_field) == ("acme_source", "acme_ref", "acme_order_no")
+
+
+@pytest.mark.parametrize("name", ["", "Acme", "1acme", "acme-sync", "acme sync", "_acme"])
+def test_a_name_that_is_not_a_frappe_fieldname_is_refused(name: str) -> None:
+    with pytest.raises(ValueError, match="not a Frappe fieldname"):
+        Namespace(name=name, label="Acme", site_header="X-Acme-Site")
+
+
+def test_an_empty_label_is_refused() -> None:
+    with pytest.raises(ValueError, match="label is empty"):
+        Namespace(name="acme", label="  ", site_header="X-Acme-Site")
+
+
+@pytest.mark.parametrize("header", ["", "X Acme Site", "X-Acme-Site:", "-X-Acme", "X_Acme"])
+def test_a_site_header_that_is_not_a_header_name_is_refused(header: str) -> None:
+    with pytest.raises(ValueError, match="not an HTTP header name"):
+        Namespace(name="acme", label="Acme", site_header=header)

{icedcoffee_sync-0.1.0.dev9 → icedcoffee_sync-0.1.0.dev13}/tests/test_erpnext_purchase.py

@@ -6,8 +6,11 @@ from collections.abc import Sequence
 from typing import Any
 
 from icedcoffee_sync.erpnext import purchase as p
+from icedcoffee_sync.erpnext.namespace import Namespace
 
 FIXTURE = pathlib.Path(__file__).parent / "fixtures" / "purchase_order_submitted.json"
+# The namespace the fixture's order was written under (see fixtures/README.md).
+WRITER = Namespace(name="transpire", label="Transpire", site_header="X-Transpire-Site")
 
 
 def _doc() -> dict[str, Any]:
@@ -15,21 +18,28 @@ def _doc() -> dict[str, Any]:
 
 
 def test_a_submitted_purchase_order_reads_into_a_typed_record() -> None:
-    po = p.purchase_order_from_document(_doc())
+    po = p.purchase_order_from_document(_doc(), WRITER)
     assert po.name.startswith("PUR-ORD-")
     assert po.supplier == "SUP"
     assert po.company == "Acmebike Cycles" and po.currency == "USD"
     assert po.docstatus == 1 and po.is_submitted and not po.is_cancelled
-    assert po.transpire_source == "transpire" and po.transpire_order_no == "0001ABCD"
+    assert po.source_marker == "transpire" and po.source_order_no == "0001ABCD"
+    assert po.source_ref == "ord_0123456789abcdef"
     assert po.order_confirmation_no is None
     assert po.amended_from is None
     assert po.items and po.items[0].item_code == "IT0001" and po.items[0].qty == 1.0 and po.items[0].uom == "Nos"
 
 
+def test_another_namespace_reads_none_of_the_writers_fields() -> None:
+    other = Namespace(name="acme", label="Acme", site_header="X-Acme-Site")
+    po = p.purchase_order_from_document(_doc(), other)
+    assert (po.source_marker, po.source_ref, po.source_order_no) == (None, None, None)
+
+
 def test_empty_strings_read_as_none() -> None:
     doc = _doc()
     doc["order_confirmation_no"] = ""
-    assert p.purchase_order_from_document(doc).order_confirmation_no is None
+    assert p.purchase_order_from_document(doc, WRITER).order_confirmation_no is None
 
 
 def test_set_order_confirmation_updates_exactly_two_fields() -> None:

{icedcoffee_sync-0.1.0.dev9 → icedcoffee_sync-0.1.0.dev13}/tests/test_erpnext_webhook.py

@@ -1,23 +1,30 @@
-"""The Frappe Webhook documents that ring phloem's doorbell."""
+"""The Frappe Webhook documents that ring a receiver's doorbell."""
 
 import json
 
 from icedcoffee_sync.erpnext import webhook as w
+from icedcoffee_sync.erpnext.namespace import Namespace
+
+ACME = Namespace(name="acme", label="Acme", site_header="X-Acme-Site")
 
 SECRET = "7dc9c9544e17e1867efde0506bca3dacaaa5d11f661560591bc1acf0924e8c86"
 
 
 def test_three_purchase_order_webhooks_named_deterministically() -> None:
-    hooks = w.purchase_order_webhooks(site_id="site-1", request_url="https://gw.example/frappe", secret=SECRET)
+    hooks = w.purchase_order_webhooks(
+        namespace=ACME, site_id="site-1", request_url="https://gw.example/frappe", secret=SECRET
+    )
     assert [h.name for h in hooks] == [
-        "transpire-site-1-purchase-order-on_submit",
-        "transpire-site-1-purchase-order-on_update_after_submit",
-        "transpire-site-1-purchase-order-on_cancel",
+        "acme-site-1-purchase-order-on_submit",
+        "acme-site-1-purchase-order-on_update_after_submit",
+        "acme-site-1-purchase-order-on_cancel",
     ]
 
 
 def test_the_document_uses_the_v16_field_names_and_a_two_field_json_template() -> None:
-    hook = w.purchase_order_webhooks(site_id="site-1", request_url="https://gw.example/frappe", secret=SECRET)[0]
+    hook = w.purchase_order_webhooks(
+        namespace=ACME, site_id="site-1", request_url="https://gw.example/frappe", secret=SECRET
+    )[0]
     doc = hook.as_document()
     assert doc["name"] == hook.name
     assert doc["webhook_doctype"] == "Purchase Order"
@@ -29,12 +36,12 @@ def test_the_document_uses_the_v16_field_names_and_a_two_field_json_template() -
     # Disabled by default: deliveries start only once the inbound route exists.
     assert doc["enabled"] == 0 and doc["timeout"] == 10
     live = w.purchase_order_webhooks(
-        site_id="site-1", request_url="https://gw.example/frappe", secret=SECRET, enabled=True
+        namespace=ACME, site_id="site-1", request_url="https://gw.example/frappe", secret=SECRET, enabled=True
     )
     assert live[0].as_document()["enabled"] == 1
     assert {h["key"]: h["value"] for h in doc["webhook_headers"]} == {
         "Content-Type": "application/json",
-        "X-Transpire-Site": "site-1",
+        "X-Acme-Site": "site-1",
     }
     # The template is a doorbell: the document's identity and nothing else.
     rendered = doc["webhook_json"].replace("{{ doc.doctype }}", "Purchase Order").replace("{{ doc.name }}", "PUR-ORD-1")
@@ -42,7 +49,9 @@ def test_the_document_uses_the_v16_field_names_and_a_two_field_json_template() -
 
 
 def test_the_secret_never_appears_in_the_repr() -> None:
-    hook = w.purchase_order_webhooks(site_id="site-1", request_url="https://gw.example/frappe", secret=SECRET)[0]
+    hook = w.purchase_order_webhooks(
+        namespace=ACME, site_id="site-1", request_url="https://gw.example/frappe", secret=SECRET
+    )[0]
     assert SECRET not in repr(hook)
 
 
@@ -51,7 +60,7 @@ def test_ensure_creates_the_missing_ones_and_reasserts_the_rest() -> None:
 
     class Site:
         def __init__(self) -> None:
-            self.have = {"transpire-site-1-purchase-order-on_submit"}
+            self.have = {"acme-site-1-purchase-order-on_submit"}
             self.inserted: list[str] = []
             self.updated: list[tuple[str, dict]] = []
 
@@ -70,13 +79,15 @@ def test_ensure_creates_the_missing_ones_and_reasserts_the_rest() -> None:
             return {"name": name, **doc}
 
     site = Site()
-    hooks = w.purchase_order_webhooks(site_id="site-1", request_url="https://gw.example/frappe", secret=SECRET)
+    hooks = w.purchase_order_webhooks(
+        namespace=ACME, site_id="site-1", request_url="https://gw.example/frappe", secret=SECRET
+    )
     first = w.ensure_webhooks(site, hooks)
     assert first.created == [
-        "transpire-site-1-purchase-order-on_update_after_submit",
-        "transpire-site-1-purchase-order-on_cancel",
+        "acme-site-1-purchase-order-on_update_after_submit",
+        "acme-site-1-purchase-order-on_cancel",
     ]
-    assert first.updated == ["transpire-site-1-purchase-order-on_submit"]
+    assert first.updated == ["acme-site-1-purchase-order-on_submit"]
     # The existing one was brought back to the desired document, secret included,
     # and its name was not sent as a field to change.
     _name, doc = site.updated[0]
@@ -85,7 +96,9 @@ def test_ensure_creates_the_missing_ones_and_reasserts_the_rest() -> None:
     # Nothing said which way the switch should go, so the existing Webhook keeps its own.
     assert "enabled" not in doc
 
-    rotated = w.purchase_order_webhooks(site_id="site-1", request_url="https://gw2.example/frappe", secret="y" * 64)
+    rotated = w.purchase_order_webhooks(
+        namespace=ACME, site_id="site-1", request_url="https://gw2.example/frappe", secret="y" * 64
+    )
     second = w.ensure_webhooks(site, rotated)
     assert second.created == [] and len(second.updated) == 3
     assert all(doc["request_url"] == "https://gw2.example/frappe" for _, doc in site.updated[1:])
@@ -96,7 +109,11 @@ def test_ensure_creates_the_missing_ones_and_reasserts_the_rest() -> None:
         w.ensure_webhooks(
             site,
             w.purchase_order_webhooks(
-                site_id="site-1", request_url="https://gw2.example/frappe", secret=SECRET, enabled=enabled
+                namespace=ACME,
+                site_id="site-1",
+                request_url="https://gw2.example/frappe",
+                secret=SECRET,
+                enabled=enabled,
             ),
         )
         assert {doc["enabled"] for _, doc in site.updated} == {expected}

{icedcoffee_sync-0.1.0.dev9 → icedcoffee_sync-0.1.0.dev13}/tests/test_live_frappe.py

@@ -236,9 +236,13 @@ def test_upload_file_attaches_a_private_file_to_a_document(client: Client) -> No
 
 def test_a_webhook_provisions_idempotently_and_is_deletable(client: Client) -> None:
     from icedcoffee_sync.erpnext import webhook as w
+    from icedcoffee_sync.erpnext.namespace import Namespace
 
+    ns = Namespace(name="icedcoffee_live", label="icedcoffee live", site_header="X-Icedcoffee-Live-Site")
     site_id = f"live-{uuid.uuid4().hex[:8]}"
-    hooks = w.purchase_order_webhooks(site_id=site_id, request_url="https://example.invalid/frappe", secret="x" * 64)
+    hooks = w.purchase_order_webhooks(
+        namespace=ns, site_id=site_id, request_url="https://example.invalid/frappe", secret="x" * 64
+    )
     try:
         first = w.ensure_webhooks(client, hooks)
         assert first.created == [h.name for h in hooks]
@@ -246,7 +250,7 @@ def test_a_webhook_provisions_idempotently_and_is_deletable(client: Client) -> N
         assert second.created == [] and second.updated == [h.name for h in hooks]
         got = client.get(w.DOCTYPE_WEBHOOK, hooks[0].name)
         assert got["webhook_docevent"] == "on_submit"
-        assert {h["key"] for h in got["webhook_headers"]} == {"Content-Type", w.SITE_HEADER}
+        assert {h["key"] for h in got["webhook_headers"]} == {"Content-Type", ns.site_header}
     finally:
         for hook in hooks:
             with contextlib.suppress(DoesNotExistError):
@@ -255,11 +259,13 @@ def test_a_webhook_provisions_idempotently_and_is_deletable(client: Client) -> N
 
 def test_submitted_purchase_orders_list_and_read(client: Client) -> None:
     from icedcoffee_sync.erpnext import purchase as p
+    from icedcoffee_sync.erpnext.namespace import Namespace
 
+    ns = Namespace(name="icedcoffee_live", label="icedcoffee live", site_header="X-Icedcoffee-Live-Site")
     rows = list(p.list_submitted_purchase_orders(client, modified_after=None, page_size=5))
     if not rows:
         pytest.skip("test site holds no submitted Purchase Orders")
-    po = p.read_purchase_order(client, rows[0]["name"])
+    po = p.read_purchase_order(client, rows[0]["name"], ns)
     # The listing deliberately includes cancelled documents, so the first row
     # may be either; what matters is that a finalized document reads with lines.
     assert (po.is_submitted or po.is_cancelled) and po.items
@@ -270,6 +276,6 @@ def test_a_comment_lands_on_the_document_and_lists_back(note: tuple[Client, str,
 
     client, name, _title = note
     text = f"icedcoffee-sync live comment {uuid.uuid4()}"
-    created = add_comment(client, "Note", name, text)
+    created = add_comment(client, "Note", name, text, email="integration@example.com", by="icedcoffee-sync")
     assert created["reference_name"] == name
     assert any(c["content"] == text for c in list_comments(client, "Note", name))

icedcoffee_sync-0.1.0.dev9/tests/test_erpnext_documents.py

@@ -1,42 +0,0 @@
-"""The ERPNext document shapes shared by graft and phloem."""
-
-from icedcoffee_sync.erpnext import documents as d
-
-
-def test_custom_field_is_named_the_way_frappe_names_it() -> None:
-    field = d.DesiredCustomField(
-        dt="Supplier", fieldname="transpire_ref", label="Transpire Ref", insert_after="supplier_name"
-    )
-    assert field.document_name == "Supplier-transpire_ref"
-    doc = field.as_document()
-    assert doc["dt"] == "Supplier" and doc["fieldname"] == "transpire_ref"
-    assert doc["read_only"] == 1 and doc["no_copy"] == 1
-    assert "unique" not in doc
-
-
-def test_every_pushed_document_carries_the_source_marker() -> None:
-    supplier = d.DesiredSupplier(vendor_id="v1", supplier_name="Shimano")
-    item = d.DesiredItem(item_code="CN-1", item_name="CHAIN", description="CHAIN")
-    line = d.DesiredPurchaseOrderItem(item_code="CN-1", qty=2, schedule_date="2026-04-17")
-    order = d.DesiredPurchaseOrder(
-        order_id="o1",
-        vendor_id="v1",
-        order_number="12672682",
-        transaction_date="2026-04-17",
-        schedule_date="2026-04-17",
-        items=(line,),
-    )
-    for doc in (supplier.as_document(), item.as_document(), order.as_document("Shimano")):
-        assert doc[d.FIELD_SOURCE] == d.SOURCE_MARKER
-
-
-def test_supplier_ref_field_is_the_one_graft_creates() -> None:
-    assert d.SUPPLIER_REF_FIELD in d.CUSTOM_FIELDS
-    assert d.SUPPLIER_REF_FIELD.document_name == "Supplier-transpire_ref"
-
-
-def test_an_item_is_stock_maintained() -> None:
-    # These are bicycle parts a shop holds in inventory, not services. ERPNext
-    # writes no stock ledger entry for an item with Maintain Stock off, so a
-    # Purchase Receipt against one moves nothing.
-    assert d.DesiredItem(item_code="CN-1", item_name="CHAIN", description="CHAIN").as_document()["is_stock_item"] == 1