athena-python-docx 0.2.3__tar.gz → 0.4.0__tar.gz

{athena_python_docx-0.2.3 → athena_python_docx-0.4.0}/CLAUDE.md

@@ -35,6 +35,18 @@ These standard python-docx members don't apply to a Superdoc-backed SDK:
 - `Document.settings` — Word app settings (not surfaced by Superdoc)
 - `InlineShape.chart` — charts (Phase 2+)
 
+### Intentional deviations (additions / different semantics)
+
+These differ from stock python-docx because the SDK is asset-backed,
+not file-backed. Each is documented in the relevant docstring.
+
+- **`Document.create(name=, base_url=, api_key=, parent_folder_id=, workspace_id=)`**
+  classmethod. Stock python-docx returns a blank in-memory document
+  for `Document(None)`; we can't fabricate a SuperDocument asset
+  client-side, so net-new asset creation is a separate factory that
+  hits `POST {base_url}/docs/empty`. The constructor positional-arg
+  shape (`Document(asset_id)`) is preserved for parity.
+
 ### If you need a deviation
 
 If there is a genuine technical reason why a deviation from python-docx is necessary:

{athena_python_docx-0.2.3 → athena_python_docx-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: athena-python-docx
-Version: 0.2.3
+Version: 0.4.0
 Summary: Drop-in replacement for python-docx that connects to Athena's Superdoc/Keryx collaborative document stack
 Project-URL: Homepage, https://athenaintelligence.ai
 Author-email: Athena Intelligence <engineering@athenaintelligence.ai>

{athena_python_docx-0.2.3 → athena_python_docx-0.4.0}/docx/__init__.py

@@ -6,7 +6,7 @@ See CLAUDE.md for the API parity contract.
 
 from __future__ import annotations
 
-__version__ = "0.2.3"
+__version__ = "0.4.0"
 
 from docx.api import Document
 # Re-exports python-docx ships at docx top-level for convenience.

athena_python_docx-0.4.0/docx/_http.py

@@ -0,0 +1,189 @@
+"""HTTP bootstrap for Document.create().
+
+The SDK's primary transport is y-websocket via Superdoc; this module is
+the *only* HTTP client in the package. It exists solely so that
+``Document.create()`` can hit ``POST /docs/empty`` on docx-studio to
+provision a new SuperDocument asset and receive a collab bundle to open
+the document with.
+
+We use ``urllib`` from stdlib to avoid pulling ``httpx`` / ``requests``
+into the runtime — this code runs in Daytona sandboxes where every MB
+matters, and the existing SDK already keeps its dep tree tight.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.request
+from typing import TypedDict
+
+from docx.errors import (
+    AuthenticationError,
+    DocxError,
+    SessionError,
+)
+
+
+class _CollabBundle(TypedDict):
+    """The collab credentials returned alongside a freshly-created asset.
+
+    Note: env-var-shape (matches what ``Session`` reads), even though
+    the wire format from docx-studio uses different key names. The
+    keys are renamed at parse time.
+    """
+
+    SUPERDOC_COLLAB_TOKEN: str
+    KERYX_WS_URL: str
+    ATHENA_WORKSPACE_ID: str
+
+
+class CreateAssetResult(TypedDict):
+    """Parsed response from ``POST /docs/empty``."""
+
+    asset_id: str
+    name: str
+    workspace_id: str
+    collab: _CollabBundle
+
+
+_BASE_URL_ENV = "ATHENA_DOCX_BASE_URL"
+_API_KEY_ENV = "ATHENA_DOCX_API_KEY"  # noqa: S105
+
+
+def create_empty_document(
+    *,
+    base_url: str | None = None,
+    api_key: str | None = None,
+    name: str | None = None,
+    parent_folder_id: str | None = None,
+    workspace_id: str | None = None,
+    timeout: float = 30.0,
+) -> CreateAssetResult:
+    """Call ``POST {base_url}/docs/empty`` and parse the response.
+
+    Args:
+        base_url: docx-studio API base, e.g. ``https://docx-studio.stg.athenaintel.com``.
+            Falls back to ``$ATHENA_DOCX_BASE_URL``.
+        api_key: Athena API key (PropelAuth user API key) or PropelAuth
+            access token. Sent as ``Authorization: Bearer <api_key>``.
+            Falls back to ``$ATHENA_DOCX_API_KEY``.
+        name: Optional display title.
+        parent_folder_id: Optional parent folder; defaults to workspace root.
+        workspace_id: Optional workspace UUID; defaults to caller's
+            current workspace.
+        timeout: Request timeout in seconds.
+
+    Returns:
+        Parsed response dict with the new asset_id and a collab bundle
+        ready to feed into ``Session(..., bundle=...)``.
+
+    Raises:
+        SessionError: missing base_url or unparseable response.
+        AuthenticationError: missing api_key, or the server returned 401/403.
+        DocxError: any other 4xx/5xx from the server.
+    """
+    resolved_base: str | None = base_url or os.environ.get(_BASE_URL_ENV)
+    resolved_key: str | None = api_key or os.environ.get(_API_KEY_ENV)
+
+    if not resolved_base:
+        raise SessionError(
+            f"Missing base_url and {_BASE_URL_ENV} env var. "
+            "Pass base_url= to Document.create() or set the env var.",
+        )
+    if not resolved_key:
+        raise AuthenticationError(
+            f"Missing api_key and {_API_KEY_ENV} env var. "
+            "Pass api_key= to Document.create() or set the env var.",
+        )
+
+    url: str = resolved_base.rstrip("/") + "/docs/empty"
+    body: dict[str, str] = {}
+    if name is not None:
+        body["name"] = name
+    if parent_folder_id is not None:
+        body["parentFolderId"] = parent_folder_id
+    if workspace_id is not None:
+        body["workspaceId"] = workspace_id
+
+    # Lazy import — _http is loaded lazily by Document.create(), so the
+    # package is fully initialized by the time we reach this code.
+    from docx import __version__
+
+    payload: bytes = json.dumps(body).encode("utf-8")
+    req = urllib.request.Request(  # noqa: S310
+        url,
+        data=payload,
+        method="POST",
+        headers={
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {resolved_key}",
+            "Accept": "application/json",
+            "User-Agent": f"athena-python-docx/{__version__}",
+        },
+    )
+
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:  # noqa: S310
+            raw: bytes = resp.read()
+    except urllib.error.HTTPError as e:
+        err_body: str = ""
+        try:
+            err_body = e.read().decode("utf-8", errors="replace")
+        except Exception:  # noqa: BLE001
+            pass
+        if e.code in (401, 403):
+            raise AuthenticationError(
+                f"docx-studio rejected the API key (HTTP {e.code}): {err_body}",
+            ) from e
+        raise DocxError(
+            f"docx-studio /docs/empty returned HTTP {e.code}: {err_body}",
+        ) from e
+    except urllib.error.URLError as e:
+        raise SessionError(
+            f"Unable to reach docx-studio at {url}: {e.reason}",
+        ) from e
+
+    try:
+        parsed: dict = json.loads(raw.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as e:
+        raise SessionError(
+            f"docx-studio returned non-JSON response: {raw[:200]!r}",
+        ) from e
+
+    asset_id_obj = parsed.get("assetId")
+    name_obj = parsed.get("name")
+    ws_obj = parsed.get("workspaceId")
+    collab_obj = parsed.get("collab")
+    if not (
+        isinstance(asset_id_obj, str)
+        and isinstance(name_obj, str)
+        and isinstance(ws_obj, str)
+        and isinstance(collab_obj, dict)
+    ):
+        raise SessionError(
+            f"docx-studio response is missing required fields: {parsed!r}",
+        )
+    token_obj = collab_obj.get("token")
+    ws_url_obj = collab_obj.get("wsUrl")
+    bundle_ws_obj = collab_obj.get("workspaceId")
+    if not (
+        isinstance(token_obj, str)
+        and isinstance(ws_url_obj, str)
+        and isinstance(bundle_ws_obj, str)
+    ):
+        raise SessionError(
+            f"docx-studio collab bundle is malformed: {collab_obj!r}",
+        )
+
+    return CreateAssetResult(
+        asset_id=asset_id_obj,
+        name=name_obj,
+        workspace_id=ws_obj,
+        collab=_CollabBundle(
+            SUPERDOC_COLLAB_TOKEN=token_obj,
+            KERYX_WS_URL=ws_url_obj,
+            ATHENA_WORKSPACE_ID=bundle_ws_obj,
+        ),
+    )

athena_python_docx-0.4.0/docx/_http_doc.py

@@ -0,0 +1,181 @@
+"""HTTP-backed Superdoc document handle.
+
+This is the core of the ``transport="http"`` path. It mirrors the
+shape of the bound doc API that ``superdoc-sdk`` exposes — every
+existing SDK call site uses ``self._session.doc.<dotted.path>(params)``,
+and ``HttpDocHandle`` matches that shape via a lazy attribute walker.
+
+When the user calls ``doc.create.paragraph({...})`` the path proxy
+accumulates the dotted name and the terminal ``__call__`` POSTs a
+single-command request to docx-studio's ``POST /docs/:id/commands``,
+unpacks the dispatcher's ``applied[0].result``, and returns it. The
+existing SDK code expects a Python dict back, which the server returns
+verbatim from Superdoc.
+
+The HTTP path is a 1:1 substitute for the embedded Superdoc CLI; no
+SDK call site has to change to opt in.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from typing import Any
+
+from docx.errors import (
+    AuthenticationError,
+    DocxError,
+    SessionError,
+)
+
+
+def _user_agent() -> str:
+    # Lazy import — docx/__init__.py imports api.py at package load, but
+    # _http_doc is only imported lazily from client.py at session-open
+    # time, so the package is fully initialized by the time this runs.
+    from docx import __version__
+
+    return f"athena-python-docx/{__version__}"
+
+
+def _http_post_json(
+    *,
+    url: str,
+    api_key: str,
+    body: dict,
+    timeout: float = 60.0,
+) -> dict:
+    """POST JSON, parse JSON, raise typed errors on non-2xx."""
+    payload: bytes = json.dumps(body).encode("utf-8")
+    req = urllib.request.Request(  # noqa: S310
+        url,
+        data=payload,
+        method="POST",
+        headers={
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {api_key}",
+            "Accept": "application/json",
+            "User-Agent": _user_agent(),
+        },
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:  # noqa: S310
+            raw: bytes = resp.read()
+            return json.loads(raw.decode("utf-8"))
+    except urllib.error.HTTPError as e:
+        err_body: str = ""
+        try:
+            err_body = e.read().decode("utf-8", errors="replace")
+        except Exception:  # noqa: BLE001
+            pass
+        if e.code in (401, 403):
+            raise AuthenticationError(
+                f"docx-studio rejected the request (HTTP {e.code}): {err_body}",
+            ) from e
+        if e.code == 207:
+            # Partial-success — caller may want to inspect. Re-raise as
+            # DocxError but parse the body so they can see what failed.
+            try:
+                parsed = json.loads(err_body) if err_body else {}
+            except json.JSONDecodeError:
+                parsed = {"raw": err_body}
+            raise DocxError(
+                f"docx-studio batch reported a partial failure: {parsed!r}",
+            ) from e
+        raise DocxError(
+            f"docx-studio returned HTTP {e.code}: {err_body}",
+        ) from e
+    except urllib.error.URLError as e:
+        raise SessionError(
+            f"Unable to reach docx-studio at {url}: {e.reason}",
+        ) from e
+
+
+class HttpClient:
+    """Owns the HTTP transport for a Document.
+
+    Stateless wrt batching today — every SDK primitive maps to one
+    POST /commands with a single-element commands array. Future:
+    add a batch buffer that flushes on `with doc.batch():` exit.
+    """
+
+    def __init__(self, *, base_url: str, api_key: str) -> None:
+        self._base_url: str = base_url.rstrip("/")
+        self._api_key: str = api_key
+
+    def execute(self, asset_id: str, op: str, params: dict) -> Any:
+        """Send one command to /docs/:id/commands and return its result."""
+        url: str = f"{self._base_url}/docs/{asset_id}/commands"
+        body: dict = {
+            "commands": [{"op": op, "params": params}],
+            "return": {"snapshot": False},
+        }
+        resp: dict = _http_post_json(url=url, api_key=self._api_key, body=body)
+        applied = resp.get("applied")
+        if not isinstance(applied, list) or not applied:
+            err = resp.get("error")
+            if err:
+                raise DocxError(
+                    f"docx-studio command {op!r} failed: {err!r}",
+                )
+            raise DocxError(
+                f"docx-studio returned no applied entry for {op!r}: {resp!r}",
+            )
+        result = applied[0].get("result")
+        return result if isinstance(result, dict) else {}
+
+
+class _PathProxy:
+    """Lazy attribute walker — turns ``doc.create.paragraph(p)`` into
+    ``client.execute(asset_id, "create.paragraph", p)``.
+
+    The Python SDK's call sites use snake_case dotted paths
+    (e.g. ``doc.format.paragraph.set_alignment``) which match the
+    Python ``superdoc-sdk`` Bound API. The server-side dispatcher
+    converts to camelCase before resolving on the npm SDK's bound API,
+    so the wire op-name stays in snake_case and clients across
+    languages can share it.
+    """
+
+    __slots__ = ("_client", "_asset_id", "_path")
+
+    def __init__(self, client: HttpClient, asset_id: str, path: str) -> None:
+        self._client: HttpClient = client
+        self._asset_id: str = asset_id
+        self._path: str = path
+
+    def __getattr__(self, name: str) -> "_PathProxy":
+        # Block Python special names so iteration / hash / etc. don't
+        # silently deepen the path.
+        if name.startswith("__"):
+            raise AttributeError(name)
+        new_path: str = f"{self._path}.{name}" if self._path else name
+        return _PathProxy(self._client, self._asset_id, new_path)
+
+    async def __call__(self, params: dict | None = None) -> Any:
+        # The existing SDK is async-style (calls go through run_sync);
+        # __call__ is async to match. _http_post_json is blocking under
+        # the hood, but run_sync runs us on a persistent event-loop
+        # thread, so blocking HTTP is fine — it doesn't starve the
+        # main thread.
+        return self._client.execute(self._asset_id, self._path, params or {})
+
+
+class HttpDocHandle:
+    """Drop-in replacement for ``superdoc.AsyncSuperDocClient.open()``'s
+    return value. Existing SDK call sites use ``self._session.doc.<X>(p)``
+    where ``X`` is a dotted path on the bound doc API; this object
+    forwards every such access to the HTTP transport via _PathProxy.
+    """
+
+    __slots__ = ("_client", "_asset_id")
+
+    def __init__(self, client: HttpClient, asset_id: str) -> None:
+        self._client: HttpClient = client
+        self._asset_id: str = asset_id
+
+    def __getattr__(self, name: str) -> _PathProxy:
+        if name.startswith("__"):
+            raise AttributeError(name)
+        return _PathProxy(self._client, self._asset_id, name)

athena_python_docx-0.4.0/docx/api.py

@@ -0,0 +1,84 @@
+"""The `Document` factory — matches python-docx's `docx.Document(path)`.
+
+python-docx signature:
+    Document(docx=None) -> Document
+
+Our signature deviates from the path-based one because we don't open
+.docx files from disk — we open Y.Doc assets from Keryx. The parameter
+is reused: you pass an asset_id string where python-docx would take a
+file path.
+
+For net-new asset creation, use the classmethod ``Document.create()``
+(see ``docx.document``). Stock python-docx returns a blank document
+when ``Document(None)`` is called, but our SDK can't fabricate a
+SuperDocument asset out of thin air — there's an Athena-side asset
+write that has to happen first. ``Document.create()`` handles that via
+``POST /docs/empty`` on docx-studio.
+"""
+
+from __future__ import annotations
+
+from docx.document import Document as _Document
+
+
+def Document(
+    docx: str | None = None,
+    *,
+    transport: str = "http",
+    base_url: str | None = None,
+    api_key: str | None = None,
+) -> _Document:
+    """Open a Word document for editing.
+
+    Args:
+        docx: Athena asset_id of the SuperDoc document to open.
+              In python-docx this takes a file path; here it takes
+              an asset_id. To create a NEW document instead of opening
+              an existing one, call ``Document.create(...)`` (a
+              classmethod on the Document class).
+        transport: Either ``"http"`` (default since 0.4.0 — every
+              primitive routes through docx-studio's
+              ``POST /docs/:id/commands``; pure-Python client, no
+              embedded binary) or ``"direct"`` (legacy — embedded
+              Superdoc CLI talks to Keryx via y-websocket; requires
+              ``SUPERDOC_COLLAB_TOKEN`` env vars; emits a
+              ``DeprecationWarning`` and will be removed in 1.0).
+              The ``http`` transport requires ``base_url`` +
+              ``api_key`` (or the ``ATHENA_DOCX_*`` env vars).
+        base_url: docx-studio API base for ``transport="http"``. Falls
+              back to ``$ATHENA_DOCX_BASE_URL``.
+        api_key: Athena API key / PropelAuth bearer for
+              ``transport="http"``. Falls back to ``$ATHENA_DOCX_API_KEY``.
+
+    Returns:
+        A Document instance bound to the asset.
+
+    Raises:
+        ValueError: if ``docx`` is None or empty. Use ``Document.create()``
+            to make a fresh asset.
+    """
+    if not docx:
+        raise ValueError(
+            "athena-python-docx requires an asset_id. "
+            "Pass the SuperDoc asset ID as the first argument: "
+            "Document('asset_xxx...'). "
+            "To create a brand-new document, call "
+            "Document.create(name=..., base_url=..., api_key=...).",
+        )
+    return _Document(
+        asset_id=docx,
+        transport=transport,
+        http_base_url=base_url,
+        http_api_key=api_key,
+    )
+
+
+# Re-export the classmethod factories at module level so callers can
+# write either:
+#     from docx import Document
+#     Document.create(name=...)
+# or:
+#     from docx.api import Document
+#     Document.create(name=...)
+# (matching python-docx's flat API surface.)
+Document.create = _Document.create  # type: ignore[attr-defined]

{athena_python_docx-0.2.3 → athena_python_docx-0.4.0}/docx/client.py

@@ -64,12 +64,28 @@ class Session:
         *,
         asset_id: str,
         user_info: dict[str, str] | None = None,
+        bundle: dict[str, str] | None = None,
+        transport: str = "direct",
+        http_base_url: str | None = None,
+        http_api_key: str | None = None,
     ) -> None:
         self._asset_id: str = asset_id
         self._user_info: dict[str, str] = user_info or {
             "name": "Athena Agent",
             "email": "agent@athenaintel.com",
         }
+        # Optional pre-minted collab bundle. When set, open() uses these
+        # values instead of reading from os.environ. Used by Document.create()
+        # so the freshly-minted Keryx JWT returned from the create API is
+        # consumed directly without a round-trip through env vars.
+        self._bundle: dict[str, str] | None = bundle
+        # Transport: "direct" → embedded superdoc-sdk talks Keryx directly
+        # (legacy path, requires SUPERDOC_COLLAB_TOKEN env vars).
+        #              "http"   → all primitives go through docx-studio's
+        # POST /docs/:id/commands; no embedded Superdoc, no Keryx WS in-process.
+        self._transport: str = transport
+        self._http_base_url: str | None = http_base_url
+        self._http_api_key: str | None = http_api_key
         self._client: Any | None = None
         self._doc_handle: Any | None = None
         self._opened: bool = False
@@ -84,10 +100,19 @@ class Session:
         return self._opened and not self._closed
 
     async def open(self) -> None:
-        """Open the Superdoc SDK session against Keryx.
+        """Open a session against the configured transport.
+
+        For ``transport="http"`` this is a near no-op — we just construct
+        the HTTP doc handle. The first command-level call hits docx-studio,
+        which performs the ownership check and acquires the Superdoc
+        session server-side.
+
+        For ``transport="direct"`` (legacy) this opens an embedded
+        Superdoc session and y-websocket to Keryx. Requires the
+        ``SUPERDOC_COLLAB_TOKEN`` env var (or a pre-minted bundle).
 
         Raises:
-            AuthenticationError: if SUPERDOC_COLLAB_TOKEN is missing/invalid.
+            AuthenticationError: if creds are missing/invalid.
             SessionError: on any other open-time failure.
         """
         if self._closed:
@@ -97,9 +122,57 @@ class Session:
         if self._opened:
             return
 
-        token: str | None = os.environ.get(_TOKEN_ENV)
-        ws_url: str | None = os.environ.get(_WS_URL_ENV)
-        workspace_id: str | None = os.environ.get(_WORKSPACE_ENV)
+        if self._transport == "direct":
+            import warnings
+
+            warnings.warn(
+                "transport='direct' is deprecated and will be removed in "
+                "athena-python-docx 1.0. Pass transport='http' (the new "
+                "default) or remove the argument. The HTTP transport is "
+                "pure-Python, has no embedded Superdoc binary, and works "
+                "without the SUPERDOC_COLLAB_TOKEN env-var dance.",
+                DeprecationWarning,
+                stacklevel=3,
+            )
+        elif self._transport == "http":
+            from docx._http_doc import HttpClient, HttpDocHandle
+
+            base_url: str | None = self._http_base_url or os.environ.get(
+                "ATHENA_DOCX_BASE_URL",
+            )
+            api_key: str | None = self._http_api_key or os.environ.get(
+                "ATHENA_DOCX_API_KEY",
+            )
+            if not base_url:
+                raise SessionError(
+                    "Missing base_url for HTTP transport. Pass base_url= "
+                    "to Document(...) or set ATHENA_DOCX_BASE_URL.",
+                )
+            if not api_key:
+                raise AuthenticationError(
+                    "Missing api_key for HTTP transport. Pass api_key= "
+                    "to Document(...) or set ATHENA_DOCX_API_KEY.",
+                )
+            client = HttpClient(base_url=base_url, api_key=api_key)
+            self._client = client
+            self._doc_handle = HttpDocHandle(client, self._asset_id)
+            self._opened = True
+            _log_info(f"Opened {self._asset_id} (http)")
+            return
+
+        # ----- legacy direct transport -----
+
+        # Prefer the in-memory bundle over env vars when present — that
+        # path is taken by Document.create(), which receives a fresh
+        # bundle in the create-asset HTTP response.
+        if self._bundle is not None:
+            token = self._bundle.get(_TOKEN_ENV)
+            ws_url = self._bundle.get(_WS_URL_ENV)
+            workspace_id = self._bundle.get(_WORKSPACE_ENV)
+        else:
+            token = os.environ.get(_TOKEN_ENV)
+            ws_url = os.environ.get(_WS_URL_ENV)
+            workspace_id = os.environ.get(_WORKSPACE_ENV)
 
         if not token:
             raise AuthenticationError(
@@ -173,33 +246,38 @@ class Session:
         return self._doc_handle
 
     async def save(self, *, in_place: bool = True) -> None:  # noqa: ARG002
-        """Ensure pending mutations have flushed to Keryx.
+        """Ensure pending mutations have flushed.
 
-        In collab mode (our only mode), the Y-Websocket provider streams
-        updates to Keryx as they happen — there's no explicit save RPC
-        to call. The underlying Superdoc SDK's ``save({"inPlace": True})``
-        targets file-backed docs and errors with "this session has no
-        source path" for collab sessions. So save() is a thin flush:
-        sleep briefly so in-flight WebSocket frames land, then return.
+        For ``transport="http"`` this is a true no-op — every primitive
+        was a synchronous HTTP round-trip that the server already
+        committed to Keryx before responding.
 
-        The ``in_place`` kwarg is accepted for python-docx parity but
-        has no effect in collab mode (there is no alternate target).
+        For ``transport="direct"`` we sleep briefly to let in-flight
+        y-websocket frames land before close, matching the legacy
+        superdoc_write_utils.py 1-second pre-close delay.
         """
         if not self._opened:
             raise SessionError("Cannot save a session that was never opened.")
         if self._closed:
             raise DocumentClosedError(f"Session {self._asset_id} is closed.")
 
-        # Short flush — matches superdoc_write_utils.py's 1-second pre-close
-        # delay. Keeps a single in-flight frame from being dropped on close.
+        if self._transport == "http":
+            _log_info(f"Saved (no-op for http transport) {self._asset_id}")
+            return
+
         await asyncio.sleep(1)
         _log_info(f"Saved (flushed) {self._asset_id}")
 
     async def close(self) -> None:
-        """Close the Superdoc session. Idempotent."""
+        """Close the session. Idempotent."""
         if self._closed:
             return
 
+        if self._transport == "http":
+            self._closed = True
+            _log_info(f"Closed {self._asset_id} (http)")
+            return
+
         if self._opened and self._doc_handle is not None:
             try:
                 # Match the 1-second flush delay from superdoc_write_utils