runapi-core 0.7.0__tar.gz → 0.8.0__tar.gz

{runapi_core-0.7.0 → runapi_core-0.8.0}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.5
 Name: runapi-core
-Version: 0.7.0
+Version: 0.8.0
 Summary: RunAPI core SDK for JavaScript, Python, Ruby, Go, Java, and PHP
 Project-URL: Homepage, https://runapi.ai/models
 Project-URL: Documentation, https://runapi.ai/docs/resources/sdks
 Project-URL: Source, https://github.com/runapi-ai/core-sdk
 Project-URL: Issues, https://github.com/runapi-ai/core-sdk/issues
 Project-URL: Changelog, https://github.com/runapi-ai/core-sdk/blob/main/CHANGELOG.md
-Project-URL: Release Notes, https://github.com/runapi-ai/core-sdk/releases/tag/python%2Fv0.7.0
+Project-URL: Release Notes, https://github.com/runapi-ai/core-sdk/releases/tag/python%2Fv0.8.0
 Author-email: RunAPI <contact@runapi.ai>
 License-Expression: Apache-2.0
 Keywords: api,core,golang,gradle,java,maven,pypi,python,ruby,runapi,runapi-ai,sdk,typescript
@@ -41,6 +41,20 @@ RunAPI accepts an optional `X-Client-Request-Id` header on public API calls. Use
 
 Task-creation calls also accept an optional opaque `Idempotency-Key` up to 512 characters. Generate one value per logical task and reuse it only with identical input after an unknown result. Reusing the value with different input returns `409 Conflict`; do not derive it from `X-Client-Request-Id`.
 
+## Recovering Interrupted Requests
+
+Normal `run()` calls wait for and return the endpoint's terminal result. It also generates an `Idempotency-Key` before the initial POST when one was not supplied. If a lower-level request is interrupted after RunAPI accepted it, persist the opaque `Location` from the response and call `subscribe(location)` to recover the terminal result. Completed JSON responses keep their endpoint-specific type; text, SRT, and VTT responses return `str`.
+
+```python
+from runapi.midjourney import MidjourneyClient
+
+client = MidjourneyClient(api_key="sk-...")
+result = client.shorten_prompt.run(prompt="A detailed cinematic mountain landscape")
+
+# Persist this opaque URL after receiving 202 from a lower-level request.
+result = client.shorten_prompt.subscribe("https://runapi.ai/api/v1/tasks/task-id")
+```
+
 High-level Python Provider Client resource methods accept per-request options and keep response headers on the returned model object. This example uses the Suno Provider Client; install `runapi-suno` to run it.
 
 ```python

{runapi_core-0.7.0 → runapi_core-0.8.0}/README.md

@@ -24,6 +24,20 @@ RunAPI accepts an optional `X-Client-Request-Id` header on public API calls. Use
 
 Task-creation calls also accept an optional opaque `Idempotency-Key` up to 512 characters. Generate one value per logical task and reuse it only with identical input after an unknown result. Reusing the value with different input returns `409 Conflict`; do not derive it from `X-Client-Request-Id`.
 
+## Recovering Interrupted Requests
+
+Normal `run()` calls wait for and return the endpoint's terminal result. It also generates an `Idempotency-Key` before the initial POST when one was not supplied. If a lower-level request is interrupted after RunAPI accepted it, persist the opaque `Location` from the response and call `subscribe(location)` to recover the terminal result. Completed JSON responses keep their endpoint-specific type; text, SRT, and VTT responses return `str`.
+
+```python
+from runapi.midjourney import MidjourneyClient
+
+client = MidjourneyClient(api_key="sk-...")
+result = client.shorten_prompt.run(prompt="A detailed cinematic mountain landscape")
+
+# Persist this opaque URL after receiving 202 from a lower-level request.
+result = client.shorten_prompt.subscribe("https://runapi.ai/api/v1/tasks/task-id")
+```
+
 High-level Python Provider Client resource methods accept per-request options and keep response headers on the returned model object. This example uses the Suno Provider Client; install `runapi-suno` to run it.
 
 ```python

{runapi_core-0.7.0 → runapi_core-0.8.0}/pyproject.toml

@@ -19,7 +19,7 @@ Documentation = "https://runapi.ai/docs/resources/sdks"
 Source = "https://github.com/runapi-ai/core-sdk"
 Issues = "https://github.com/runapi-ai/core-sdk/issues"
 Changelog = "https://github.com/runapi-ai/core-sdk/blob/main/CHANGELOG.md"
-"Release Notes" = "https://github.com/runapi-ai/core-sdk/releases/tag/python%2Fv0.7.0"
+"Release Notes" = "https://github.com/runapi-ai/core-sdk/releases/tag/python%2Fv0.8.0"
 
 [tool.hatch.version]
 path = "src/runapi/core/version.py"

{runapi_core-0.7.0 → runapi_core-0.8.0}/src/runapi/core/__init__.py

@@ -34,6 +34,8 @@ from .models import (
     BillingSettlement,
     DynamicModel,
     TaskBillingFacts,
+    TaskResult,
+    TaskResultResponse,
     TaskResponse,
     optional,
     required,
@@ -82,6 +84,8 @@ __all__ = [
     "BaseModel",
     "DynamicModel",
     "TaskResponse",
+    "TaskResult",
+    "TaskResultResponse",
     "BillingReservation",
     "BillingSettlement",
     "BillingRefund",

{runapi_core-0.7.0 → runapi_core-0.8.0}/src/runapi/core/contract_gen.py

@@ -341,7 +341,11 @@ CONTRACT = {
         "models": ["grok-imagine-edit-image", "grok-imagine-image-2-0"],
         "fields_by_model": {
             "grok-imagine-edit-image": {},
-            "grok-imagine-image-2-0": {}
+            "grok-imagine-image-2-0": {
+                "aspect_ratio": {
+                    "enum": ["1:1", "2:3", "3:2", "16:9", "9:16", "auto"]
+                }
+            }
         }
     },
     "grok-imagine/extend": {
@@ -2072,7 +2076,7 @@ CONTRACT = {
         "fields_by_model": {
             "topaz-upscale-image": {
                 "upscale_factor": {
-                    "enum": [1, 2, 4, 8]
+                    "enum": [1, 2, 4]
                 }
             }
         }

{runapi_core-0.7.0 → runapi_core-0.8.0}/src/runapi/core/errors.py

@@ -204,10 +204,17 @@ def error_from_response(response: "Any") -> Error:
     Maps the status code to a specific error class and extracts the message,
     request id, response details, and (for 429) the retry-after delay.
     """
-    status = response.status_code
-    request_id = response.headers.get("x-request-id")
-
-    parsed_body = _parse_body(response.text)
+    return error_from_response_data(
+        response.status_code,
+        _parse_body(response.text),
+        response.headers,
+    )
+
+def error_from_response_data(status: int, body: Any, headers: Any = None) -> Error:
+    """Build a public SDK error from a stored terminal response checkpoint."""
+    response_headers = ResponseHeaders(headers)
+    request_id = response_headers.get("x-request-id")
+    parsed_body = body
     message = _extract_message(parsed_body) or DEFAULT_MESSAGES.get(status) or "Request failed"
 
     error_class = STATUS_MAP.get(status, Error)
@@ -217,10 +224,10 @@ def error_from_response(response: "Any") -> Error:
         "status": status,
         "request_id": request_id,
         "details": parsed_body,
-        "response_headers": response.headers,
+        "response_headers": response_headers,
     }
     if error_class is RateLimitError:
-        kwargs["retry_after"] = _parse_retry_after(response.headers.get("retry-after"))
+        kwargs["retry_after"] = _parse_retry_after(response_headers.get("retry-after"))
 
     return error_class(message, **kwargs)
 

{runapi_core-0.7.0 → runapi_core-0.8.0}/src/runapi/core/http_client.py

@@ -6,11 +6,12 @@ import json
 import random
 import time
 from typing import Any, Dict, List, Optional, Tuple
+from urllib.parse import urlsplit
 
 import httpx
 
 from . import constants
-from .errors import NetworkError, RateLimitError, TimeoutError, error_from_response
+from .errors import NetworkError, RateLimitError, TimeoutError, ValidationError, error_from_response
 from .multipart import MultipartBody
 from .options import ClientOptions, RequestOptions
 from .response import ApiResponse
@@ -51,6 +52,7 @@ class HttpClient:
         body: Any = None,
         options: Optional[RequestOptions] = None,
     ) -> Any:
+        self._validate_request_url(path)
         max_retries = self._options.max_retries
         if options is not None and options.max_retries is not None:
             max_retries = options.max_retries
@@ -75,8 +77,16 @@ class HttpClient:
                         timeout=timeout,
                     )
                 except httpx.TimeoutException as exc:
+                    if self._retryable_request(method, headers) and retries < max_retries:
+                        retries += 1
+                        time.sleep(self._retry_delay(retries, TimeoutError(str(exc))))
+                        continue
                     raise TimeoutError(str(exc))
                 except httpx.TransportError as exc:
+                    if self._retryable_request(method, headers) and retries < max_retries:
+                        retries += 1
+                        time.sleep(self._retry_delay(retries, NetworkError(str(exc))))
+                        continue
                     raise NetworkError(str(exc))
 
                 if response.status_code == 304:
@@ -87,11 +97,15 @@ class HttpClient:
                     if body is None:
                         return None
                     if isinstance(body, (dict, list)):
-                        return ApiResponse(body, response.headers)
+                        return ApiResponse(body, response.headers, status_code=response.status_code)
                     return body
 
                 error = error_from_response(response)
-                if self._retryable(method, response.status_code) and retries < max_retries:
+                if (
+                    self._retryable_request(method, headers)
+                    and response.status_code in constants.RETRYABLE_STATUS_CODES
+                    and retries < max_retries
+                ):
                     retries += 1
                     time.sleep(self._retry_delay(retries, error))
                     continue
@@ -122,6 +136,7 @@ class HttpClient:
         options: Optional[RequestOptions] = None,
     ) -> bytes:
         """Return a successful response body without text decoding."""
+        self._validate_request_url(path)
         max_retries = self._options.max_retries
         if options is not None and options.max_retries is not None:
             max_retries = options.max_retries
@@ -140,7 +155,11 @@ class HttpClient:
             if response.is_success:
                 return response.content
             error = error_from_response(response)
-            if self._retryable(method, response.status_code) and retries < max_retries:
+            if (
+                self._retryable_request(method, headers)
+                and response.status_code in constants.RETRYABLE_STATUS_CODES
+                and retries < max_retries
+            ):
                 retries += 1
                 time.sleep(self._retry_delay(retries, error))
                 continue
@@ -172,8 +191,25 @@ class HttpClient:
             return body, None, None, []
         return None, None, None, []
 
-    def _retryable(self, method: str, status: int) -> bool:
-        return method in constants.IDEMPOTENT_METHODS and status in constants.RETRYABLE_STATUS_CODES
+    def _retryable_request(self, method: str, headers: Dict[str, str]) -> bool:
+        return method in constants.IDEMPOTENT_METHODS or (
+            method == "POST"
+            and any(name.lower() == "idempotency-key" and str(value).strip() for name, value in headers.items())
+        )
+
+    def _validate_request_url(self, path: str) -> None:
+        requested = urlsplit(path)
+        if not requested.scheme and not requested.netloc:
+            return
+        configured = urlsplit(str(self._options.base_url))
+        if self._origin(requested) != self._origin(configured):
+            raise ValidationError("Request URL must use the configured RunAPI origin")
+
+    @staticmethod
+    def _origin(url: Any) -> Tuple[str, str, Optional[int]]:
+        scheme = url.scheme.lower()
+        port = url.port or ({"http": 80, "https": 443}.get(scheme))
+        return scheme, (url.hostname or "").lower(), port
 
     def _retry_delay(self, attempt: int, error: Any) -> float:
         if isinstance(error, RateLimitError) and error.retry_after and error.retry_after > 0:

{runapi_core-0.7.0 → runapi_core-0.8.0}/src/runapi/core/models.py

@@ -266,6 +266,23 @@ class TaskResponse(BaseModel):
     billing = optional(lambda: TaskBillingFacts)
 
 
+class TaskResultResponse(BaseModel):
+    """The persisted public response checkpoint for a terminal Task."""
+
+    status = required(int)
+    content_type = required(str)
+    headers = optional(dict)
+    body = optional()
+
+
+class TaskResult(TaskResponse):
+    """The account-scoped Task Result resource returned from an opaque Location."""
+
+    id = required(str)
+    status = required(str, enum=lambda: TaskResponse.Status.ALL)
+    response = optional(lambda: TaskResultResponse)
+
+
 class BillingReservation(BaseModel):
     amount_cents = required(int)
 

{runapi_core-0.7.0 → runapi_core-0.8.0}/src/runapi/core/polling.py

@@ -5,14 +5,21 @@ from __future__ import annotations
 import time
 from typing import Any, Callable, Optional
 
-from .errors import TaskFailedError, TaskTimeoutError
+from .errors import TaskFailedError, TaskTimeoutError, _parse_retry_after
 from .models import BaseModel
 from .options import PollingOptions
 
 ACTIVE_STATUSES = ("pending", "processing")
 
 
-def poll_until_complete(fetch: Callable[[], Any], options: Optional[PollingOptions] = None) -> Any:
+def poll_until_complete(
+    fetch: Callable[[], Any],
+    options: Optional[PollingOptions] = None,
+    *,
+    initial_delay: Optional[float] = None,
+    completed: Optional[Callable[[Any], Any]] = None,
+    failed: Optional[Callable[[Any], Exception]] = None,
+) -> Any:
     """Call ``fetch`` repeatedly until the task completes.
 
     Returns the completed response. Raises :class:`TaskFailedError` on a failed
@@ -22,15 +29,30 @@ def poll_until_complete(fetch: Callable[[], Any], options: Optional[PollingOptio
         options = PollingOptions()
 
     deadline = time.monotonic() + options.max_wait
+    wait = initial_delay
+    response = None
 
     while True:
+        if wait and wait > 0:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise _timeout_error(options, response)
+            time.sleep(min(wait, remaining))
+
+        if (response is not None or (wait and wait > 0)) and time.monotonic() >= deadline:
+            raise _timeout_error(options, response)
+
         response = fetch()
+        if time.monotonic() >= deadline:
+            raise _timeout_error(options, response)
         status = str(_value_for(response, "status") or "").lower()
 
         if status == "completed":
-            return response
+            return completed(response) if completed else response
 
         if status == "failed":
+            if failed:
+                raise failed(response)
             message = _value_for(response, "error") or "Task failed"
             raise TaskFailedError(
                 message,
@@ -38,13 +60,6 @@ def poll_until_complete(fetch: Callable[[], Any], options: Optional[PollingOptio
                 response_headers=_response_headers_for(response),
             )
 
-        if time.monotonic() >= deadline:
-            raise TaskTimeoutError(
-                f"Task polling timed out after {options.max_wait}s",
-                details=_details_for(response),
-                response_headers=_response_headers_for(response),
-            )
-
         if status not in ACTIVE_STATUSES:
             raise TaskFailedError(
                 f"Unknown task status: {status}",
@@ -52,7 +67,15 @@ def poll_until_complete(fetch: Callable[[], Any], options: Optional[PollingOptio
                 response_headers=_response_headers_for(response),
             )
 
-        time.sleep(options.poll_interval)
+        wait = _retry_after_for(response) or options.poll_interval
+
+
+def _timeout_error(options: PollingOptions, response: Any) -> TaskTimeoutError:
+    return TaskTimeoutError(
+        f"Task polling timed out after {options.max_wait}s",
+        details=_details_for(response) if response is not None else None,
+        response_headers=_response_headers_for(response) if response is not None else None,
+    )
 
 
 def _value_for(response: Any, key: str) -> Any:
@@ -69,3 +92,9 @@ def _details_for(response: Any) -> Any:
 
 def _response_headers_for(response: Any) -> Any:
     return response.response_headers if hasattr(response, "response_headers") else None
+
+
+def _retry_after_for(response: Any) -> Optional[float]:
+    headers = _response_headers_for(response)
+    delay = _parse_retry_after(headers.get("Retry-After") if headers else None)
+    return delay if delay and delay > 0 else None

{runapi_core-0.7.0 → runapi_core-0.8.0}/src/runapi/core/resource.py

@@ -2,11 +2,13 @@
 
 from __future__ import annotations
 
+from dataclasses import replace
 from typing import Any, Callable, Dict, Optional, Sequence
+from uuid import uuid4
 
 from . import polling
-from .errors import ValidationError
-from .models import BaseModel, TaskResponse
+from .errors import TaskFailedError, ValidationError, _parse_retry_after, error_from_response_data
+from .models import BaseModel, TaskResult, TaskResponse
 from .options import PollingOptions, RequestOptions
 from .response import ApiResponse
 
@@ -19,7 +21,7 @@ class Resource:
     re-coerces to once the task completes).
     """
 
-    RESPONSE_CLASS: type = TaskResponse
+    RESPONSE_CLASS: Optional[type] = TaskResponse
     COMPLETED_RESPONSE_CLASS: Optional[type] = None
 
     def __init__(self, http: Any) -> None:
@@ -34,12 +36,146 @@ class Resource:
         response_class: Optional[type] = None,
     ) -> Any:
         response = self._http.request(method, path, body=body, options=options)
+        return self._coerce_response(response, response_class)
+
+    def _coerce_response(self, response: Any, response_class: Optional[type] = None) -> Any:
         payload = response.body if isinstance(response, ApiResponse) else response
-        result = BaseModel.coerce(payload, as_=response_class or type(self).RESPONSE_CLASS)
+        target = response_class or type(self).RESPONSE_CLASS
+        result = payload if target is None else BaseModel.coerce(payload, as_=target)
         if isinstance(response, ApiResponse):
             self._attach_response_headers(result, response.response_headers)
         return result
 
+    def _run_hybrid(
+        self,
+        method: str,
+        path: str,
+        body: Any = None,
+        options: Optional[RequestOptions] = None,
+        polling_options: Optional[PollingOptions] = None,
+    ) -> Any:
+        """Run a terminal-or-accepted Task endpoint through one stable API."""
+        request_options = self._with_idempotency_key(options) if method.upper() == "POST" else options
+        response = self._http.request(method, path, body=body, options=request_options)
+        if isinstance(response, ApiResponse) and response.status_code == 202:
+            location = response.response_headers.get("Location")
+            if not location:
+                raise TaskFailedError(
+                    "Accepted Task response is missing Location",
+                    response_headers=response.response_headers,
+                )
+            return self.subscribe(
+                location,
+                options=request_options,
+                polling_options=polling_options,
+                initial_delay=self._retry_after(response.response_headers),
+            )
+        return self._coerce_response(response)
+
+    def subscribe(
+        self,
+        location: str,
+        *,
+        options: Optional[RequestOptions] = None,
+        polling_options: Optional[PollingOptions] = None,
+        initial_delay: Optional[float] = None,
+    ) -> Any:
+        """Follow an opaque Task Result URL until its stored terminal response is ready."""
+        return self._poll_until_complete(
+            lambda: self._request("get", location, options=options, response_class=TaskResult),
+            polling_options,
+            initial_delay=initial_delay,
+            completed=self._decode_task_result,
+            failed=self._task_result_error,
+        )
+
+    def _with_idempotency_key(self, options: Optional[RequestOptions]) -> RequestOptions:
+        headers = {}
+        idempotency_key = None
+        source_headers = (options.headers or {}) if options else {}
+        for name, value in source_headers.items():
+            if name.lower() != "idempotency-key":
+                headers[name] = value
+                continue
+
+            normalized = str(value).strip()
+            if not normalized:
+                continue
+            if idempotency_key is not None and idempotency_key != normalized:
+                raise ValidationError("conflicting Idempotency-Key headers")
+            idempotency_key = normalized
+
+        headers["Idempotency-Key"] = idempotency_key or str(uuid4())
+        return replace(options, headers=headers) if options else RequestOptions(headers=headers)
+
+    def _decode_task_result(self, task: TaskResult) -> Any:
+        response = task.response
+        if response is None:
+            raise TaskFailedError("Completed Task is missing its terminal response", details=task.to_dict())
+        if not 200 <= response.status < 300:
+            raise self._task_result_error(task)
+
+        body = self._plain_value(response.body)
+        content_type = response.content_type.lower().split(";", 1)[0].strip()
+        if content_type == "application/json" or content_type.endswith("+json"):
+            response_class = type(self).RESPONSE_CLASS
+            result = body if response_class is None else BaseModel.coerce(body, as_=response_class)
+            self._attach_response_headers(result, response.headers or {})
+            return result
+        if self._textual_content_type(content_type):
+            if isinstance(body, bytes):
+                return body.decode("utf-8")
+            return "" if body is None else str(body)
+        if isinstance(body, bytes):
+            return body
+        if isinstance(body, str):
+            return body.encode("utf-8")
+        return body
+
+    def _task_result_error(self, task: TaskResult) -> Exception:
+        response = task.response
+        if response is None:
+            return TaskFailedError("Task failed without a terminal response", details=task.to_dict())
+        return error_from_response_data(
+            response.status,
+            self._plain_value(response.body),
+            response.headers or {},
+        )
+
+    def _poll_until_complete(
+        self,
+        fetch: Callable[[], Any],
+        polling_opts: Optional[PollingOptions] = None,
+        **kwargs: Any,
+    ) -> Any:
+        response = polling.poll_until_complete(fetch, polling_opts or PollingOptions(), **kwargs)
+
+        if kwargs.get("completed"):
+            return response
+
+        completed_class = type(self).COMPLETED_RESPONSE_CLASS
+        if completed_class is None or isinstance(response, completed_class):
+            return response
+
+        payload = response.to_dict() if isinstance(response, BaseModel) else response
+        completed = completed_class.from_dict(payload)
+        if isinstance(response, BaseModel):
+            completed._with_response_headers(response.response_headers)
+        return completed
+
+    @staticmethod
+    def _plain_value(value: Any) -> Any:
+        return value.to_dict() if isinstance(value, BaseModel) else value
+
+    @staticmethod
+    def _textual_content_type(content_type: str) -> bool:
+        return content_type.startswith("text/") or content_type in {"application/srt", "application/x-subrip"}
+
+    @staticmethod
+    def _retry_after(headers: Any) -> Optional[float]:
+        delay = _parse_retry_after(headers.get("Retry-After") if headers else None)
+        return delay if delay and delay > 0 else None
+
     @staticmethod
     def _compact_params(params: Dict[str, Any]) -> Dict[str, Any]:
         return {
@@ -249,21 +385,6 @@ class Resource:
             return len(value) > 0
         return True
 
-    def _poll_until_complete(
-        self, fetch: Callable[[], Any], polling_opts: Optional[PollingOptions] = None
-    ) -> Any:
-        response = polling.poll_until_complete(fetch, polling_opts or PollingOptions())
-
-        completed_class = type(self).COMPLETED_RESPONSE_CLASS
-        if completed_class is None or isinstance(response, completed_class):
-            return response
-
-        payload = response.to_dict() if isinstance(response, BaseModel) else response
-        completed = completed_class.from_dict(payload)
-        if isinstance(response, BaseModel):
-            completed._with_response_headers(response.response_headers)
-        return completed
-
     def _attach_response_headers(self, result: Any, headers: Any) -> None:
         if isinstance(result, BaseModel):
             result._with_response_headers(headers)

{runapi_core-0.7.0 → runapi_core-0.8.0}/src/runapi/core/response.py

@@ -35,11 +35,18 @@ class ApiResponse(dict[str, Any]):
     that index the returned JSON body keep working.
     """
 
-    def __init__(self, body: Mapping[str, Any] | Sequence[Any], headers: Optional[Mapping[str, Any]] = None) -> None:
+    def __init__(
+        self,
+        body: Mapping[str, Any] | Sequence[Any],
+        headers: Optional[Mapping[str, Any]] = None,
+        *,
+        status_code: Optional[int] = None,
+    ) -> None:
         super().__init__(body if isinstance(body, Mapping) else {})
         self.body = self if isinstance(body, Mapping) else body
         self.response_headers = headers if isinstance(headers, ResponseHeaders) else ResponseHeaders(headers)
         self.headers = self.response_headers
+        self.status_code = status_code
 
     def __getitem__(self, key: Any) -> Any:
         if self.body is not self:

runapi_core-0.8.0/src/runapi/core/version.py

@@ -0,0 +1 @@
+__version__ = "0.8.0"

{runapi_core-0.7.0 → runapi_core-0.8.0}/tests/test_http_client.py

@@ -31,6 +31,25 @@ def test_returns_parsed_json_on_success():
     assert client.request("get", "/api/v1/test") == {"id": "123"}
 
 
+def test_rejects_cross_origin_absolute_url_before_sending_credentials():
+    requests = []
+    client = make_client(lambda request: requests.append(request) or httpx.Response(200, json={}))
+
+    with pytest.raises(errors.ValidationError, match="configured RunAPI origin"):
+        client.request("get", "https://attacker.example/tasks/task-1")
+
+    assert requests == []
+
+
+def test_accepts_absolute_url_on_configured_origin():
+    requested_urls = []
+    client = make_client(lambda request: requested_urls.append(str(request.url)) or httpx.Response(200, json={}))
+
+    client.request("get", "https://runapi.ai/api/v1/tasks/task-1")
+
+    assert requested_urls == ["https://runapi.ai/api/v1/tasks/task-1"]
+
+
 def test_keeps_response_headers_on_success():
     client = make_client(
         lambda request: httpx.Response(
@@ -198,6 +217,55 @@ def test_does_not_retry_post_on_503():
     assert calls["n"] == 1
 
 
+def test_retries_post_with_idempotency_key_and_reuses_the_key():
+    calls = []
+
+    def handler(request):
+        calls.append(request.headers["idempotency-key"])
+        if len(calls) == 1:
+            return httpx.Response(503, json={"error": "down"})
+        return httpx.Response(200, json={"ok": True})
+
+    assert make_client(handler).request(
+        "post",
+        "/api/v1/test",
+        body={"prompt": "hello"},
+        options=RequestOptions(headers={"Idempotency-Key": "task-key"}),
+    ) == {"ok": True}
+    assert calls == ["task-key", "task-key"]
+
+
+def test_does_not_retry_post_with_blank_idempotency_key():
+    calls = {"n": 0}
+
+    def handler(_request):
+        calls["n"] += 1
+        return httpx.Response(503, json={"error": "down"})
+
+    with pytest.raises(errors.ServiceUnavailableError):
+        make_client(handler).request(
+            "post",
+            "/api/v1/test",
+            body={"prompt": "hello"},
+            options=RequestOptions(headers={"Idempotency-Key": "  "}),
+        )
+
+    assert calls["n"] == 1
+
+
+def test_request_bytes_retries_idempotent_get():
+    calls = {"n": 0}
+
+    def handler(_request):
+        calls["n"] += 1
+        if calls["n"] == 1:
+            return httpx.Response(503, json={"error": "down"})
+        return httpx.Response(200, content=b"audio")
+
+    assert make_client(handler).request_bytes("get", "/api/v1/files/audio") == b"audio"
+    assert calls["n"] == 2
+
+
 def test_respects_retry_after(monkeypatch):
     slept = []
     monkeypatch.setattr(http_client.time, "sleep", lambda seconds: slept.append(seconds))