Merge branch 'refs/heads/claude/raw-response-8e1bbd' into feat/sdk-parity

# Conflicts:
#	CHANGELOG.md
#	docs/reference/clients.md

Author: shrijayan

CHANGELOG.md

@@ -16,6 +16,10 @@ Releases are published automatically on every merge to `main`. Release notes for
 - `OPENCODE_LOG=debug|info` sends the `opencode` logger to stderr at that level.
 - `DefaultAioHttpClient`: an optional aiohttp transport for `AsyncOpencode`, installed with the `aiohttp` extra
   (`pip install 'opencode-python-sdk[aiohttp]'`) and passed as `http_client=`.
+- `.with_raw_response` and `.with_streaming_response` on every resource (sync and async): return an
+  `APIResponse` / `AsyncAPIResponse` with `headers`, `status_code`, `http_response`, `request`, `text`, `json()`,
+  `iter_bytes()` / `iter_lines()` and `parse()` for the usual typed value.
+- `client.get` / `post` / `put` / `patch` / `delete` for endpoints the client has no method for.
 
 ## 0.1.0
 

README.md

@@ -453,6 +453,61 @@ Logs go to the `opencode` logger. `logging.getLogger("opencode").setLevel(loggin
 retry; credentials are never logged. Set `OPENCODE_LOG=debug` (or `info`) to have the SDK attach a stderr handler at
 that level on import, without touching your own logging config.
 
+### Accessing raw response data
+
+Prefix any method with `.with_raw_response` to get the HTTP response (headers, status, request) instead of the
+parsed value. `.parse()` returns what the plain call would have returned:
+
+```python
+response = client.session.with_raw_response.get("ses_...")
+print(response.status_code, response.headers.get("content-type"))
+session = response.parse()  # SessionInfo
+```
+
+`.with_raw_response` reads the body before returning. `.with_streaming_response` does not: it is a context manager
+that sends the request on entry and closes the connection on exit, so you can read large bodies incrementally with
+`iter_bytes()`, `iter_text()` or `iter_lines()`, or still call `parse()`:
+
+```python
+with client.file.with_streaming_response.read("big.log") as response:
+    for line in response.iter_lines():
+        ...
+```
+
+Both exist on every resource and sub-resource of both clients (`async with` and `await response.parse()` on
+`AsyncOpencode`). `APIResponse` also has `.http_response`, `.request`, `.text`, `.json()` and `.read()`.
+
+- **List methods** give the response of the first page; `parse()` returns a `SyncCursorPage` / `AsyncCursorPage`
+  that fetches the following pages as usual.
+- **Event streams** are never read eagerly: `parse()` returns the `Stream` / `AsyncStream`, which reads events as
+  you iterate. Close the stream (or the response) when done.
+- Error statuses still raise `APIStatusError` subclasses; the response is on the exception as `error.response`.
+- Hand-written helpers such as `client.session.run()` and `client.pty.attach()` are not wrapped.
+
+### Making custom/undocumented requests
+
+Undocumented parameters go through `extra_headers`, `extra_query` and `extra_body` on every method (see above). For
+an endpoint the client has no method for, `client.get`, `post`, `put`, `patch` and `delete` send a request relative
+to `base_url` with the client's authentication, retries and typed errors, and return the decoded JSON:
+
+```python
+data = client.post("/api/new-endpoint", body={"key": "value"}, query={"directory": "/repo"})
+
+# Validate into a type, e.g. a response wrapped in {"data": ...}:
+from opencode.types import SessionInfo
+
+payload = client.get("/api/session/ses_...", cast_to=dict[str, SessionInfo])
+```
+
+### Determining the installed version
+
+```python
+import opencode
+
+print(opencode.__version__)  # this package
+print(opencode.API_VERSION)  # the OpenCode server version it was generated from
+```
+
 ## Versioning
 
 | `opencode-python-sdk` (this package) | OpenCode server |

codegen/render.py

@@ -359,7 +359,13 @@ def _render_method(operation: Operation, errors: dict[str, dict[str, Any]], *, i
             "        )",
         ]
     elif operation.kind == "void":
-        lines += [f"        {awaiting}self._client.request(", *request_options, '            kind="void",', "        )"]
+        # Returned so ``with_raw_response`` can hand back the response; a plain call returns ``None``.
+        lines += [
+            f'        return cast("None", {awaiting}self._client.request(',
+            *request_options,
+            '            kind="void",',
+            "        ))",
+        ]
     elif operation.kind == "binary":
         lines += [
             f'        return cast("bytes", {awaiting}self._client.request(',
@@ -412,13 +418,67 @@ def _resource_classes(resource: Resource, errors: dict[str, dict[str, Any]], *,
             f'        """Operations under ``client.{_attr_path(child)}``."""',
             f"        return {prefix}{child.class_name}Resource(self._client)\n",
         ]
+    for kind, summary in _WRAPPERS:
+        lines += [
+            "    @cached_property",
+            f"    def {kind}(self) -> {prefix}{resource.class_name}Resource{_WRAPPER_SUFFIX[kind]}:",
+            f'        """{summary}"""',
+            f"        return {prefix}{resource.class_name}Resource{_WRAPPER_SUFFIX[kind]}(self)\n",
+        ]
     for operation in resource.operations:
         lines += _render_method(operation, errors, is_async=is_async)
         lines.append("")
     blocks.append("\n".join(lines).rstrip() + "\n")
+    for kind, _ in _WRAPPERS:
+        blocks.append(_wrapper_class(resource, kind, is_async=is_async))
     return blocks
 
 
+_WRAPPERS = (
+    (
+        "with_raw_response",
+        "Same methods, returning the raw HTTP response; call ``.parse()`` on it for the usual value.",
+    ),
+    (
+        "with_streaming_response",
+        "Same methods, returning a context manager over the HTTP response without reading the body.",
+    ),
+)
+_WRAPPER_SUFFIX = {"with_raw_response": "WithRawResponse", "with_streaming_response": "WithStreamingResponse"}
+_WRAPPER_FUNCTION = {
+    ("with_raw_response", False): "to_raw_response_wrapper",
+    ("with_streaming_response", False): "to_streamed_response_wrapper",
+    ("with_raw_response", True): "async_to_raw_response_wrapper",
+    ("with_streaming_response", True): "async_to_streamed_response_wrapper",
+}
+
+
+def _wrapper_class(resource: Resource, kind: str, *, is_async: bool) -> str:
+    prefix = "Async" if is_async else ""
+    suffix = _WRAPPER_SUFFIX[kind]
+    name = f"{prefix}{resource.class_name}Resource"
+    wrap = _WRAPPER_FUNCTION[(kind, is_async)]
+    lines = [
+        f"class {name}{suffix}:",
+        f'    """``client.{_attr_path(resource)}.{kind}``."""\n',
+        f"    def __init__(self, resource: {name}) -> None:",
+        "        self._resource = resource",
+        *[
+            f"        self.{operation.method_name} = {wrap}(resource.{operation.method_name})"
+            for operation in resource.operations
+        ],
+        "",
+    ]
+    for child_name, child in resource.children.items():
+        lines += [
+            "    @cached_property",
+            f"    def {child_name}(self) -> {prefix}{child.class_name}Resource{suffix}:",
+            f'        """``client.{_attr_path(child)}.{kind}``."""',
+            f"        return {prefix}{child.class_name}Resource{suffix}(self._resource.{child_name})\n",
+        ]
+    return "\n".join(lines).rstrip() + "\n"
+
+
 def _attr_path(resource: Resource) -> str:
     return ".".join(safe_identifier(snake(part)) for part in resource.path)
 
@@ -478,6 +538,12 @@ def render_resource_module(
         *[f"from ..{module} import {', '.join(sorted({sync, async_}))}" for module, sync, async_ in _mixins(resource)],
         *([f"from .._qs import {', '.join(runtime)}"] if runtime else []),
         "from .._resource import AsyncAPIResource, SyncAPIResource",
+        "from .._response import (",
+        "    async_to_raw_response_wrapper,",
+        "    async_to_streamed_response_wrapper,",
+        "    to_raw_response_wrapper,",
+        "    to_streamed_response_wrapper,",
+        ")",
         *(["from .._streaming import AsyncStream, Stream"] if any(op.kind == "stream" for op in operations) else []),
         "from .._types import NOT_GIVEN, Body, Headers, NotGiven, Query, Timeout"
         + (", OpenEnum" if "OpenEnum" in uses else ""),

docs/hooks/types_reference.py

@@ -121,7 +121,11 @@ def resources_page() -> str:
         if path.name.startswith("_"):
             continue
         tree = ast.parse(path.read_text())
-        classes = [n.name for n in tree.body if isinstance(n, ast.ClassDef) and not n.name.startswith("Async")]
+        classes = [
+            n.name
+            for n in tree.body
+            if isinstance(n, ast.ClassDef) and not n.name.startswith("Async") and n.name.endswith("Resource")
+        ]
         for cls in classes:
             lines += [f"::: opencode.resources.{path.stem}.{cls}", "    options:", "      show_bases: false", ""]
     return "\n".join(lines)

docs/reference/clients.md

@@ -2,12 +2,12 @@
 
 ::: opencode.Opencode
     options:
-      members: [with_options, copy, close, wait_until_ready, fake]
+      members: [with_options, copy, close, wait_until_ready, fake, get, post, put, patch, delete]
       show_bases: false
 
 ::: opencode.AsyncOpencode
     options:
-      members: [with_options, copy, close, wait_until_ready, fake]
+      members: [with_options, copy, close, wait_until_ready, fake, get, post, put, patch, delete]
       show_bases: false
 
 ::: opencode.DefaultAioHttpClient

docs/reference/index.md

@@ -8,7 +8,7 @@ Generated from the docstrings in `src/opencode`.
 | [Server launcher](server.md) | `OpencodeServer`, `AsyncOpencodeServer` |
 | [Background service](service.md) | `opencode.service`, `Endpoint`, `ServiceError` |
 | [Resources](resources.md) | Every `client.<group>` and its methods |
-| [Pagination and streams](pagination.md) | `SyncCursorPage`, `AsyncPaginator`, `Stream`, `AsyncStream` |
+| [Pagination and streams](pagination.md) | `SyncCursorPage`, `AsyncPaginator`, `Stream`, `AsyncStream`, `APIResponse` |
 | [Shared events and RPC](events.md) | `EventHub`, `Subscription`, `RpcDefinition`, `RpcClient` |
 | [Exceptions](exceptions.md) | Status errors and every declared server error |
 | [Types](types/index.md) | The models in `opencode.types`, grouped by domain |

docs/reference/pagination.md

@@ -9,3 +9,12 @@
 ::: opencode.Stream
 
 ::: opencode.AsyncStream
+
+## Raw responses
+
+Returned by `with_raw_response` and `with_streaming_response` on every resource. See
+[Accessing raw response data](https://github.com/shrijayan/opencode-python-sdk#accessing-raw-response-data).
+
+::: opencode.APIResponse
+
+::: opencode.AsyncAPIResponse

src/opencode/__init__.py

@@ -80,6 +80,7 @@
 from ._models import BaseModel
 from ._pagination import AsyncCursorPage, AsyncPaginator, SyncCursorPage
 from ._pty import AsyncPtyConnection, PtyConnection, PtyConnectionError
+from ._response import APIResponse, AsyncAPIResponse
 from ._server import AsyncOpencodeServer, OpencodeServer, ServerStartError
 from ._service import Endpoint, ServiceError
 from ._streaming import AsyncStream, Stream
@@ -125,10 +126,12 @@
     "API_VERSION",
     "NOT_GIVEN",
     "APIConnectionError",
+    "APIResponse",
     "APIError",
     "APIResponseValidationError",
     "APIStatusError",
     "APITimeoutError",
+    "AsyncAPIResponse",
     "AsyncCursorPage",
     "AsyncOpencode",
     "AsyncOpencodeServer",