feat(notion-writer): markdown endpoint helpers + version-aware client

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

custom-skills/32-notion-writer/code/scripts/_notion_compat.py

@@ -16,8 +16,11 @@ from notion_client import Client
 from notion_client.errors import APIErrorCode, APIResponseError
 
 
-def make_client(api_key: str) -> Client:
-    """Build a sync Notion client on the SDK default API version (2025-09-03+)."""
+def make_client(api_key: str, notion_version: str = None) -> Client:
+    """Build a sync Notion client. Pass notion_version to override the SDK
+    default (needed: 2026-03-11 for the markdown content endpoints)."""
+    if notion_version:
+        return Client(auth=api_key, notion_version=notion_version)
     return Client(auth=api_key)
 
 
@@ -210,7 +213,10 @@ def explain_api_error(exc: APIResponseError, context: str = "") -> str:
             "https://www.notion.so/my-integrations."
         )
     if code == APIErrorCode.ValidationError:
-        return f"Validation error{suffix}: {exc.body.get('message', str(exc))}"
+        msg = exc.body.get('message', str(exc))
+        if 'delet' in msg.lower():
+            msg += " — re-run with --allow-deleting-content to permit this."
+        return f"Validation error{suffix}: {msg}"
     if code == APIErrorCode.RateLimited:
         return f"Rate limited{suffix}. Back off and retry."
     return f"Notion API error [{code}]{suffix}: {exc}"
@@ -253,3 +259,31 @@ def find_existing_page(
     )
     results = response.get("results") or []
     return results[0] if results else None
+
+
+def create_page_markdown(client, parent, properties, markdown):
+    """POST /v1/pages with the enhanced-markdown body param."""
+    return client.request(
+        path="pages", method="POST",
+        body={"parent": parent, "properties": properties, "markdown": markdown},
+    )
+
+
+def append_markdown(client, page_id, markdown):
+    """PATCH /v1/pages/:id/markdown — append at end (insert_content)."""
+    return client.request(
+        path=f"pages/{page_id}/markdown", method="PATCH",
+        body={"type": "insert_content",
+              "insert_content": {"content": markdown,
+                                 "position": {"type": "end"}}},
+    )
+
+
+def replace_markdown(client, page_id, markdown, allow_deleting=False):
+    """PATCH /v1/pages/:id/markdown — replace all content."""
+    return client.request(
+        path=f"pages/{page_id}/markdown", method="PATCH",
+        body={"type": "replace_content",
+              "replace_content": {"new_str": markdown,
+                                  "allow_deleting_content": allow_deleting}},
+    )