lr-gladiator 0.4.0__py3-none-any.whl → 0.14.0__py3-none-any.whl

gladiator/arena.py

@@ -6,25 +6,31 @@ import subprocess
 import shlex
 import os
 from pathlib import Path
-from typing import Dict, List, Optional, Tuple
+from typing import Dict, List, Optional, Tuple, FrozenSet
 import requests
 from .config import LoginConfig
+from .checksums import sha256_file
+import hashlib
+
 
 class ArenaError(RuntimeError):
     pass
 
+
 class ArenaClient:
     def __init__(self, cfg: LoginConfig):
         self.cfg = cfg
         self.session = requests.Session()
         self.session.verify = cfg.verify_tls
         # Default headers: explicitly request/submit JSON
-        self.session.headers.update({
-            "Accept": "application/json",
-            "Content-Type": "application/json",
-            "User-Agent": "gladiator-arena/0.1",
-            "Arena-Usage-Reason": cfg.reason or "gladiator/cli",
-        })
+        self.session.headers.update(
+            {
+                "Accept": "application/json",
+                "Content-Type": "application/json",
+                "User-Agent": "gladiator-arena/0.1",
+                "Arena-Usage-Reason": cfg.reason or "gladiator/cli",
+            }
+        )
         if cfg.arena_session_id:
             self.session.headers.update({"arena_session_id": cfg.arena_session_id})
 
@@ -87,7 +93,15 @@ class ArenaClient:
     def _timestamp_of(f: Dict):
         from datetime import datetime
         from email.utils import parsedate_to_datetime
-        for k in ("modifiedAt", "updatedAt", "lastModified", "lastModifiedDate", "effectiveDate", "createdAt"):
+
+        for k in (
+            "modifiedAt",
+            "updatedAt",
+            "lastModified",
+            "lastModifiedDate",
+            "effectiveDate",
+            "createdAt",
+        ):
             s = f.get(k)
             if not s:
                 continue
@@ -125,29 +139,139 @@ class ArenaClient:
     def get_latest_approved_revision(self, item_number: str) -> str:
         return self._api_get_latest_approved(item_number)
 
-
-    def list_files(self, item_number: str, revision: Optional[str] = None) -> List[Dict]:
-        target_guid = self._api_resolve_revision_guid(item_number, revision or "EFFECTIVE")
+    def list_files(
+        self, item_number: str, revision: Optional[str] = None
+    ) -> List[Dict]:
+        target_guid = self._api_resolve_revision_guid(
+            item_number, revision or "EFFECTIVE"
+        )
         raw = self._api_list_files_by_item_guid(target_guid)
         return self._latest_files(raw)
-    
 
-    def download_files(self, item_number: str, revision: Optional[str] = None, out_dir: Path = Path(".")) -> List[Path]:
+    def download_files(
+        self,
+        item_number: str,
+        revision: Optional[str] = None,
+        out_dir: Path = Path("."),
+    ) -> List[Path]:
         files = self.list_files(item_number, revision)
         out_dir.mkdir(parents=True, exist_ok=True)
         downloaded: List[Path] = []
         for f in files:
+            # Skip associations with no blob
+            if not f.get("haveContent", True):
+                self._log(
+                    f"Skip {item_number}: file {f.get('filename')} has no content"
+                )
+                continue
+
             url = f.get("downloadUrl") or f.get("url")
             filename = f.get("filename") or f.get("name")
             if not url or not filename:
                 continue
+
             p = out_dir / filename
-            with self.session.get(url, stream=True, headers={"arena_session_id": self.cfg.arena_session_id or ""}) as r:
-                r.raise_for_status()
-                with open(p, "wb") as fh:
-                    for chunk in r.iter_content(128 * 1024):
-                        fh.write(chunk)
-            downloaded.append(p)
+            try:
+                with self.session.get(
+                    url,
+                    stream=True,
+                    headers={"arena_session_id": self.cfg.arena_session_id or ""},
+                ) as r:
+                    # If the blob is missing/forbidden, don’t abort the whole command
+                    if r.status_code in (400, 403, 404):
+                        self._log(
+                            f"Skip {item_number}: {filename} content unavailable "
+                            f"(HTTP {r.status_code})"
+                        )
+                        continue
+                    r.raise_for_status()
+                    with open(p, "wb") as fh:
+                        for chunk in r.iter_content(128 * 1024):
+                            fh.write(chunk)
+                downloaded.append(p)
+            except requests.HTTPError as e:
+                # Be resilient: log and continue
+                self._log(f"Download failed for {filename}: {e}")
+                continue
+        return downloaded
+
+    def download_files_recursive(
+        self,
+        item_number: str,
+        revision: Optional[str] = None,
+        out_dir: Path = Path("."),
+        *,
+        max_depth: Optional[int] = None,
+    ) -> List[Path]:
+        """
+        Download files for `item_number` AND, recursively, for all subassemblies
+        discovered via the BOM. Each child item is placed under a subdirectory:
+            <out_dir>/<child_item_number>/
+        Root files go directly in <out_dir>/.
+
+        Depth semantics match `get_bom(..., recursive=True, max_depth=...)`.
+        """
+        # Ensure the root directory exists
+        out_dir.mkdir(parents=True, exist_ok=True)
+
+        downloaded: List[Path] = []
+        bom_cache: Dict[str, List[Dict]] = {}
+
+        def fetch_children(item: str) -> List[Dict]:
+            if item not in bom_cache:
+                bom_cache[item] = self.get_bom(
+                    item,
+                    revision,
+                    recursive=False,
+                    max_depth=None,
+                )
+            return bom_cache[item]
+
+        def walk(
+            current_item: str,
+            dest: Path,
+            depth: int,
+            ancestors: FrozenSet[str],
+        ) -> None:
+            if current_item in ancestors:
+                self._log(
+                    "Detected BOM cycle involving "
+                    f"{current_item} (ancestors: {', '.join(sorted(ancestors))})"
+                )
+                return
+
+            next_ancestors = ancestors | {current_item}
+
+            dest.mkdir(parents=True, exist_ok=True)
+            downloaded.extend(self.download_files(current_item, revision, out_dir=dest))
+
+            if max_depth is not None and depth >= max_depth:
+                return
+
+            children = fetch_children(current_item)
+            seen_children: set[str] = set()
+            for child in children:
+                if not child:
+                    continue
+                child_num = child.get("itemNumber")
+                if not child_num:
+                    continue
+                if child_num == current_item:
+                    continue
+                if child_num in seen_children:
+                    continue
+                if child_num in next_ancestors:
+                    self._log(
+                        "Detected BOM cycle involving "
+                        f"{child_num} (ancestors: {', '.join(sorted(next_ancestors))})"
+                    )
+                    continue
+                seen_children.add(child_num)
+
+                child_dir = dest / child_num
+                walk(child_num, child_dir, depth + 1, next_ancestors)
+
+        walk(item_number, out_dir, depth=0, ancestors=frozenset())
         return downloaded
 
     def upload_file_to_working(
@@ -162,13 +286,13 @@ class ArenaClient:
         description: Optional[str] = None,
         primary: bool = True,
         latest_edition_association: bool = True,
-        edition: str = "1",
+        edition: str = None,
     ) -> Dict:
         """
-        Update-if-exists-else-create semantics, matching the bash script:
+        Update-if-exists-else-create semantics:
           1) Resolve EFFECTIVE GUID from item number
           2) Resolve WORKING revision GUID (fail if none)
-          3) Find existing file by exact filename (WORKING first, then EFFECTIVE)
+          3) Find existing file by title orexact filename (WORKING first, then EFFECTIVE)
              - If found: POST /files/{fileGuid}/content (multipart)
              - Else:     POST /items/{workingGuid}/files (multipart) with file.edition
         """
@@ -185,7 +309,139 @@ class ArenaClient:
             edition=edition,
         )
 
-    # ---------- API-mode (HTTP) ----------
+    def get_bom(
+        self,
+        item_number: str,
+        revision: Optional[str] = None,
+        *,
+        recursive: bool = False,
+        max_depth: Optional[int] = None,
+    ) -> List[Dict]:
+        """
+        Return a normalized list of BOM lines for the given item.
+
+        By default this fetches the EFFECTIVE (approved) revision's BOM.
+        Use revision="WORKING" or a specific label (e.g., "B2") to override.
+
+        If recursive=True, expand subassemblies depth-first. max_depth limits the recursion
+        depth (1 = only direct children). If omitted, recursion is unlimited.
+        """
+        selector = (revision or "EFFECTIVE").strip()
+        out: List[Dict] = []
+        self._bom_expand(
+            root_item=item_number,
+            selector=selector,
+            out=out,
+            recursive=recursive,
+            max_depth=max_depth,
+            _level=0,
+            _seen=set(),
+        )
+        return out
+
+    # === Internal: single fetch + normalization (your original logic) ===
+
+    def _fetch_bom_normalized(self, item_number: str, selector: str) -> List[Dict]:
+        """
+        Fetch and normalize the BOM for item_number with the given revision selector.
+        Falls back WORKING -> EFFECTIVE if selector is WORKING and no WORKING exists.
+        """
+        # 1) Resolve the exact revision GUID we want the BOM for
+        try:
+            target_guid = self._api_resolve_revision_guid(item_number, selector)
+        except ArenaError:
+            if selector.strip().upper() == "WORKING":
+                # fallback: try EFFECTIVE for children that don't have a WORKING revision
+                target_guid = self._api_resolve_revision_guid(item_number, "EFFECTIVE")
+            else:
+                raise
+
+        # 2) GET /items/{guid}/bom
+        url = f"{self._api_base()}/items/{target_guid}/bom"
+        self._log(f"GET {url}")
+        r = self.session.get(url)
+        r.raise_for_status()
+        data = self._ensure_json(r)
+
+        rows = data.get("results", data if isinstance(data, list) else [])
+        norm: List[Dict] = []
+        for row in rows:
+            itm = row.get("item", {}) if isinstance(row, dict) else {}
+            norm.append(
+                {
+                    # association/line
+                    "guid": row.get("guid"),
+                    "lineNumber": row.get("lineNumber"),
+                    "notes": row.get("notes"),
+                    "quantity": row.get("quantity"),
+                    "refDes": row.get("refDes")
+                    or row.get("referenceDesignators")
+                    or "",
+                    # child item
+                    "itemGuid": itm.get("guid") or itm.get("id"),
+                    "itemNumber": itm.get("number"),
+                    "itemName": itm.get("name"),
+                    "itemRevision": itm.get("revisionNumber"),
+                    "itemRevisionStatus": itm.get("revisionStatus"),
+                    "itemUrl": (itm.get("url") or {}).get("api"),
+                    "itemAppUrl": (itm.get("url") or {}).get("app"),
+                }
+            )
+        return norm
+
+    # === Internal: recursive expansion ===
+
+    def _bom_expand(
+        self,
+        *,
+        root_item: str,
+        selector: str,
+        out: List[Dict],
+        recursive: bool,
+        max_depth: Optional[int],
+        _level: int,
+        _seen: set,
+    ) -> None:
+        # avoid cycles
+        if root_item in _seen:
+            return
+        _seen.add(root_item)
+
+        rows = self._fetch_bom_normalized(root_item, selector)
+
+        # attach level and parentNumber (useful in JSON + for debugging)
+        for r in rows:
+            r["level"] = _level
+            r["parentNumber"] = root_item
+            out.append(r)
+
+        if not recursive:
+            return
+
+        # depth check: if max_depth=1, only expand children once (level 0 -> level 1)
+        if max_depth is not None and _level >= max_depth:
+            return
+
+        # expand each child that looks like an assembly (if it has a BOM; empty BOM is okay)
+        for r in rows:
+            child_num = r.get("itemNumber")
+            if not child_num:
+                continue
+            try:
+                # Recurse; keep same selector, with WORKING->EFFECTIVE fallback handled in _fetch_bom_normalized
+                self._bom_expand(
+                    root_item=child_num,
+                    selector=selector,
+                    out=out,
+                    recursive=True,
+                    max_depth=max_depth,
+                    _level=_level + 1,
+                    _seen=_seen,
+                )
+            except ArenaError:
+                # Child might not have a BOM; skip silently
+                continue
+
     def _api_base(self) -> str:
         return self.cfg.base_url.rstrip("/")
 
@@ -206,26 +462,35 @@ class ArenaClient:
         #   - revisionStatus == "EFFECTIVE"   (string)
         #   - OR status == 1                  (numeric)
         effective = [
-            rv for rv in revs
-            if (str(rv.get("revisionStatus") or "").upper() == "EFFECTIVE") or (rv.get("status") == 1)
+            rv
+            for rv in revs
+            if (str(rv.get("revisionStatus") or "").upper() == "EFFECTIVE")
+            or (rv.get("status") == 1)
         ]
         if not effective:
             raise ArenaError(f"No approved/released revisions for item {item_number}")
 
         # Prefer the one that is not superseded; otherwise fall back to the most recently superseded.
-        current = next((rv for rv in effective if not rv.get("supersededDateTime")), None)
+        current = next(
+            (rv for rv in effective if not rv.get("supersededDateTime")), None
+        )
         if not current:
             # sort by supersededDateTime (None last) then by number/name as a stable tie-breaker
             def _sd(rv):
                 dt = rv.get("supersededDateTime")
                 return dt or "0000-00-00T00:00:00Z"
+
             effective.sort(key=_sd)
             current = effective[-1]
 
         # The human-visible revision is under "number" (e.g., "B3"); fall back defensively.
-        rev_label = current.get("number") or current.get("name") or current.get("revision")
+        rev_label = (
+            current.get("number") or current.get("name") or current.get("revision")
+        )
         if not rev_label:
-            raise ArenaError(f"Could not determine revision label for item {item_number}")
+            raise ArenaError(
+                f"Could not determine revision label for item {item_number}"
+            )
         return rev_label
 
     def _api_list_files(self, item_number: str) -> List[Dict]:
@@ -240,19 +505,27 @@ class ArenaClient:
         for row in rows:
             f = row.get("file", {}) if isinstance(row, dict) else {}
             file_guid = f.get("guid") or f.get("id")
-            norm.append({
-                "id": row.get("guid") or row.get("id"),         # association id
-                "fileGuid": file_guid,                           # actual file id
-                "name": f.get("name") or f.get("title"),
-                "filename": f.get("name") or f.get("title"),
-                "size": f.get("size"),
-                "checksum": f.get("checksum") or f.get("md5"),
-                "downloadUrl": f"{self._api_base()}/files/{file_guid}/content" if file_guid else None,
-                # for “pick latest” helper:
-                "version": f.get("version") or f.get("edition"),
-                "updatedAt": f.get("lastModifiedDateTime") or f.get("lastModifiedDate") or f.get("creationDateTime"),
-                "attachmentGroupGuid": row.get("guid"),
-            })
+            norm.append(
+                {
+                    "id": row.get("guid") or row.get("id"),
+                    "fileGuid": file_guid,
+                    "name": f.get("name") or f.get("title"),
+                    "title": f.get("title"),
+                    "filename": f.get("name") or f.get("title"),
+                    "size": f.get("size"),
+                    "haveContent": f.get("haveContent", True),
+                    "downloadUrl": (
+                        f"{self._api_base()}/files/{file_guid}/content"
+                        if file_guid
+                        else None
+                    ),
+                    "edition": f.get("edition"),
+                    "updatedAt": f.get("lastModifiedDateTime")
+                    or f.get("lastModifiedDate")
+                    or f.get("creationDateTime"),
+                    "attachmentGroupGuid": row.get("guid"),
+                }
+            )
         return norm
 
     def _api_resolve_revision_guid(self, item_number: str, selector: str | None) -> str:
@@ -266,7 +539,8 @@ class ArenaClient:
         # Fetch revisions
         url = f"{self._api_base()}/items/{effective_guid}/revisions"
         self._log(f"GET {url}")
-        r = self.session.get(url); r.raise_for_status()
+        r = self.session.get(url)
+        r.raise_for_status()
         data = self._ensure_json(r)
         revs = data.get("results", data if isinstance(data, list) else [])
 
@@ -278,21 +552,36 @@ class ArenaClient:
 
         # Named selectors
         if sel in {"WORKING"}:
-            guid = pick(lambda rv: (rv.get("revisionStatus") or "").upper() == "WORKING" or rv.get("status") == 0)
+            guid = pick(
+                lambda rv: (rv.get("revisionStatus") or "").upper() == "WORKING"
+                or rv.get("status") == 0
+            )
             if not guid:
                 raise ArenaError("No WORKING revision exists for this item.")
             return guid
 
         if sel in {"EFFECTIVE", "APPROVED", "RELEASED"}:
             # Prefer the one not superseded
-            eff = [rv for rv in revs if (rv.get("revisionStatus") or "").upper() == "EFFECTIVE" or rv.get("status") == 1]
+            eff = [
+                rv
+                for rv in revs
+                if (rv.get("revisionStatus") or "").upper() == "EFFECTIVE"
+                or rv.get("status") == 1
+            ]
             if not eff:
-                raise ArenaError("No approved/effective revision exists for this item.")
-            current = next((rv for rv in eff if not rv.get("supersededDateTime")), eff[-1])
+                raise ArenaError(
+                    "No approved/effective revision exists for this item. Try using revision 'WORKING'."
+                )
+            current = next(
+                (rv for rv in eff if not rv.get("supersededDateTime")), eff[-1]
+            )
             return current.get("guid")
 
         # Specific label (e.g., "A", "B2")
-        guid = pick(lambda rv: (rv.get("number") or rv.get("name")) and str(rv.get("number") or rv.get("name")).upper() == sel)
+        guid = pick(
+            lambda rv: (rv.get("number") or rv.get("name"))
+            and str(rv.get("number") or rv.get("name")).upper() == sel
+        )
         if not guid:
             raise ArenaError(f'Revision "{selector}" not found for item {item_number}.')
         return guid
@@ -300,7 +589,8 @@ class ArenaClient:
     def _api_list_files_by_item_guid(self, item_guid: str) -> list[dict]:
         url = f"{self._api_base()}/items/{item_guid}/files"
         self._log(f"GET {url}")
-        r = self.session.get(url); r.raise_for_status()
+        r = self.session.get(url)
+        r.raise_for_status()
         data = self._ensure_json(r)
         rows = data.get("results", data if isinstance(data, list) else [])
         # … keep existing normalization from _api_list_files() …
@@ -308,19 +598,32 @@ class ArenaClient:
         for row in rows:
             f = row.get("file", {}) if isinstance(row, dict) else {}
             file_guid = f.get("guid") or f.get("id")
-            norm.append({
-                "id": row.get("guid") or row.get("id"),
-                "fileGuid": file_guid,
-                "name": f.get("name") or f.get("title"),
-                "filename": f.get("name") or f.get("title"),
-                "size": f.get("size"),
-                "checksum": f.get("checksum") or f.get("md5"),
-                "downloadUrl": f"{self._api_base()}/files/{file_guid}/content" if file_guid else None,
-                "version": f.get("version") or f.get("edition"),
-                "updatedAt": f.get("lastModifiedDateTime") or f.get("lastModifiedDate") or f.get("creationDateTime"),
-                "attachmentGroupGuid": row.get("guid"),
-            })
-        return norm    
+            norm.append(
+                {
+                    "id": row.get("guid") or row.get("id"),
+                    "fileGuid": file_guid,
+                    "title": f.get("title"),
+                    "name": f.get("name"),
+                    "filename": f.get("name"),
+                    "size": f.get("size"),
+                    "haveContent": f.get("haveContent", True),
+                    "downloadUrl": (
+                        f"{self._api_base()}/files/{file_guid}/content"
+                        if file_guid
+                        else None
+                    ),
+                    "edition": f.get("edition"),
+                    "updatedAt": f.get("lastModifiedDateTime")
+                    or f.get("lastModifiedDate")
+                    or f.get("creationDateTime"),
+                    "attachmentGroupGuid": row.get("guid"),
+                    "storageMethodName": (
+                        f.get("storageMethodName") or f.get("storageMethod")
+                    ),
+                    "location": f.get("location"),
+                }
+            )
+        return norm
 
     def _api_upload_or_update_file(
         self,
@@ -339,6 +642,14 @@ class ArenaClient:
         if not file_path.exists() or not file_path.is_file():
             raise ArenaError(f"File not found: {file_path}")
 
+        filename = file_path.name  # Use truncated SHA256 hash if no edition is provided
+        if not edition:
+            # Arena seems to only accept 16 characters of edition information.
+            # The hex digest gives 16 hex × 4 bits = 64 bits of entropy.
+            # Less than a million files, collision risk is practically zero (~1 / 10^8).
+            edition = sha256_file(file_path)
+        edition = str(edition)[:16]
+
         # 0) Resolve EFFECTIVE revision guid from item number
         effective_guid = self._api_resolve_item_guid(item_number)
 
@@ -351,7 +662,9 @@ class ArenaClient:
         rows = data.get("results", data if isinstance(data, list) else [])
         working_guid = None
         for rv in rows:
-            if (str(rv.get("revisionStatus") or "").upper() == "WORKING") or (rv.get("status") == 0):
+            if (str(rv.get("revisionStatus") or "").upper() == "WORKING") or (
+                rv.get("status") == 0
+            ):
                 working_guid = rv.get("guid")
                 break
         if not working_guid:
@@ -371,15 +684,45 @@ class ArenaClient:
         # Try to find existing association by exact filename (WORKING first, then EFFECTIVE)
         filename = file_path.name
         assoc = None
+        if title:
+            candidates = _list_assocs(working_guid)
+
+            def _a_title(a):
+                f = a.get("file") or {}
+                return (f.get("title") or a.get("title") or "").strip().casefold()
+
+            tnorm = title.strip().casefold()
+            # Prefer primary + latestEditionAssociation if duplicates exist
+            preferred = [
+                a
+                for a in candidates
+                if _a_title(a) == tnorm
+                and a.get("primary")
+                and a.get("latestEditionAssociation")
+            ]
+            if preferred:
+                assoc = preferred[0]
+            else:
+                any_match = [a for a in candidates if _a_title(a) == tnorm]
+                if any_match:
+                    assoc = any_match[0]
+
         for guid in (working_guid, effective_guid):
             assocs = _list_assocs(guid)
             # prefer primary && latestEditionAssociation, then any by name
-            prim_latest = [a for a in assocs if a.get("primary") and a.get("latestEditionAssociation")
-                           and ((a.get("file") or {}).get("name") == filename)]
+            prim_latest = [
+                a
+                for a in assocs
+                if a.get("primary")
+                and a.get("latestEditionAssociation")
+                and ((a.get("file") or {}).get("name") == filename)
+            ]
             if prim_latest:
                 assoc = prim_latest[0]
                 break
-            any_by_name = [a for a in assocs if (a.get("file") or {}).get("name") == filename]
+            any_by_name = [
+                a for a in assocs if (a.get("file") or {}).get("name") == filename
+            ]
             if any_by_name:
                 assoc = any_by_name[0]
                 break
@@ -400,6 +743,17 @@ class ArenaClient:
                     if existing_ct is not None:
                         self.session.headers["Content-Type"] = existing_ct
             ur.raise_for_status()
+
+            # Update the edition label on the File itself
+            try:
+                put_url = f"{self._api_base()}/files/{file_guid}"
+                self._log(f"PUT {put_url} (set edition={edition})")
+                pr = self.session.put(put_url, json={"edition": str(edition)})
+                pr.raise_for_status()
+            except requests.HTTPError as e:
+                # Don't fail the whole operation if the label update is rejected
+                self._log(f"Edition update failed for {file_guid}: {e}")
+
             # Many tenants return 201 with no JSON for content updates. Be flexible.
             data = self._try_json(ur)
             if data is None:
@@ -409,6 +763,7 @@ class ArenaClient:
                     "status": ur.status_code,
                     "fileGuid": file_guid,
                     "location": ur.headers.get("Location"),
+                    "edition": str(edition),
                 }
             return data
 
@@ -421,30 +776,44 @@ class ArenaClient:
         cats = self._ensure_json(r).get("results", [])
         cat_guid = None
         for c in cats:
-            if c.get("name") == category_name and (c.get("parentCategory") or {}).get("name") in {"Internal File", None}:
+            if c.get("name") == category_name and (c.get("parentCategory") or {}).get(
+                "name"
+            ) in {"Internal File", None}:
                 cat_guid = c.get("guid")
                 break
         if not cat_guid:
-            raise ArenaError(f'File category "{category_name}" not found or not allowed.')
+            raise ArenaError(
+                f'File category "{category_name}" not found or not allowed.'
+            )
 
         # 3) Prepare multipart (create association)
-        title = title or file_path.stem
-        file_format = file_format or (file_path.suffix[1:].lower() if file_path.suffix else "bin")
+        title = title or file_path.name
+        file_format = file_format or (
+            file_path.suffix[1:].lower() if file_path.suffix else "bin"
+        )
         description = description or "Uploaded via gladiator"
-        files = {"content": (file_path.name, open(file_path, "rb"), "application/octet-stream")}
+        files = {
+            "content": (
+                file_path.name,
+                open(file_path, "rb"),
+                "application/octet-stream",
+            )
+        }
 
         # NOTE: nested field names are sent in `data`, not `files`
         data_form = {
-             "file.title": title,
-             "file.description": description,
-             "file.category.guid": cat_guid,
-             "file.format": file_format,
-             "file.edition": str(edition),
-             "file.storageMethodName": "FILE",
-             "file.private": "false",
-             "primary": "true" if primary else "false",
-             "latestEditionAssociation": "true" if latest_edition_association else "false",
-         }
+            "file.title": title,
+            "file.description": description,
+            "file.category.guid": cat_guid,
+            "file.format": file_format,
+            "file.edition": str(edition),
+            "file.storageMethodName": "FILE",
+            "file.private": "false",
+            "primary": "true" if primary else "false",
+            "latestEditionAssociation": (
+                "true" if latest_edition_association else "false"
+            ),
+        }
         if reference:
             data_form["reference"] = reference
 
@@ -466,6 +835,22 @@ class ArenaClient:
         # Normalize common fields we use elsewhere
         row = resp if isinstance(resp, dict) else {}
         f = row.get("file", {})
+
+        # Ensure the edition label is exactly what we asked for (some tenants ignore form edition)
+        try:
+            file_guid_created = (f or {}).get("guid")
+            if file_guid_created and str(edition):
+                put_url = f"{self._api_base()}/files/{file_guid_created}"
+                self._log(f"PUT {put_url} (set edition={edition})")
+                pr = self.session.put(put_url, json={"edition": str(edition)})
+                pr.raise_for_status()
+                # Update local 'f' edition if the PUT succeeded
+                f["edition"] = str(edition)
+        except requests.HTTPError as e:
+            self._log(
+                f"Edition update after create failed for {file_guid_created}: {e}"
+            )
+
         return {
             "associationGuid": row.get("guid"),
             "primary": row.get("primary"),
@@ -477,10 +862,14 @@ class ArenaClient:
                 "size": f.get("size"),
                 "format": f.get("format"),
                 "category": (f.get("category") or {}).get("name"),
-                "edition": f.get("edition"),
+                "edition": f.get("edition") or str(edition),
                 "lastModifiedDateTime": f.get("lastModifiedDateTime"),
             },
-            "downloadUrl": f"{self._api_base()}/files/{(f or {}).get('guid')}/content" if f.get("guid") else None,
+            "downloadUrl": (
+                f"{self._api_base()}/files/{(f or {}).get('guid')}/content"
+                if f.get("guid")
+                else None
+            ),
         }
 
     def _api_resolve_item_guid(self, item_number: str) -> str:
@@ -493,11 +882,272 @@ class ArenaClient:
         results = data.get("results") if isinstance(data, dict) else data
         if not results:
             raise ArenaError(f"Item number {item_number} not found")
-        guid = (results[0].get("guid") or results[0].get("id") or results[0].get("itemId"))
+        guid = (
+            results[0].get("guid") or results[0].get("id") or results[0].get("itemId")
+        )
         if not guid:
             raise ArenaError("API response missing item GUID")
         return guid
 
+    # --- helper: resolve File Category GUID by name (exact match under Settings) ---
+    def _api_resolve_file_category_guid(self, category_name: str) -> str:
+        cats_url = f"{self._api_base()}/settings/files/categories"
+        self._log(f"GET {cats_url}")
+        r = self.session.get(cats_url)
+        r.raise_for_status()
+        cats = self._ensure_json(r).get("results", [])
+        for c in cats:
+            if c.get("name") == category_name:
+                return c.get("guid")
+        raise ArenaError(f'File category "{category_name}" not found.')
+
+    # --- helper: create a WEB File (no binary content) and return its GUID ---
+    def _api_create_web_file(
+        self,
+        *,
+        category_guid: str,
+        title: str,
+        location_url: str,
+        edition: str,
+        description: Optional[str],
+        file_format: Optional[str],
+        private: bool = False,
+    ) -> dict:
+        """
+        POST /files  (create File record with storageMethodName=WEB and a 'location')
+        """
+        url = f"{self._api_base()}/files"
+        payload = {
+            "category": {"guid": category_guid},
+            "title": title,
+            "description": description or "",
+            "edition": str(edition),
+            "format": file_format or "url",
+            "private": bool(private),
+            "storageMethodName": "WEB",
+            "location": location_url,
+        }
+        self._log(f"POST {url} (create web file)")
+        r = self.session.post(url, json=payload)
+        r.raise_for_status()
+        data = self._ensure_json(r)
+        if not isinstance(data, dict) or not data.get("guid"):
+            raise ArenaError("File create (WEB) returned no GUID")
+        return data  # includes "guid", "number", etc.
+
+    # --- helper: PUT File (update WEB metadata/location/edition) ---
+    def _api_update_web_file(
+        self,
+        *,
+        file_guid: str,
+        category_guid: str,
+        title: str,
+        location_url: str,
+        edition: str,
+        description: Optional[str],
+        file_format: Optional[str],
+        private: bool = False,
+    ) -> dict:
+        """
+        PUT /files/{guid} (update summary). For WEB/FTP/PLACE_HOLDER, include 'location'.
+        """
+        url = f"{self._api_base()}/files/{file_guid}"
+        payload = {
+            "category": {"guid": category_guid},
+            "title": title,
+            "description": description or "",
+            "edition": str(edition),
+            "format": file_format or "url",
+            "private": bool(private),
+            "storageMethodName": "WEB",
+            "location": location_url,
+        }
+        self._log(f"PUT {url} (update web file)")
+        r = self.session.put(url, json=payload)
+        r.raise_for_status()
+        return self._ensure_json(r)
+
+    def _api_item_add_existing_file(
+        self,
+        *,
+        item_guid: str,
+        file_guid: str,
+        primary: bool,
+        latest_edition_association: bool,
+        reference: Optional[str] = None,
+    ) -> dict:
+        url = f"{self._api_base()}/items/{item_guid}/files"
+        payload = {
+            "primary": bool(primary),
+            "latestEditionAssociation": bool(latest_edition_association),
+            "file": {"guid": file_guid},
+        }
+        if reference:
+            payload["reference"] = reference
+        r = self.session.post(url, json=payload)
+        r.raise_for_status()
+        return self._ensure_json(r)
+
+    def upload_weblink_to_working(
+        self,
+        *,
+        item_number: str,
+        url: str,
+        reference: Optional[str] = None,  # (unused by "add existing"; kept for parity)
+        title: str,
+        category_name: str = "Web Link",
+        file_format: Optional[str] = "url",
+        description: Optional[str] = None,
+        primary: bool = True,
+        latest_edition_association: bool = True,
+        edition: Optional[str] = None,
+    ) -> Dict:
+        """
+        Idempotent "upsert" of a WEB-link File on the WORKING revision of `item_number`.
+
+        Match rules (WORKING first, then EFFECTIVE):
+          - any association whose File has storageMethodName in {"WEB","FTP"} AND
+            (File.title == title OR File.location == url)
+
+        If found -> PUT /files/{fileGuid} with storageMethodName=WEB + location + edition.
+        Else      -> POST /files (create) + POST /items/{workingGuid}/files (add existing).
+        """
+        # Compute an edition if none is provided (SHA256 of the URL, truncated to 16)
+        if not edition:
+            edition = hashlib.sha256(url.encode("utf-8")).hexdigest()
+        edition = str(edition)[:16]
+
+        # Resolve item GUIDs
+        effective_guid = self._api_resolve_item_guid(item_number)
+        revs_url = f"{self._api_base()}/items/{effective_guid}/revisions"
+        self._log(f"GET {revs_url}")
+        r = self.session.get(revs_url)
+        r.raise_for_status()
+        revs = self._ensure_json(r).get("results", [])
+        working_guid = None
+        for rv in revs:
+            if (str(rv.get("revisionStatus") or "").upper() == "WORKING") or (
+                rv.get("status") == 0
+            ):
+                working_guid = rv.get("guid")
+                break
+        if not working_guid:
+            raise ArenaError(
+                "No WORKING revision exists for this item. Create a working revision in Arena, then retry."
+            )
+
+        # Resolve category GUID
+        cat_guid = self._api_resolve_file_category_guid(category_name)
+
+        # Helper to list associations for a given item/revision guid
+        def _list_assocs(guid: str) -> list[dict]:
+            url2 = f"{self._api_base()}/items/{guid}/files"
+            self._log(f"GET {url2}")
+            lr = self.session.get(url2)
+            lr.raise_for_status()
+            payload = self._ensure_json(lr)
+            return payload.get("results", payload if isinstance(payload, list) else [])
+
+        # Try to find an existing WEB/FTP style file by title or URL
+        def _pick_assoc_by_title_or_url(assocs: list[dict]) -> Optional[dict]:
+            pick = None
+            for a in assocs:
+                f = a.get("file") or {}
+                smn = str(
+                    f.get("storageMethodName") or f.get("storageMethod") or ""
+                ).upper()
+                if smn not in {"WEB", "FTP"}:
+                    continue
+                f_title = (f.get("title") or "").strip()
+                f_loc = (f.get("location") or "").strip()
+                if (f_title and f_title == title) or (f_loc and f_loc == url):
+                    if not pick:
+                        pick = a
+                        continue
+                    # prefer latestEditionAssociation + primary
+                    if (
+                        a.get("latestEditionAssociation") and a.get("primary")
+                    ) and not (
+                        pick.get("latestEditionAssociation") and pick.get("primary")
+                    ):
+                        pick = a
+            return pick
+
+        assoc = _pick_assoc_by_title_or_url(
+            _list_assocs(working_guid)
+        ) or _pick_assoc_by_title_or_url(_list_assocs(effective_guid))
+
+        # If found: update the File summary (ensures storageMethodName=WEB + new location/edition)
+        if assoc:
+            file_guid = (assoc.get("file") or {}).get("guid")
+            if not file_guid:
+                raise ArenaError(
+                    "Existing web-link association found but missing file.guid"
+                )
+            updated = self._api_update_web_file(
+                file_guid=file_guid,
+                category_guid=cat_guid,
+                title=title,
+                location_url=url,
+                edition=str(edition),
+                description=description,
+                file_format=file_format,
+                private=False,
+            )
+            # Normalize to a consistent response
+            return {
+                "ok": True,
+                "action": "updated",
+                "file": {
+                    "guid": updated.get("guid"),
+                    "number": updated.get("number"),
+                    "title": updated.get("title"),
+                    "edition": updated.get("edition"),
+                    "storageMethodName": updated.get("storageMethodName"),
+                    "location": updated.get("location"),
+                },
+                "associationGuid": assoc.get("guid"),
+                "primary": assoc.get("primary"),
+                "latestEditionAssociation": assoc.get("latestEditionAssociation"),
+            }
+
+        # Else: create a new WEB file, then associate it on WORKING
+        created = self._api_create_web_file(
+            category_guid=cat_guid,
+            title=title,
+            location_url=url,
+            edition=str(edition),
+            description=description,
+            file_format=file_format,
+            private=False,
+        )
+        file_guid = created.get("guid")
+        assoc_resp = self._api_item_add_existing_file(
+            item_guid=working_guid,
+            file_guid=file_guid,
+            primary=primary,
+            latest_edition_association=latest_edition_association,
+            reference=reference,
+        )
+
+        return {
+            "ok": True,
+            "action": "created",
+            "associationGuid": assoc_resp.get("guid"),
+            "primary": assoc_resp.get("primary"),
+            "latestEditionAssociation": assoc_resp.get("latestEditionAssociation"),
+            "file": {
+                "guid": file_guid,
+                "number": created.get("number"),
+                "title": created.get("title"),
+                "edition": created.get("edition"),
+                "storageMethodName": created.get("storageMethodName") or "WEB",
+                "location": created.get("location") or url,
+            },
+        }
+
     def _run(self, cmd: str) -> Tuple[int, str, str]:
-        proc = subprocess.run(cmd, shell=True, check=False, capture_output=True, text=True)
+        proc = subprocess.run(
+            cmd, shell=True, check=False, capture_output=True, text=True
+        )
         return proc.returncode, proc.stdout.strip(), proc.stderr.strip()