python-corekit 0.2.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

corekit/http/client.py

@@ -1,7 +1,11 @@
 """
 A small HTTP client with retries.
 
-Subclass and give it a base URL::
+``BaseHttpClient`` is the transport: relative paths, optional strict URL
+checking, retries for statuses the typed HTTP exceptions mark as
+retryable, and ``stream_request`` for SSE / chunked bodies. Subclass
+``BaseApiClient`` when the client always talks to one API and a foreign
+absolute URL should be a bug.
 
     class GithubClient(BaseApiClient):
         '''
@@ -17,46 +21,81 @@ Subclass and give it a base URL::
             return {"Authorization": f"Bearer {self.token}"}
 
     client = GithubClient()
-    response = client.get("/user")          # or await client.async_get("/user")
+    response = client.get("/user")          # or await client.get("/user")
     response.data["login"]
 
 Every response comes back as a ``BaseApiResponse``, so callers see one shape
-regardless of what the endpoint returned. Requests that fail with a retryable
-status are retried with exponential backoff.
+regardless of what the endpoint returned.
 """
 
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
 from http import HTTPMethod
 from typing import Any
-from urllib.parse import urljoin
+from urllib.parse import urljoin, urlsplit, urlunsplit
 
 import httpx
 
+from corekit.concurrency.decorators import allow_sync
+from corekit.http.exceptions import RETRYABLE_STATUS_CODES, UnsupportedMethodError, URLMismatchError
 from corekit.http.exponential_backoff import ExponentialBackoff
 from corekit.http.response import BaseApiResponse
+from corekit.http.status import HTTPStatusCode
 from corekit.observability.benchmarkable import Benchmarkable
 
-__all__ = ["BaseApiClient", "URLMismatchError"]
+__all__ = ["BaseHttpClient"]
 
-# Statuses worth retrying: the server is busy or briefly unavailable, so the
-# same request may well succeed shortly. A 4xx other than 429 will not.
-RETRYABLE_STATUS_CODES = frozenset({429, 500, 502, 503, 504})
 
-
-class URLMismatchError(Exception):
+def _without_query(url: str) -> str:
     """
-    Raised when an absolute URL is passed that does not share the base URL.
+    Drop the query string before a retry warning is logged.
     """
+    parts = urlsplit(url)
+    return urlunsplit((parts.scheme, parts.netloc, parts.path, "", ""))
+
+
+_DEFAULT_METHODS = frozenset(
+    {
+        HTTPMethod.GET,
+        HTTPMethod.POST,
+        HTTPMethod.PUT,
+        HTTPMethod.PATCH,
+        HTTPMethod.DELETE,
+    }
+)
 
 
-class BaseApiClient(Benchmarkable):
+class BaseHttpClient(Benchmarkable):
     """
-    Base for API clients. Override ``base_url`` and, usually, ``headers``.
+    Base for HTTP clients. Override ``base_url`` and, usually, ``headers``.
+
+    ``strict=False`` accepts a foreign absolute URL as-is. ``BaseApiClient``
+    turns that into an error.
     """
 
-    def __init__(self, retries: int = 3, timeout: float = 30.0) -> None:
+    def __init__(
+        self,
+        retries: int = 3,
+        timeout: float = 30.0,
+        strict: bool = False,
+        base_delay: float = 1,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
         super().__init__()
         self.retries = retries
         self.timeout = timeout
+        self.strict = strict
+        self.base_delay = base_delay
+        # Optional pool. Left unset by default: @allow_sync runs sync calls on a
+        # throwaway loop, and an AsyncClient cannot move between loops.
+        self._http_client = http_client
+
+    @property
+    def supported_methods(self) -> frozenset[HTTPMethod]:
+        """
+        HTTP methods this client will send. Override to narrow or extend the set.
+        """
+        return _DEFAULT_METHODS
 
     @property
     def headers(self) -> dict[str, str]:
@@ -77,16 +116,18 @@ class BaseApiClient(Benchmarkable):
         Resolve a path against the base URL, accepting an absolute URL that
         already matches it.
         """
-        if url.startswith(self.base_url):
+        if self.base_url and url.startswith(self.base_url):
             return url
         if url.startswith("http"):
-            raise URLMismatchError(f"URL {url} does not match base URL {self.base_url}")
+            if self.strict:
+                raise URLMismatchError(url, self.base_url)
+            return url
         return urljoin(self.base_url, url)
 
     @staticmethod
-    def _to_response(raw: Any) -> BaseApiResponse:
+    def _to_response(raw: httpx.Response) -> BaseApiResponse:
         """
-        Normalize an httpx response into a BaseApiResponse.
+        Normalize a httpx response into a BaseApiResponse.
 
         The body is decoded as JSON when it parses, and left as text otherwise,
         so a caller never has to guard against a non-JSON error page.
@@ -99,78 +140,95 @@ class BaseApiClient(Benchmarkable):
             data = {"data": data}
 
         return BaseApiResponse(
-            status_code=raw.status_code,
+            status_code=HTTPStatusCode.coerce(raw.status_code),
             text=raw.text,
             data=data,
             headers=dict(raw.headers),
             cookies=dict(raw.cookies),
         )
 
-    def _new_backoff(self) -> ExponentialBackoff:
-        return ExponentialBackoff(retries=self.retries)
-
-    def request(self, method: HTTPMethod, url: str, **kwargs: Any) -> BaseApiResponse:
-        """
-        Send a request, retrying retryable statuses.
-        """
-
-        target = self._build_url(url)
-        backoff = self._new_backoff()
-
-        while True:
-            with httpx.Client(timeout=self.timeout) as client:
-                raw = client.request(str(method), target, headers=self.headers, **kwargs)
-
-            if raw.status_code not in RETRYABLE_STATUS_CODES or backoff.did_timeout():
-                return self._to_response(raw)
-
-            self.warning(f"{method} {target} returned {raw.status_code}; retrying")
-            backoff.wait()
-
-    async def async_request(self, method: HTTPMethod, url: str, **kwargs: Any) -> BaseApiResponse:
+    async def request(self, method: HTTPMethod, url: str, **kwargs: Any) -> BaseApiResponse:
         """
         Send a request asynchronously, retrying retryable statuses.
         """
+        if method not in self.supported_methods:
+            raise UnsupportedMethodError(method)
 
         target = self._build_url(url)
-        backoff = self._new_backoff()
-
+        headers = dict(self.headers)
+        extra_headers = kwargs.pop("headers", None)
+        if extra_headers:
+            headers.update(extra_headers)
+        # Fresh each request: ExponentialBackoff keeps its own attempt count.
+        backoff = ExponentialBackoff(retries=self.retries, base_delay=self.base_delay)
+
+        if self._http_client is not None:
+            return await self._exchange(self._http_client, method, target, headers, backoff, kwargs)
+
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            return await self._exchange(client, method, target, headers, backoff, kwargs)
+
+    async def _exchange(
+        self,
+        client: httpx.AsyncClient,
+        method: HTTPMethod,
+        target: str,
+        headers: dict[str, str],
+        backoff: ExponentialBackoff,
+        kwargs: dict[str, Any],
+    ) -> BaseApiResponse:
         while True:
-            async with httpx.AsyncClient(timeout=self.timeout) as client:
-                raw = await client.request(str(method), target, headers=self.headers, **kwargs)
-
+            raw = await client.request(str(method), target, headers=headers, **kwargs)
             if raw.status_code not in RETRYABLE_STATUS_CODES or backoff.did_timeout():
                 return self._to_response(raw)
 
-            self.warning(f"{method} {target} returned {raw.status_code}; retrying")
+            self.warning(f"{method} {_without_query(target)} returned {raw.status_code}; retrying")
             await backoff.async_wait()
 
-    def get(self, url: str, **kwargs: Any) -> BaseApiResponse:
-        return self.request(HTTPMethod.GET, url, **kwargs)
-
-    def post(self, url: str, **kwargs: Any) -> BaseApiResponse:
-        return self.request(HTTPMethod.POST, url, **kwargs)
-
-    def put(self, url: str, **kwargs: Any) -> BaseApiResponse:
-        return self.request(HTTPMethod.PUT, url, **kwargs)
-
-    def patch(self, url: str, **kwargs: Any) -> BaseApiResponse:
-        return self.request(HTTPMethod.PATCH, url, **kwargs)
-
-    def delete(self, url: str, **kwargs: Any) -> BaseApiResponse:
-        return self.request(HTTPMethod.DELETE, url, **kwargs)
-
-    async def async_get(self, url: str, **kwargs: Any) -> BaseApiResponse:
-        return await self.async_request(HTTPMethod.GET, url, **kwargs)
-
-    async def async_post(self, url: str, **kwargs: Any) -> BaseApiResponse:
-        return await self.async_request(HTTPMethod.POST, url, **kwargs)
-
-    async def async_put(self, url: str, **kwargs: Any) -> BaseApiResponse:
-        return await self.async_request(HTTPMethod.PUT, url, **kwargs)
+    @asynccontextmanager
+    async def stream_request(self, method: HTTPMethod, url: str, **kwargs: Any) -> AsyncIterator[httpx.Response]:
+        """
+        Open a streaming response and yield the raw ``httpx.Response``.
 
-    async def async_patch(self, url: str, **kwargs: Any) -> BaseApiResponse:
-        return await self.async_request(HTTPMethod.PATCH, url, **kwargs)
+        Holds the connection for the life of the ``async with`` block. Unlike
+        ``request``, the body is not buffered into a ``BaseApiResponse`` — the
+        caller reads it (for example with ``aiter_lines`` for SSE). Retries are
+        not applied: a mid-stream failure cannot be replayed safely.
+        """
+        if method not in self.supported_methods:
+            raise UnsupportedMethodError(method)
 
-    async def async_delete(self, url: str, **kwargs: Any) -> BaseApiResponse:
-        return await self.async_request(HTTPMethod.DELETE, url, **kwargs)
+        target = self._build_url(url)
+        headers = dict(self.headers)
+        extra_headers: dict[str, Any] | None = kwargs.pop("headers", None)
+        if extra_headers:
+            headers.update(extra_headers)
+
+        if self._http_client is not None:
+            async with self._http_client.stream(str(method), target, headers=headers, **kwargs) as response:
+                yield response
+            return
+
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            async with client.stream(str(method), target, headers=headers, **kwargs) as response:
+                yield response
+
+    @allow_sync
+    async def get(self, url: str, **kwargs: Any) -> BaseApiResponse:
+        return await self.request(HTTPMethod.GET, url, **kwargs)
+
+    @allow_sync
+    async def post(self, url: str, **kwargs: Any) -> BaseApiResponse:
+        return await self.request(HTTPMethod.POST, url, **kwargs)
+
+    @allow_sync
+    async def put(self, url: str, **kwargs: Any) -> BaseApiResponse:
+        return await self.request(HTTPMethod.PUT, url, **kwargs)
+
+    @allow_sync
+    async def patch(self, url: str, **kwargs: Any) -> BaseApiResponse:
+        return await self.request(HTTPMethod.PATCH, url, **kwargs)
+
+    @allow_sync
+    async def delete(self, url: str, **kwargs: Any) -> BaseApiResponse:
+        return await self.request(HTTPMethod.DELETE, url, **kwargs)

corekit/http/exceptions.py

@@ -0,0 +1,140 @@
+"""
+HTTP-specific exceptions.
+
+These live here, not in ``corekit.exceptions``, so the exception package does
+not have to import this layer. The bases (``CoreHTTPException`` and the
+retryable / non-retryable variants) still come from there.
+"""
+
+from http import HTTPMethod
+from typing import Any
+
+from corekit.exceptions.base import (
+    InternalCoreException,
+    NonRetryableCoreHTTPException,
+    RetryableCoreHTTPException,
+)
+from corekit.exceptions.enum import Retryability
+from corekit.http.status import HTTPStatusCode
+
+__all__ = [
+    "BadGatewayException",
+    "BadRequestException",
+    "ConflictErrorException",
+    "ForbiddenException",
+    "GatewayTimeoutException",
+    "InternalServerErrorException",
+    "NotFoundException",
+    "ServiceUnavailableException",
+    "TooManyRequestsException",
+    "UnauthorizedException",
+    "UnprocessableEntityException",
+    "UnsupportedMediaTypeException",
+    "UnsupportedMethodError",
+    "URLMismatchError",
+    "RETRYABLE_STATUS_CODES",
+]
+
+
+class _CodedHTTPException:
+    """
+    Sets ``status_code`` from the class. The code is the type, so a caller
+    cannot pass a different one and have a ``GatewayTimeoutException`` that is
+    actually a 200.
+    """
+
+    code: HTTPStatusCode
+
+    def __init__(self, **kwargs: Any) -> None:
+        if "status_code" in kwargs:
+            raise TypeError(f"{type(self).__name__} does not accept status_code; it is always {int(self.code)}")
+        super().__init__(status_code=self.code, **kwargs)
+
+
+class BadRequestException(_CodedHTTPException, NonRetryableCoreHTTPException):
+    code = HTTPStatusCode.BAD_REQUEST
+
+
+class UnauthorizedException(_CodedHTTPException, NonRetryableCoreHTTPException):
+    code = HTTPStatusCode.UNAUTHORIZED
+
+
+class ForbiddenException(_CodedHTTPException, NonRetryableCoreHTTPException):
+    code = HTTPStatusCode.FORBIDDEN
+
+
+class NotFoundException(_CodedHTTPException, NonRetryableCoreHTTPException):
+    code = HTTPStatusCode.NOT_FOUND
+
+
+class ConflictErrorException(_CodedHTTPException, NonRetryableCoreHTTPException):
+    code = HTTPStatusCode.CONFLICT
+
+
+class UnsupportedMediaTypeException(_CodedHTTPException, NonRetryableCoreHTTPException):
+    code = HTTPStatusCode.UNSUPPORTED_MEDIA_TYPE
+
+
+class UnprocessableEntityException(_CodedHTTPException, NonRetryableCoreHTTPException):
+    code = HTTPStatusCode.UNPROCESSABLE_ENTITY
+
+
+class TooManyRequestsException(_CodedHTTPException, RetryableCoreHTTPException):
+    code = HTTPStatusCode.TOO_MANY_REQUESTS
+
+
+class InternalServerErrorException(_CodedHTTPException, RetryableCoreHTTPException):
+    code = HTTPStatusCode.INTERNAL_SERVER_ERROR
+
+
+class BadGatewayException(_CodedHTTPException, RetryableCoreHTTPException):
+    code = HTTPStatusCode.BAD_GATEWAY
+
+
+class ServiceUnavailableException(_CodedHTTPException, RetryableCoreHTTPException):
+    code = HTTPStatusCode.SERVICE_UNAVAILABLE
+
+
+class GatewayTimeoutException(_CodedHTTPException, RetryableCoreHTTPException):
+    code = HTTPStatusCode.GATEWAY_TIMEOUT
+
+
+# Statuses worth retrying: the server is busy or briefly unavailable, so the
+# same request may well succeed shortly. A 4xx other than 429 will not.
+# Derived from the typed exceptions so this set cannot drift from retryability.
+RETRYABLE_STATUS_CODES = frozenset(
+    {
+        TooManyRequestsException.code,
+        InternalServerErrorException.code,
+        BadGatewayException.code,
+        ServiceUnavailableException.code,
+        GatewayTimeoutException.code,
+    }
+)
+
+
+class URLMismatchError(InternalCoreException):
+    """
+    Raised when an absolute URL does not share the client's base URL.
+    """
+
+    def __init__(self, url: str, base_url: str) -> None:
+        super().__init__(
+            message=f"URL {url} does not match base URL {base_url}",
+            retryable=Retryability.NON_RETRYABLE,
+        )
+        self.url = url
+        self.base_url = base_url
+
+
+class UnsupportedMethodError(InternalCoreException):
+    """
+    Raised when a client is asked for an HTTP method it does not implement.
+    """
+
+    def __init__(self, method: HTTPMethod) -> None:
+        super().__init__(
+            message=f"Method {method} is not supported",
+            retryable=Retryability.NON_RETRYABLE,
+        )
+        self.method = method

corekit/http/response.py

@@ -1,12 +1,61 @@
 from pydantic import BaseModel, Field
 
+from corekit.exceptions import CoreHTTPException
+from corekit.http.exceptions import (
+    BadGatewayException,
+    ConflictErrorException,
+    ForbiddenException,
+    GatewayTimeoutException,
+    InternalServerErrorException,
+    NotFoundException,
+    ServiceUnavailableException,
+    TooManyRequestsException,
+    UnauthorizedException,
+    UnprocessableEntityException,
+)
+from corekit.http.status import HTTPStatusCode
 from corekit.schemas.pydantic.fields import DefaultDictField
 from corekit.schemas.types import AnyDict
 
 
 class BaseApiResponse(BaseModel):
-    status_code: int = Field(..., description="HTTP status code")
+    status_code: HTTPStatusCode | int = Field(..., description="HTTP status code")
     text: str = Field(..., description="Response text")
     data: AnyDict = DefaultDictField()
     headers: AnyDict = DefaultDictField()
     cookies: AnyDict = DefaultDictField()
+
+    @property
+    def ok(self) -> bool:
+        """
+        Whether the status is below 400. A failure is still a response.
+        """
+        return int(self.status_code) < 400
+
+    def raise_for_status(self) -> "BaseApiResponse":
+        """
+        Raise a typed HTTP exception for a failure status.
+
+        Opt-in. ``request`` still returns the failure so existing callers that
+        read ``status_code`` keep working.
+        """
+        if self.ok:
+            return self
+
+        typed = {
+            int(UnauthorizedException.code): UnauthorizedException,
+            int(ForbiddenException.code): ForbiddenException,
+            int(NotFoundException.code): NotFoundException,
+            int(ConflictErrorException.code): ConflictErrorException,
+            int(UnprocessableEntityException.code): UnprocessableEntityException,
+            int(TooManyRequestsException.code): TooManyRequestsException,
+            int(InternalServerErrorException.code): InternalServerErrorException,
+            int(BadGatewayException.code): BadGatewayException,
+            int(ServiceUnavailableException.code): ServiceUnavailableException,
+            int(GatewayTimeoutException.code): GatewayTimeoutException,
+        }
+        detail = self.text or f"HTTP {int(self.status_code)}"
+        exception_type = typed.get(int(self.status_code))
+        if exception_type is None:
+            raise CoreHTTPException(status_code=int(self.status_code), detail=detail)
+        raise exception_type(detail=detail)

corekit/http/status.py

@@ -0,0 +1,89 @@
+"""
+HTTP codes
+See HTTP Status Code Registry:
+https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml
+
+And RFC 2324 - https://tools.ietf.org/html/rfc2324
+"""
+
+from corekit.schemas import IntegerEnum
+
+__all__ = ["HTTPStatusCode"]
+
+
+class HTTPStatusCode(IntegerEnum):
+    CONTINUE = 100
+    SWITCHING_PROTOCOLS = 101
+    PROCESSING = 102
+    EARLY_HINTS = 103
+    OK = 200
+    CREATED = 201
+    ACCEPTED = 202
+    NON_AUTHORITATIVE_INFORMATION = 203
+    NO_CONTENT = 204
+    RESET_CONTENT = 205
+    PARTIAL_CONTENT = 206
+    MULTI_STATUS = 207
+    ALREADY_REPORTED = 208
+    IM_USED = 226
+    MULTIPLE_CHOICES = 300
+    MOVED_PERMANENTLY = 301
+    FOUND = 302
+    SEE_OTHER = 303
+    NOT_MODIFIED = 304
+    USE_PROXY = 305
+    RESERVED = 306
+    TEMPORARY_REDIRECT = 307
+    PERMANENT_REDIRECT = 308
+    BAD_REQUEST = 400
+    UNAUTHORIZED = 401
+    PAYMENT_REQUIRED = 402
+    FORBIDDEN = 403
+    NOT_FOUND = 404
+    METHOD_NOT_ALLOWED = 405
+    NOT_ACCEPTABLE = 406
+    PROXY_AUTHENTICATION_REQUIRED = 407
+    REQUEST_TIMEOUT = 408
+    CONFLICT = 409
+    GONE = 410
+    LENGTH_REQUIRED = 411
+    PRECONDITION_FAILED = 412
+    REQUEST_ENTITY_TOO_LARGE = 413
+    REQUEST_URI_TOO_LONG = 414
+    UNSUPPORTED_MEDIA_TYPE = 415
+    REQUESTED_RANGE_NOT_SATISFIABLE = 416
+    EXPECTATION_FAILED = 417
+    IM_A_TEAPOT = 418
+    MISDIRECTED_REQUEST = 421
+    UNPROCESSABLE_ENTITY = 422
+    LOCKED = 423
+    FAILED_DEPENDENCY = 424
+    TOO_EARLY = 425
+    UPGRADE_REQUIRED = 426
+    PRECONDITION_REQUIRED = 428
+    TOO_MANY_REQUESTS = 429
+    REQUEST_HEADER_FIELDS_TOO_LARGE = 431
+    UNAVAILABLE_FOR_LEGAL_REASONS = 451
+    INTERNAL_SERVER_ERROR = 500
+    NOT_IMPLEMENTED = 501
+    BAD_GATEWAY = 502
+    SERVICE_UNAVAILABLE = 503
+    GATEWAY_TIMEOUT = 504
+    HTTP_VERSION_NOT_SUPPORTED = 505
+    VARIANT_ALSO_NEGOTIATES = 506
+    INSUFFICIENT_STORAGE = 507
+    LOOP_DETECTED = 508
+    NOT_EXTENDED = 510
+    NETWORK_AUTHENTICATION_REQUIRED = 511
+
+    @classmethod
+    def coerce(cls, code: int) -> "HTTPStatusCode | int":
+        """
+        Return the enum member for a known status, or the raw code otherwise.
+
+        Proxies and CDNs emit statuses this registry does not name. Callers
+        should still get the numeric code rather than a failed response parse.
+        """
+        if cls.is_member(code):
+            return cls.from_int(code)
+        return code

corekit/http/stream.py

@@ -0,0 +1,110 @@
+"""
+Decode streaming HTTP response bodies into typed events.
+
+``BaseHttpClient.stream_request`` yields a raw ``httpx.Response``. Decoders
+turn that into an async iterator of useful values (SSE text, SSE JSON, …).
+"""
+
+from __future__ import annotations
+
+import json
+from abc import ABC, abstractmethod
+from collections.abc import AsyncIterator
+from typing import Any, Generic, TypeVar
+
+import httpx
+
+from corekit.observability import Loggable
+
+__all__ = [
+    "SseDecoder",
+    "SseJsonDecoder",
+    "SseTextDecoder",
+    "StreamDecoder",
+]
+
+T = TypeVar("T")
+
+
+class StreamDecoder(Loggable, ABC, Generic[T]):
+    """
+    Turn a streaming ``httpx.Response`` into an async iterator of ``T``.
+    """
+
+    @abstractmethod
+    def decode(self, response: httpx.Response) -> AsyncIterator[T]:
+        """
+        Consume ``response`` and yield decoded items.
+
+        Implemented as an async generator on concrete subclasses.
+        """
+        ...
+
+
+class SseDecoder(StreamDecoder[T], ABC):
+    """
+    Server-Sent Events framing: ``data:`` lines, skip comments / blanks.
+
+    Optional ``done_sentinel`` (e.g. OpenAI's ``[DONE]``) ends the stream
+    early. Subclasses interpret each data payload via ``_decode_payload``.
+    """
+
+    def __init__(self, *, done_sentinel: str | None = None) -> None:
+        super().__init__()
+        self.done_sentinel = done_sentinel
+
+    async def decode(self, response: httpx.Response) -> AsyncIterator[T]:
+        async for data in self._iter_data_payloads(response):
+            item = self._decode_payload(data)
+            if item is not None:
+                yield item
+
+    async def _iter_data_payloads(self, response: httpx.Response) -> AsyncIterator[str]:
+        async for line in response.aiter_lines():
+            line = line.strip()
+            if not line.startswith("data:"):
+                continue
+            data = line.removeprefix("data:").strip()
+            if not data:
+                continue
+            if self.done_sentinel is not None and data == self.done_sentinel:
+                return
+            yield data
+
+    @abstractmethod
+    def _decode_payload(self, data: str) -> T | None:
+        """
+        Map one SSE data payload to ``T``, or ``None`` to skip.
+        """
+
+
+class SseTextDecoder(SseDecoder[str]):
+    """
+    Yield SSE data payloads as plain strings.
+    """
+
+    def _decode_payload(self, data: str) -> str | None:
+        return data
+
+
+class SseJsonDecoder(SseDecoder[dict[str, Any]]):
+    """
+    Yield SSE data payloads parsed as JSON objects.
+
+    Non-object JSON and decode failures are skipped (with a warning). Default
+    ``done_sentinel`` matches OpenAI-compatible chat streams.
+    """
+
+    def __init__(self, *, done_sentinel: str | None = "[DONE]") -> None:
+        super().__init__(done_sentinel=done_sentinel)
+
+    def _decode_payload(self, data: str) -> dict[str, Any] | None:
+        try:
+            payload = json.loads(data)
+        except json.JSONDecodeError:
+            self.warning(f"[SseJsonDecoder] Skipping bad SSE payload: {data!r}")
+            return None
+        if isinstance(payload, dict):
+            return payload
+        self.warning(f"[SseJsonDecoder] Skipping non-object SSE JSON: {type(payload).__name__}")
+        return None