feat(api): add health check endpoint for proxies

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
-configured_endpoints: 89
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel%2Fkernel-2cf104c4b88159c6a50713b019188f83983748b9cacec598089cf9068dc5b1cd.yml
-openapi_spec_hash: 84ea30ae65ad7ebcc04d2f3907d1e73b
-config_hash: 179f33af31ece83563163d5b3d751d13
+configured_endpoints: 90
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel%2Fkernel-20fac779e9e13dc9421e467be31dbf274c39072ba0c01528ba451b48698d43c1.yml
+openapi_spec_hash: c3fc5784297ccc8f729326b62000d1f0
+config_hash: e47e015528251ee83e30367dbbb51044

api.md

@@ -228,7 +228,12 @@ Methods:
 Types:
 
 ```python
-from kernel.types import ProxyCreateResponse, ProxyRetrieveResponse, ProxyListResponse
+from kernel.types import (
+    ProxyCreateResponse,
+    ProxyRetrieveResponse,
+    ProxyListResponse,
+    ProxyCheckResponse,
+)
 ```
 
 Methods:
@@ -237,6 +242,7 @@ Methods:
 - <code title="get /proxies/{id}">client.proxies.<a href="./src/kernel/resources/proxies.py">retrieve</a>(id) -> <a href="./src/kernel/types/proxy_retrieve_response.py">ProxyRetrieveResponse</a></code>
 - <code title="get /proxies">client.proxies.<a href="./src/kernel/resources/proxies.py">list</a>() -> <a href="./src/kernel/types/proxy_list_response.py">ProxyListResponse</a></code>
 - <code title="delete /proxies/{id}">client.proxies.<a href="./src/kernel/resources/proxies.py">delete</a>(id) -> None</code>
+- <code title="post /proxies/{id}/check">client.proxies.<a href="./src/kernel/resources/proxies.py">check</a>(id) -> <a href="./src/kernel/types/proxy_check_response.py">ProxyCheckResponse</a></code>
 
 # Extensions
 

src/kernel/resources/proxies.py

@@ -19,6 +19,7 @@
 )
 from .._base_client import make_request_options
 from ..types.proxy_list_response import ProxyListResponse
+from ..types.proxy_check_response import ProxyCheckResponse
 from ..types.proxy_create_response import ProxyCreateResponse
 from ..types.proxy_retrieve_response import ProxyRetrieveResponse
 
@@ -184,6 +185,39 @@ def delete(
             cast_to=NoneType,
         )
 
+    def check(
+        self,
+        id: str,
+        *,
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    ) -> ProxyCheckResponse:
+        """
+        Run a health check on the proxy to verify it's working.
+
+        Args:
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          timeout: Override the client-level default timeout for this request, in seconds
+        """
+        if not id:
+            raise ValueError(f"Expected a non-empty value for `id` but received {id!r}")
+        return self._post(
+            f"/proxies/{id}/check",
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=ProxyCheckResponse,
+        )
+
 
 class AsyncProxiesResource(AsyncAPIResource):
     @cached_property
@@ -344,6 +378,39 @@ async def delete(
             cast_to=NoneType,
         )
 
+    async def check(
+        self,
+        id: str,
+        *,
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    ) -> ProxyCheckResponse:
+        """
+        Run a health check on the proxy to verify it's working.
+
+        Args:
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          timeout: Override the client-level default timeout for this request, in seconds
+        """
+        if not id:
+            raise ValueError(f"Expected a non-empty value for `id` but received {id!r}")
+        return await self._post(
+            f"/proxies/{id}/check",
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=ProxyCheckResponse,
+        )
+
 
 class ProxiesResourceWithRawResponse:
     def __init__(self, proxies: ProxiesResource) -> None:
@@ -361,6 +428,9 @@ def __init__(self, proxies: ProxiesResource) -> None:
         self.delete = to_raw_response_wrapper(
             proxies.delete,
         )
+        self.check = to_raw_response_wrapper(
+            proxies.check,
+        )
 
 
 class AsyncProxiesResourceWithRawResponse:
@@ -379,6 +449,9 @@ def __init__(self, proxies: AsyncProxiesResource) -> None:
         self.delete = async_to_raw_response_wrapper(
             proxies.delete,
         )
+        self.check = async_to_raw_response_wrapper(
+            proxies.check,
+        )
 
 
 class ProxiesResourceWithStreamingResponse:
@@ -397,6 +470,9 @@ def __init__(self, proxies: ProxiesResource) -> None:
         self.delete = to_streamed_response_wrapper(
             proxies.delete,
         )
+        self.check = to_streamed_response_wrapper(
+            proxies.check,
+        )
 
 
 class AsyncProxiesResourceWithStreamingResponse:
@@ -415,3 +491,6 @@ def __init__(self, proxies: AsyncProxiesResource) -> None:
         self.delete = async_to_streamed_response_wrapper(
             proxies.delete,
         )
+        self.check = async_to_streamed_response_wrapper(
+            proxies.check,
+        )

src/kernel/types/__init__.py

@@ -22,6 +22,7 @@
 from .browser_persistence import BrowserPersistence as BrowserPersistence
 from .proxy_create_params import ProxyCreateParams as ProxyCreateParams
 from .proxy_list_response import ProxyListResponse as ProxyListResponse
+from .proxy_check_response import ProxyCheckResponse as ProxyCheckResponse
 from .browser_create_params import BrowserCreateParams as BrowserCreateParams
 from .browser_delete_params import BrowserDeleteParams as BrowserDeleteParams
 from .browser_list_response import BrowserListResponse as BrowserListResponse

src/kernel/types/proxy_check_response.py

@@ -0,0 +1,195 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from typing import Union, Optional
+from datetime import datetime
+from typing_extensions import Literal, TypeAlias
+
+from .._models import BaseModel
+
+__all__ = [
+    "ProxyCheckResponse",
+    "Config",
+    "ConfigDatacenterProxyConfig",
+    "ConfigIspProxyConfig",
+    "ConfigResidentialProxyConfig",
+    "ConfigMobileProxyConfig",
+    "ConfigCustomProxyConfig",
+]
+
+
+class ConfigDatacenterProxyConfig(BaseModel):
+    """Configuration for a datacenter proxy."""
+
+    country: Optional[str] = None
+    """ISO 3166 country code. Defaults to US if not provided."""
+
+
+class ConfigIspProxyConfig(BaseModel):
+    """Configuration for an ISP proxy."""
+
+    country: Optional[str] = None
+    """ISO 3166 country code. Defaults to US if not provided."""
+
+
+class ConfigResidentialProxyConfig(BaseModel):
+    """Configuration for residential proxies."""
+
+    asn: Optional[str] = None
+    """Autonomous system number. See https://bgp.potaroo.net/cidr/autnums.html"""
+
+    city: Optional[str] = None
+    """City name (no spaces, e.g.
+
+    `sanfrancisco`). If provided, `country` must also be provided.
+    """
+
+    country: Optional[str] = None
+    """ISO 3166 country code."""
+
+    os: Optional[Literal["windows", "macos", "android"]] = None
+    """Operating system of the residential device."""
+
+    state: Optional[str] = None
+    """Two-letter state code."""
+
+    zip: Optional[str] = None
+    """US ZIP code."""
+
+
+class ConfigMobileProxyConfig(BaseModel):
+    """Configuration for mobile proxies."""
+
+    asn: Optional[str] = None
+    """Autonomous system number. See https://bgp.potaroo.net/cidr/autnums.html"""
+
+    carrier: Optional[
+        Literal[
+            "a1",
+            "aircel",
+            "airtel",
+            "att",
+            "celcom",
+            "chinamobile",
+            "claro",
+            "comcast",
+            "cox",
+            "digi",
+            "dt",
+            "docomo",
+            "dtac",
+            "etisalat",
+            "idea",
+            "kyivstar",
+            "meo",
+            "megafon",
+            "mtn",
+            "mtnza",
+            "mts",
+            "optus",
+            "orange",
+            "qwest",
+            "reliance_jio",
+            "robi",
+            "sprint",
+            "telefonica",
+            "telstra",
+            "tmobile",
+            "tigo",
+            "tim",
+            "verizon",
+            "vimpelcom",
+            "vodacomza",
+            "vodafone",
+            "vivo",
+            "zain",
+            "vivabo",
+            "telenormyanmar",
+            "kcelljsc",
+            "swisscom",
+            "singtel",
+            "asiacell",
+            "windit",
+            "cellc",
+            "ooredoo",
+            "drei",
+            "umobile",
+            "cableone",
+            "proximus",
+            "tele2",
+            "mobitel",
+            "o2",
+            "bouygues",
+            "free",
+            "sfr",
+            "digicel",
+        ]
+    ] = None
+    """Mobile carrier."""
+
+    city: Optional[str] = None
+    """City name (no spaces, e.g.
+
+    `sanfrancisco`). If provided, `country` must also be provided.
+    """
+
+    country: Optional[str] = None
+    """ISO 3166 country code"""
+
+    state: Optional[str] = None
+    """Two-letter state code."""
+
+    zip: Optional[str] = None
+    """US ZIP code."""
+
+
+class ConfigCustomProxyConfig(BaseModel):
+    """Configuration for a custom proxy (e.g., private proxy server)."""
+
+    host: str
+    """Proxy host address or IP."""
+
+    port: int
+    """Proxy port."""
+
+    has_password: Optional[bool] = None
+    """Whether the proxy has a password."""
+
+    username: Optional[str] = None
+    """Username for proxy authentication."""
+
+
+Config: TypeAlias = Union[
+    ConfigDatacenterProxyConfig,
+    ConfigIspProxyConfig,
+    ConfigResidentialProxyConfig,
+    ConfigMobileProxyConfig,
+    ConfigCustomProxyConfig,
+]
+
+
+class ProxyCheckResponse(BaseModel):
+    """Configuration for routing traffic through a proxy."""
+
+    type: Literal["datacenter", "isp", "residential", "mobile", "custom"]
+    """Proxy type to use.
+
+    In terms of quality for avoiding bot-detection, from best to worst: `mobile` >
+    `residential` > `isp` > `datacenter`.
+    """
+
+    id: Optional[str] = None
+
+    config: Optional[Config] = None
+    """Configuration specific to the selected proxy `type`."""
+
+    last_checked: Optional[datetime] = None
+    """Timestamp of the last health check performed on this proxy."""
+
+    name: Optional[str] = None
+    """Readable name of the proxy."""
+
+    protocol: Optional[Literal["http", "https"]] = None
+    """Protocol to use for the proxy connection."""
+
+    status: Optional[Literal["available", "unavailable"]] = None
+    """Current health status of the proxy."""