python-substack 0.9.0__py3-none-any.whl → 0.10.0__py3-none-any.whl

{python_substack-0.9.0.dist-info → python_substack-0.10.0.dist-info}/METADATA

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: python-substack
-Version: 0.9.0
+Version: 0.10.0
 Summary: Write and safely manage Substack drafts from Markdown with Python, CLI, and MCP.
-License: MIT
+License-Expression: MIT
 License-File: LICENSE
 Keywords: substack,substack-api,cli,newsletter,publishing,automation,mcp
 Author: Paolo Mazza
@@ -10,13 +10,11 @@ Author-email: mazzapaolo2019@gmail.com
 Requires-Python: >=3.10,<4.0
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Communications :: Email
 Classifier: Topic :: Internet :: WWW/HTTP
 Classifier: Topic :: Software Development :: Libraries :: Python Modules

python_substack-0.10.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+substack/__init__.py,sha256=1z7cdQwJPM4msiHdIoSzm4etUIu5Jcc5CKmFDHcnODA,451
+substack/api.py,sha256=KWEJXjlxZY1sQ9j5qZSGxHfaATyE3O9Nup_elsXBHNU,37927
+substack/cli.py,sha256=dgUTgZeX4sgJDXsFmPIJRBpNGgGQyLR2OpXoEcoHQa0,27586
+substack/exceptions.py,sha256=xuckEoS-PYGYt-9zvuG8CDbr4WncpuKqGXN34yBvGnE,2140
+substack/mdexport.py,sha256=Tzkav3mnF9eIUVHUqUzEQkOTiJsLYde1Xi2AcE_cUdk,14017
+substack/mdrender.py,sha256=xRJIO4_6gcQ9jwLFm32KByi7bRmOJyowqF41GmYCA7A,15450
+substack/nodes.py,sha256=fTsGO0-lTztcXiloIjXrHVnJes9EcltGcrX-mEV2ceQ,5004
+substack/post.py,sha256=qDXu-xzO3nRXtahc-yG2EhxKAXB2hG_Z1nLa55UMBGg,19697
+substack/revision.py,sha256=guEJ8vd38eqHHDqwHL0baf3v02U7RO34Li3D2pvCka8,8796
+substack_mcp/mcp_server.py,sha256=M5XH3C4iWjzvCw3uOPbY2NFljTQAl8FLt14RKaTzka0,11324
+python_substack-0.10.0.dist-info/METADATA,sha256=fgjfdA7h0iQv_kCqxFLFw3Gemhd-LHeJOKhhEZFxthc,9209
+python_substack-0.10.0.dist-info/WHEEL,sha256=kJCRJT_g0adfAJzTx2GUMmS80rTJIVHRCfG0DQgLq3o,88
+python_substack-0.10.0.dist-info/entry_points.txt,sha256=MKPjaBUd-0PtvxsBviStsVq1c0h8JZ_qUoYEsBK1xJc,236
+python_substack-0.10.0.dist-info/licenses/LICENSE,sha256=L6jk148I5HhhVbfUvkO3EO7eAoU5zToLio4-ApkCkxg,1062
+python_substack-0.10.0.dist-info/RECORD,,

substack/__init__.py

@@ -3,7 +3,7 @@
 __author__ = "Paolo Mazza"
 __email__ = "mazzapaolo2019@gmail.com"
 __license__ = "MIT License"
-__version__ = "0.9.0"
+__version__ = "0.10.0"
 __url__ = "https://github.com/ma2za/python-substack"
 __download_url__ = "https://pypi.python.org/pypi/python-substack"
 __description__ = (

substack/api.py

@@ -460,6 +460,7 @@ class Api:
 
     def export_draft_to_markdown(self, draft_id):
         from substack.mdexport import document_to_markdown
+        from substack.revision import compute_draft_revision, format_revision_marker
 
         draft = self.get_draft(draft_id)
         draft_body = draft.get("draft_body")
@@ -474,9 +475,15 @@ class Api:
             raise ValueError("Malformed draft body: draft_body must be a JSON object")
 
         markdown, unsupported_nodes = document_to_markdown(draft_body)
+        revision = compute_draft_revision(draft)
+        revision_marker = format_revision_marker(revision)
+        full_markdown = (
+            f"{revision_marker}\n\n{markdown}" if markdown else f"{revision_marker}\n"
+        )
         return {
             "draft": draft,
-            "markdown": markdown,
+            "markdown": full_markdown,
+            "revision": revision,
             "unsupported_nodes": unsupported_nodes,
         }
 
@@ -496,12 +503,22 @@ class Api:
         dry_run: bool = False,
         allow_unsupported_change: bool = False,
         allow_image_replacement: bool = False,
+        expected_revision=None,
+        allow_conflict: bool = False,
+        force: bool = False,
     ) -> dict:
         """
         Update an existing draft body from Markdown, with optional metadata changes.
         """
+        from substack import mdrender
+        from substack.exceptions import DraftConflictError
         from substack.mdexport import document_to_markdown
         from substack.post import Post
+        from substack.revision import (
+            compare_draft_revisions,
+            compute_draft_revision,
+            parse_revision_marker,
+        )
 
         draft = self.get_draft(draft_id)
         draft_body = draft.get("draft_body")
@@ -515,8 +532,53 @@ class Api:
         if not isinstance(draft_body, dict):
             raise ValueError("Malformed draft body: draft_body must be a JSON object")
 
+        current_rev = compute_draft_revision(draft)
+
+        target_expected_rev = None
+        if expected_revision is not None:
+            if isinstance(expected_revision, dict):
+                target_expected_rev = expected_revision
+            elif isinstance(expected_revision, str):
+                target_expected_rev = {"revision": expected_revision}
+            else:
+                raise ValueError("expected_revision must be a revision dict or string")
+        else:
+            target_expected_rev = parse_revision_marker(markdown)
+
+        override_enabled = bool(allow_conflict or force)
+        conflict_detected = False
+        mismatches = []
+
+        if target_expected_rev is None:
+            conflict_detected = True
+            mismatches = [
+                "Markdown file is missing revision metadata (unprotected update); safe conflict comparison is impossible."
+            ]
+            if not override_enabled and not dry_run:
+                raise DraftConflictError(
+                    "Refusing to update: Markdown file is missing revision metadata (unprotected update). "
+                    "Export the draft first or pass allow_conflict=True to proceed.",
+                    mismatches=mismatches,
+                    expected_revision=None,
+                    current_revision=current_rev,
+                )
+        else:
+            mismatches = compare_draft_revisions(target_expected_rev, current_rev)
+            if mismatches:
+                conflict_detected = True
+                if not override_enabled and not dry_run:
+                    details = "; ".join(mismatches)
+                    raise DraftConflictError(
+                        f"Refusing to update: remote draft has changed since export ({details}). "
+                        "Re-export the draft or pass allow_conflict=True to proceed.",
+                        mismatches=mismatches,
+                        expected_revision=target_expected_rev,
+                        current_revision=current_rev,
+                    )
+
         _, remote_unsupported = document_to_markdown(draft_body)
 
+        image_markers = []
         post = Post(
             title=draft.get("title", ""),
             subtitle=(
@@ -526,30 +588,88 @@ class Api:
             audience=audience,
             write_comment_permissions=write_comment_permissions,
         )
-        post.from_markdown(markdown, api=self)
+        rendered = mdrender.markdown_to_doc(
+            markdown, api=self, track_markers=image_markers
+        )
+        post.draft_body["content"] = rendered
 
         remote_images = _image_attrs(draft_body)
         submitted_images = _image_attrs(post.draft_body)
-        for submitted in submitted_images:
-            matches = [
-                image
-                for image in remote_images
-                if image.get("src") == submitted.get("src")
-            ]
-            if len(matches) == 1:
+
+        consumed_remote_indices = set()
+
+        for submitted, marker in zip(submitted_images, image_markers):
+            if marker is not None and marker.get("version") == 2:
+                bound_src = marker["src"]
+                matched_idx = None
+                for idx, r_img in enumerate(remote_images):
+                    if (
+                        idx not in consumed_remote_indices
+                        and r_img.get("src") == bound_src
+                    ):
+                        matched_idx = idx
+                        break
+
+                if matched_idx is None:
+                    all_with_src = [
+                        idx
+                        for idx, r_img in enumerate(remote_images)
+                        if r_img.get("src") == bound_src
+                    ]
+                    if not all_with_src:
+                        raise ValueError(
+                            f"Refusing to update: stale image marker bound to '{bound_src}'."
+                        )
+                    else:
+                        raise ValueError(
+                            f"Refusing to update: reused or duplicate image marker for '{bound_src}'."
+                        )
+
+                consumed_remote_indices.add(matched_idx)
+                remote_img = remote_images[matched_idx]
                 source, alt, href = (
                     submitted.get("src"),
                     submitted.get("alt"),
                     submitted.get("href"),
                 )
-                submitted.update(matches[0])
+                submitted.update(remote_img)
+                submitted.update(marker["attrs"])
                 submitted.update(
                     {"src": source, "alt": alt, "href": href, "isProcessing": False}
                 )
-            elif not allow_image_replacement:
-                raise ValueError(
-                    "Refusing to update: image cannot be matched uniquely; set allow_image_replacement=True to proceed."
-                )
+
+            elif marker is not None and marker.get("version") == 1:
+                sub_src = submitted.get("src")
+                matches = [
+                    idx
+                    for idx, r_img in enumerate(remote_images)
+                    if r_img.get("src") == sub_src
+                    and idx not in consumed_remote_indices
+                ]
+                if len(matches) == 1:
+                    matched_idx = matches[0]
+                    consumed_remote_indices.add(matched_idx)
+                    remote_img = remote_images[matched_idx]
+                    source, alt, href = (
+                        submitted.get("src"),
+                        submitted.get("alt"),
+                        submitted.get("href"),
+                    )
+                    submitted.update(remote_img)
+                    submitted.update(marker["attrs"])
+                    submitted.update(
+                        {"src": source, "alt": alt, "href": href, "isProcessing": False}
+                    )
+                elif not allow_image_replacement:
+                    raise ValueError(
+                        "Refusing to update: image cannot be matched uniquely; set allow_image_replacement=True to proceed."
+                    )
+
+            else:
+                if not allow_image_replacement:
+                    raise ValueError(
+                        "Refusing to update: image cannot be matched uniquely; set allow_image_replacement=True to proceed."
+                    )
 
         _, submitted_unsupported = document_to_markdown(post.draft_body)
 
@@ -597,7 +717,7 @@ class Api:
             if tags_list:
                 tags_result = self.add_tags_to_post(draft_id, tags_list)
 
-        return {
+        result_payload = {
             "action": "update",
             "draft_id": draft_id,
             "dry_run": dry_run,
@@ -606,7 +726,14 @@ class Api:
             "draft": updated_draft,
             "tags": tags_result,
             "unsupported_nodes": unsupported_nodes,
+            "conflict": conflict_detected,
+            "mismatches": mismatches,
+            "expected_revision": target_expected_rev,
+            "current_revision": current_rev,
         }
+        if override_enabled and conflict_detected:
+            result_payload["override"] = True
+        return result_payload
 
     def delete_draft(self, draft_id):
         """

substack/cli.py

@@ -10,7 +10,11 @@ import yaml
 from dotenv import load_dotenv
 
 from substack import Api, __version__
-from substack.exceptions import SubstackAPIException, SubstackRequestException
+from substack.exceptions import (
+    DraftConflictError,
+    SubstackAPIException,
+    SubstackRequestException,
+)
 from substack.post import Post
 
 
@@ -146,6 +150,14 @@ def _redact(message):
 
 
 def _error_payload(exc):
+    if isinstance(exc, DraftConflictError):
+        return {
+            "error": {
+                "type": "conflict_error",
+                "message": _redact(exc.message),
+                "mismatches": exc.mismatches,
+            }
+        }
     if isinstance(exc, SubstackAPIException):
         return {
             "error": {
@@ -314,6 +326,8 @@ def _drafts_update(api, args):
         raise CLIUsageError("--yes is required when using --allow-unsupported-change")
     if args.allow_image_replacement and not args.yes:
         raise CLIUsageError("--yes is required when using --allow-image-replacement")
+    if args.allow_conflict and not args.yes:
+        raise CLIUsageError("--yes is required when using --allow-conflict")
 
     if not args.yes and (args.json_output or not sys.stdin.isatty()):
         raise CLIUsageError("--yes is required in non-interactive or JSON mode")
@@ -354,13 +368,25 @@ def _drafts_update(api, args):
         dry_run=args.dry_run,
         allow_unsupported_change=args.allow_unsupported_change,
         allow_image_replacement=args.allow_image_replacement,
+        allow_conflict=args.allow_conflict,
     )
 
     if args.json_output:
         _print_json(result)
     else:
         status = "Dry-run updated" if args.dry_run else "Updated"
-        print(f"{status} draft {args.draft_id}")
+        if result.get("conflict"):
+            print(f"Conflict detected in draft {args.draft_id}:")
+            for mismatch in result.get("mismatches", []):
+                print(f"  - {mismatch}")
+            if result.get("dry_run"):
+                print(
+                    f"Dry-run preview completed for draft {args.draft_id} with conflicts."
+                )
+            else:
+                print(f"{status} draft {args.draft_id} (override applied)")
+        else:
+            print(f"{status} draft {args.draft_id}")
 
 
 def _drafts_export(api, args):
@@ -381,6 +407,8 @@ def _drafts_export(api, args):
         "markdown": markdown,
         "unsupported_nodes": result["unsupported_nodes"],
     }
+    if "revision" in result and result["revision"] is not None:
+        payload["revision"] = result["revision"]
     if args.json_output:
         _print_json(payload)
     elif output_path is not None:
@@ -517,6 +545,13 @@ def _build_parser():
     drafts_update.add_argument("--dry-run", action="store_true")
     drafts_update.add_argument("--allow-unsupported-change", action="store_true")
     drafts_update.add_argument("--allow-image-replacement", action="store_true")
+    drafts_update.add_argument(
+        "--allow-conflict",
+        "--force",
+        action="store_true",
+        dest="allow_conflict",
+        help="Allow updating draft even if remote revision has changed or revision metadata is missing.",
+    )
     drafts_update.add_argument("--yes", action="store_true")
     drafts_update.set_defaults(handler=_drafts_update)
 

substack/exceptions.py

@@ -12,7 +12,13 @@ def _redact_message(text: str) -> str:
     return text
 
 
-class SubstackAPIException(Exception):
+class SubstackException(Exception):
+    """Base exception for all python-substack exceptions."""
+
+    pass
+
+
+class SubstackAPIException(SubstackException):
     def __init__(self, status_code, text):
         text = _redact_message(text)
         try:
@@ -32,7 +38,7 @@ class SubstackAPIException(Exception):
         return f"APIError(code={self.status_code}): {self.message}"
 
 
-class SubstackRequestException(Exception):
+class SubstackRequestException(SubstackException):
     def __init__(self, message):
         self.message = _redact_message(message)
 
@@ -42,3 +48,23 @@ class SubstackRequestException(Exception):
 
 class SectionNotExistsException(SubstackRequestException):
     pass
+
+
+class DraftConflictError(ValueError, SubstackException):
+    """Raised when an update conflicts with the current remote draft state or lacks revision metadata."""
+
+    def __init__(
+        self,
+        message: str,
+        mismatches: list = None,
+        expected_revision: dict = None,
+        current_revision: dict = None,
+    ):
+        super().__init__(message)
+        self.message = message
+        self.mismatches = mismatches or []
+        self.expected_revision = expected_revision
+        self.current_revision = current_revision
+
+    def __str__(self):
+        return self.message

substack/mdexport.py

@@ -58,18 +58,19 @@ def _marker(node, unsupported):
 
 
 def _image_marker(attrs):
-    preserved = {
-        key: value
-        for key, value in attrs.items()
-        if key not in {"src", "alt", "href", "isProcessing"}
+    payload_data = {
+        "src": attrs["src"],
+        **{
+            key: value
+            for key, value in attrs.items()
+            if key not in {"src", "alt", "href", "isProcessing"}
+        },
     }
-    if not preserved:
-        return ""
     payload = json.dumps(
-        preserved, ensure_ascii=False, separators=(",", ":"), sort_keys=True
+        payload_data, ensure_ascii=False, separators=(",", ":"), sort_keys=True
     ).encode("utf-8")
     encoded = base64.urlsafe_b64encode(payload).decode("ascii").rstrip("=")
-    return f"\n<!-- python-substack-image:v1 {encoded} -->"
+    return f"\n<!-- python-substack-image:v2 {encoded} -->"
 
 
 def _require_dict(node, context):
@@ -229,7 +230,6 @@ def _render_image(node, unsupported):
         image["type"] != "image2"
         or _has_unknown_keys(node, {"type", "content"})
         or _has_unknown_keys(image, {"type", "attrs"})
-        or _has_unknown_keys(attrs, _IMAGE_ATTRS)
         or not isinstance(attrs.get("src"), str)
     ):
         return _marker(node, unsupported)

substack/mdrender.py

@@ -45,7 +45,7 @@ _MARK_FOR = {
 }
 
 
-def parse_node_marker(comment_content: str) -> dict | None:
+def parse_node_marker(comment_content: str) -> dict | None:
     """
     Parse a python-substack-node:v1 comment marker and return the parsed JSON dictionary.
 
@@ -88,29 +88,45 @@ def parse_node_marker(comment_content: str) -> dict | None:
     if not isinstance(node_type, str) or not node_type:
         raise ValueError("Marker payload has missing or empty 'type'")
 
-    return data
-
-
-def parse_image_marker(comment_content: str) -> dict | None:
-    clean = comment_content.strip()
-    match = re.match(
-        r"^<!--\s*python-substack-image:v1\s+([A-Za-z0-9_-]+=*)\s*-->$", clean
-    )
-    if not match:
-        if "python-substack-image:v1" in clean:
-            raise ValueError("Corrupt image marker format")
-        return None
-    encoded = match.group(1)
-    encoded += "=" * (-len(encoded) % 4)
-    try:
-        attrs = json.loads(base64.urlsafe_b64decode(encoded.encode("ascii")))
-    except Exception as exc:
-        raise ValueError("Invalid image marker") from exc
-    if not isinstance(attrs, dict) or any(
-        key in {"src", "alt", "href", "isProcessing"} for key in attrs
-    ):
-        raise ValueError("Invalid image marker attributes")
-    return attrs
+    return data
+
+
+def parse_image_marker(comment_content: str) -> dict | None:
+    clean = comment_content.strip()
+    match = re.match(
+        r"^<!--\s*python-substack-image:(v1|v2)\s+([A-Za-z0-9_-]+=*)\s*-->$", clean
+    )
+    if not match:
+        if "python-substack-image:" in clean:
+            raise ValueError("Corrupt image marker format")
+        return None
+    version_str, encoded = match.group(1), match.group(2)
+    encoded += "=" * (-len(encoded) % 4)
+    try:
+        decoded_bytes = base64.urlsafe_b64decode(encoded.encode("ascii"))
+    except Exception as exc:
+        raise ValueError("Invalid image marker") from exc
+    try:
+        attrs = json.loads(decoded_bytes.decode("utf-8"))
+    except Exception as exc:
+        raise ValueError("Invalid image marker") from exc
+    if not isinstance(attrs, dict):
+        raise ValueError("Invalid image marker attributes")
+
+    if version_str == "v1":
+        if any(key in {"src", "alt", "href", "isProcessing"} for key in attrs):
+            raise ValueError("Invalid image marker attributes")
+        return {"version": 1, "src": None, "attrs": attrs}
+
+    if version_str == "v2":
+        if "src" not in attrs or not isinstance(attrs["src"], str):
+            raise ValueError("Invalid image marker attributes")
+        if any(key in {"alt", "href", "isProcessing"} for key in attrs):
+            raise ValueError("Invalid image marker attributes")
+        preserved = {k: v for k, v in attrs.items() if k != "src"}
+        return {"version": 2, "src": attrs["src"], "attrs": preserved}
+
+    return None
 
 
 def _make_parser() -> MarkdownIt:
@@ -177,6 +193,8 @@ def _render_inline(node: SyntaxTreeNode, marks: List[Dict], ctx: Dict) -> List[D
             if alt:
                 out.append(nodes.text(alt, marks))
         elif t == "html_inline":
+            if "python-substack-image:" in child.content:
+                raise ValueError("Image marker must immediately follow an image")
             marker_data = parse_node_marker(child.content)
             if marker_data is not None:
                 out.append(marker_data)
@@ -325,7 +343,9 @@ def _footnote_definitions(tree: SyntaxTreeNode, api) -> Dict[int, List[Dict]]:
     return definitions
 
 
-def markdown_to_doc(markdown_content: str, api=None) -> List[Dict]:
+def markdown_to_doc(
+    markdown_content: str, api=None, track_markers: Optional[List] = None
+) -> List[Dict]:
     """Convert Markdown into a list of Substack ProseMirror block nodes."""
     tree = SyntaxTreeNode(_make_parser().parse(markdown_content))
 
@@ -333,18 +353,39 @@ def markdown_to_doc(markdown_content: str, api=None) -> List[Dict]:
 
     ctx: Dict = {"order": []}
     out: List[Dict] = []
-    for node in tree.children:
-        if node.type == "footnote_block":
-            continue
-        if node.type == "html_block":
-            attrs = parse_image_marker(node.content)
-            if attrs is not None:
-                if not out or out[-1].get("type") != "captionedImage":
-                    raise ValueError("Image marker must immediately follow an image")
-                out[-1]["content"][0]["attrs"].update(attrs)
-                out[-1]["content"][0]["attrs"]["isProcessing"] = False
-                continue
-        out.extend(_render_block(node, api, ctx))
+    last_was_image = False
+    last_image_idx: Optional[int] = None
+
+    for node in tree.children:
+        if node.type == "footnote_block":
+            last_was_image = False
+            continue
+        if node.type == "html_block":
+            marker = parse_image_marker(node.content)
+            if marker is not None:
+                if not last_was_image or last_image_idx is None:
+                    raise ValueError("Image marker must immediately follow an image")
+                last_was_image = False
+                out[last_image_idx]["content"][0]["attrs"].update(marker["attrs"])
+                out[last_image_idx]["content"][0]["attrs"]["isProcessing"] = False
+                if track_markers is not None:
+                    track_markers[-1] = marker
+                continue
+            last_was_image = False
+
+        rendered = _render_block(node, api, ctx)
+        if rendered:
+            for blk in rendered:
+                out.append(blk)
+                if blk.get("type") == NodeType.CAPTIONED_IMAGE:
+                    last_was_image = True
+                    last_image_idx = len(out) - 1
+                    if track_markers is not None:
+                        track_markers.append(None)
+                else:
+                    last_was_image = False
+        else:
+            last_was_image = False
 
     # Emit one footnote block per reference, in anchor order, numbered to match.
     for number, footnote_id in enumerate(ctx["order"], start=1):

substack/revision.py

@@ -0,0 +1,254 @@
+import base64
+import hashlib
+import json
+import re
+from typing import Any, Dict, List, Optional
+
+from markdown_it import MarkdownIt
+
+
+def compute_draft_revision(draft: Dict[str, Any]) -> Dict[str, Any]:
+    """Compute deterministic revision and fingerprint metadata from a Substack draft dict."""
+    draft_id = draft.get("id")
+    title = (
+        draft.get("draft_title") if "draft_title" in draft else draft.get("title", "")
+    )
+    subtitle = (
+        draft.get("draft_subtitle")
+        if "draft_subtitle" in draft
+        else draft.get("subtitle", "")
+    )
+    audience = draft.get("audience") or "everyone"
+    write_comment_permissions = draft.get("write_comment_permissions") or "everyone"
+    draft_section_id = (
+        draft.get("draft_section_id")
+        if "draft_section_id" in draft
+        else draft.get("section_id")
+    )
+    slug = draft.get("slug") or ""
+    updated_at = draft.get("draft_updated_at") or draft.get("updated_at")
+
+    raw_body = draft.get("draft_body")
+    if isinstance(raw_body, str):
+        try:
+            body_obj = json.loads(raw_body)
+        except Exception:
+            body_obj = raw_body
+    else:
+        body_obj = raw_body
+
+    if isinstance(body_obj, (dict, list)):
+        body_canonical = json.dumps(
+            body_obj, ensure_ascii=False, separators=(",", ":"), sort_keys=True
+        )
+    else:
+        body_canonical = str(body_obj or "")
+
+    body_hash = hashlib.sha256(body_canonical.encode("utf-8")).hexdigest()
+
+    fingerprint_components = {
+        "draft_id": draft_id,
+        "body_hash": body_hash,
+        "title": title or "",
+        "subtitle": subtitle or "",
+        "audience": audience,
+        "write_comment_permissions": write_comment_permissions,
+        "draft_section_id": draft_section_id,
+        "slug": slug,
+    }
+    fingerprint_bytes = json.dumps(
+        fingerprint_components,
+        ensure_ascii=False,
+        separators=(",", ":"),
+        sort_keys=True,
+    ).encode("utf-8")
+    revision_hash = hashlib.sha256(fingerprint_bytes).hexdigest()
+
+    return {
+        "version": 1,
+        "draft_id": draft_id,
+        "revision": revision_hash,
+        "body_hash": body_hash,
+        "title": title or "",
+        "subtitle": subtitle or "",
+        "audience": audience,
+        "write_comment_permissions": write_comment_permissions,
+        "draft_section_id": draft_section_id,
+        "slug": slug,
+        "updated_at": str(updated_at) if updated_at else None,
+    }
+
+
+def format_revision_marker(revision_info: Dict[str, Any]) -> str:
+    """Format revision metadata as a versioned HTML comment marker."""
+    payload = json.dumps(
+        revision_info, ensure_ascii=False, separators=(",", ":"), sort_keys=True
+    ).encode("utf-8")
+    encoded = base64.urlsafe_b64encode(payload).decode("ascii").rstrip("=")
+    return f"<!-- python-substack-revision:v1 {encoded} -->"
+
+
+def parse_revision_marker(markdown: str) -> Optional[Dict[str, Any]]:
+    """
+    Parse a python-substack-revision:v1 comment marker from markdown content.
+
+    Only top-level HTML comment blocks are considered; comments inside code blocks
+    are ignored.
+
+    Returns the parsed revision dictionary, or None if no marker is found.
+    Raises ValueError if an attempted marker is corrupt, malformed, unsupported, or duplicated.
+    """
+    md = MarkdownIt()
+    tokens = md.parse(markdown)
+
+    found_markers = []
+    marker_pattern = re.compile(
+        r"^<!--\s*python-substack-revision:v([0-9]+)\s+([A-Za-z0-9_-]+=*)\s*-->$"
+    )
+
+    for token in tokens:
+        if token.type == "html_block":
+            clean = token.content.strip()
+            match = marker_pattern.match(clean)
+            if match:
+                found_markers.append(match.groups())
+            elif "python-substack-revision:" in clean:
+                raise ValueError(
+                    "Malformed revision marker: corrupt comment format or invalid characters"
+                )
+
+    if not found_markers:
+        return None
+
+    if len(found_markers) > 1:
+        raise ValueError("Malformed revision marker: multiple revision markers found")
+
+    version_str, encoded = found_markers[0]
+    if version_str != "1":
+        raise ValueError(
+            f"Malformed revision marker: unsupported version '{version_str}'"
+        )
+
+    pad = len(encoded) % 4
+    if pad:
+        encoded += "=" * (4 - pad)
+
+    try:
+        raw = base64.urlsafe_b64decode(encoded.encode("ascii"))
+    except Exception as exc:
+        raise ValueError("Malformed revision marker: invalid base64 encoding") from exc
+
+    try:
+        data = json.loads(raw.decode("utf-8"))
+    except Exception as exc:
+        raise ValueError("Malformed revision marker: invalid JSON payload") from exc
+
+    if not isinstance(data, dict):
+        raise ValueError("Malformed revision marker: payload must be a JSON object")
+
+    if not data.get("revision") or not isinstance(data.get("revision"), str):
+        raise ValueError(
+            "Malformed revision marker: missing or empty required 'revision' field"
+        )
+
+    return data
+
+
+def compare_draft_revisions(
+    expected: Dict[str, Any], current: Dict[str, Any]
+) -> List[str]:
+    """
+    Compare expected revision metadata with current remote draft revision metadata.
+
+    Returns a list of human-readable, actionable mismatch descriptions.
+    If the list is empty, there is no conflict.
+    """
+    mismatches: List[str] = []
+
+    if (
+        expected.get("draft_id") is not None
+        and current.get("draft_id") is not None
+        and str(expected.get("draft_id")) != str(current.get("draft_id"))
+    ):
+        mismatches.append(
+            f"Draft ID mismatch: expected {expected.get('draft_id')}, got {current.get('draft_id')}"
+        )
+
+    if (
+        expected.get("body_hash")
+        and current.get("body_hash")
+        and expected.get("body_hash") != current.get("body_hash")
+    ):
+        mismatches.append("Remote draft body has changed since export")
+
+    if (
+        expected.get("title") is not None
+        and current.get("title") is not None
+        and expected.get("title") != current.get("title")
+    ):
+        mismatches.append(
+            f"Remote title changed: expected '{expected.get('title')}', got '{current.get('title')}'"
+        )
+
+    if (
+        expected.get("subtitle") is not None
+        and current.get("subtitle") is not None
+        and expected.get("subtitle") != current.get("subtitle")
+    ):
+        mismatches.append(
+            f"Remote subtitle changed: expected '{expected.get('subtitle')}', got '{current.get('subtitle')}'"
+        )
+
+    if (
+        expected.get("audience")
+        and current.get("audience")
+        and expected.get("audience") != current.get("audience")
+    ):
+        mismatches.append(
+            f"Remote audience changed: expected '{expected.get('audience')}', got '{current.get('audience')}'"
+        )
+
+    if (
+        expected.get("write_comment_permissions")
+        and current.get("write_comment_permissions")
+        and expected.get("write_comment_permissions")
+        != current.get("write_comment_permissions")
+    ):
+        mismatches.append(
+            f"Remote write_comment_permissions changed: expected '{expected.get('write_comment_permissions')}', got '{current.get('write_comment_permissions')}'"
+        )
+
+    if expected.get("draft_section_id") != current.get("draft_section_id"):
+        mismatches.append(
+            f"Remote section changed: expected {expected.get('draft_section_id')}, got {current.get('draft_section_id')}"
+        )
+
+    if (
+        expected.get("slug") is not None
+        and current.get("slug") is not None
+        and expected.get("slug") != current.get("slug")
+    ):
+        mismatches.append(
+            f"Remote slug changed: expected '{expected.get('slug')}', got '{current.get('slug')}'"
+        )
+
+    if (
+        expected.get("updated_at")
+        and current.get("updated_at")
+        and expected.get("updated_at") != current.get("updated_at")
+    ):
+        mismatches.append(
+            f"Remote update timestamp changed: expected '{expected.get('updated_at')}', got '{current.get('updated_at')}'"
+        )
+
+    if (
+        expected.get("revision")
+        and current.get("revision")
+        and expected.get("revision") != current.get("revision")
+        and not mismatches
+    ):
+        mismatches.append(
+            f"Remote revision fingerprint mismatch: expected '{expected.get('revision')}', got '{current.get('revision')}'"
+        )
+
+    return mismatches

python_substack-0.9.0.dist-info/RECORD

@@ -1,14 +0,0 @@
-substack/__init__.py,sha256=W0VG-klGuBHRwwQxQWEdvxB68z6YVQMvEAWO3yNn8bY,449
-substack/api.py,sha256=k6ympBEJnwE3Gy0n2qGYTM4d26As1--SZTgZQWl7PzU,32176
-substack/cli.py,sha256=56BTWxfr3gpAaJOLJsKRG7k6PPT7xSgLdp632H4mezA,26292
-substack/exceptions.py,sha256=Y61XSPyxDxXPbVlioFvKhb94MRY0tpD389F5YdL1rGM,1390
-substack/mdexport.py,sha256=lg2DCTHWRa_w7O2eO6ks1Iif2A7_tphDIayI0w_yxKk,14037
-substack/mdrender.py,sha256=Bq0VXs0B3cC2fpKzyRNxApM-ZbK_-pC9wPvn1HIanHw,13666
-substack/nodes.py,sha256=fTsGO0-lTztcXiloIjXrHVnJes9EcltGcrX-mEV2ceQ,5004
-substack/post.py,sha256=qDXu-xzO3nRXtahc-yG2EhxKAXB2hG_Z1nLa55UMBGg,19697
-substack_mcp/mcp_server.py,sha256=M5XH3C4iWjzvCw3uOPbY2NFljTQAl8FLt14RKaTzka0,11324
-python_substack-0.9.0.dist-info/METADATA,sha256=1S7eMKYmbI8AMKG5rruRyRcUWESxELT6XStsQQeRCsY,9299
-python_substack-0.9.0.dist-info/WHEEL,sha256=kJCRJT_g0adfAJzTx2GUMmS80rTJIVHRCfG0DQgLq3o,88
-python_substack-0.9.0.dist-info/entry_points.txt,sha256=MKPjaBUd-0PtvxsBviStsVq1c0h8JZ_qUoYEsBK1xJc,236
-python_substack-0.9.0.dist-info/licenses/LICENSE,sha256=L6jk148I5HhhVbfUvkO3EO7eAoU5zToLio4-ApkCkxg,1062
-python_substack-0.9.0.dist-info/RECORD,,