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

@@ -201,13 +201,15 @@ Types:
 - <code><a href="./src/resources/proxies.ts">ProxyCreateResponse</a></code>
 - <code><a href="./src/resources/proxies.ts">ProxyRetrieveResponse</a></code>
 - <code><a href="./src/resources/proxies.ts">ProxyListResponse</a></code>
+- <code><a href="./src/resources/proxies.ts">ProxyCheckResponse</a></code>
 
 Methods:
 
 - <code title="post /proxies">client.proxies.<a href="./src/resources/proxies.ts">create</a>({ ...params }) -> ProxyCreateResponse</code>
 - <code title="get /proxies/{id}">client.proxies.<a href="./src/resources/proxies.ts">retrieve</a>(id) -> ProxyRetrieveResponse</code>
 - <code title="get /proxies">client.proxies.<a href="./src/resources/proxies.ts">list</a>() -> ProxyListResponse</code>
 - <code title="delete /proxies/{id}">client.proxies.<a href="./src/resources/proxies.ts">delete</a>(id) -> void</code>
+- <code title="post /proxies/{id}/check">client.proxies.<a href="./src/resources/proxies.ts">check</a>(id) -> ProxyCheckResponse</code>
 
 # Extensions
 

src/client.ts

@@ -77,6 +77,7 @@ import {
 import { ProfileCreateParams, ProfileListResponse, Profiles } from './resources/profiles';
 import {
   Proxies,
+  ProxyCheckResponse,
   ProxyCreateParams,
   ProxyCreateResponse,
   ProxyListResponse,
@@ -950,6 +951,7 @@ export declare namespace Kernel {
     type ProxyCreateResponse as ProxyCreateResponse,
     type ProxyRetrieveResponse as ProxyRetrieveResponse,
     type ProxyListResponse as ProxyListResponse,
+    type ProxyCheckResponse as ProxyCheckResponse,
     type ProxyCreateParams as ProxyCreateParams,
   };
 

src/resources/index.ts

@@ -81,5 +81,6 @@ export {
   type ProxyCreateResponse,
   type ProxyRetrieveResponse,
   type ProxyListResponse,
+  type ProxyCheckResponse,
   type ProxyCreateParams,
 } from './proxies';

src/resources/proxies.ts

@@ -37,6 +37,13 @@ export class Proxies extends APIResource {
       headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
     });
   }
+
+  /**
+   * Run a health check on the proxy to verify it's working.
+   */
+  check(id: string, options?: RequestOptions): APIPromise<ProxyCheckResponse> {
+    return this._client.post(path`/proxies/${id}/check`, options);
+  }
 }
 
 /**
@@ -703,6 +710,226 @@ export namespace ProxyListResponse {
   }
 }
 
+/**
+ * Configuration for routing traffic through a proxy.
+ */
+export interface ProxyCheckResponse {
+  /**
+   * Proxy type to use. In terms of quality for avoiding bot-detection, from best to
+   * worst: `mobile` > `residential` > `isp` > `datacenter`.
+   */
+  type: 'datacenter' | 'isp' | 'residential' | 'mobile' | 'custom';
+
+  id?: string;
+
+  /**
+   * Configuration specific to the selected proxy `type`.
+   */
+  config?:
+    | ProxyCheckResponse.DatacenterProxyConfig
+    | ProxyCheckResponse.IspProxyConfig
+    | ProxyCheckResponse.ResidentialProxyConfig
+    | ProxyCheckResponse.MobileProxyConfig
+    | ProxyCheckResponse.CustomProxyConfig;
+
+  /**
+   * Timestamp of the last health check performed on this proxy.
+   */
+  last_checked?: string;
+
+  /**
+   * Readable name of the proxy.
+   */
+  name?: string;
+
+  /**
+   * Protocol to use for the proxy connection.
+   */
+  protocol?: 'http' | 'https';
+
+  /**
+   * Current health status of the proxy.
+   */
+  status?: 'available' | 'unavailable';
+}
+
+export namespace ProxyCheckResponse {
+  /**
+   * Configuration for a datacenter proxy.
+   */
+  export interface DatacenterProxyConfig {
+    /**
+     * ISO 3166 country code. Defaults to US if not provided.
+     */
+    country?: string;
+  }
+
+  /**
+   * Configuration for an ISP proxy.
+   */
+  export interface IspProxyConfig {
+    /**
+     * ISO 3166 country code. Defaults to US if not provided.
+     */
+    country?: string;
+  }
+
+  /**
+   * Configuration for residential proxies.
+   */
+  export interface ResidentialProxyConfig {
+    /**
+     * Autonomous system number. See https://bgp.potaroo.net/cidr/autnums.html
+     */
+    asn?: string;
+
+    /**
+     * City name (no spaces, e.g. `sanfrancisco`). If provided, `country` must also be
+     * provided.
+     */
+    city?: string;
+
+    /**
+     * ISO 3166 country code.
+     */
+    country?: string;
+
+    /**
+     * @deprecated Operating system of the residential device.
+     */
+    os?: 'windows' | 'macos' | 'android';
+
+    /**
+     * Two-letter state code.
+     */
+    state?: string;
+
+    /**
+     * US ZIP code.
+     */
+    zip?: string;
+  }
+
+  /**
+   * Configuration for mobile proxies.
+   */
+  export interface MobileProxyConfig {
+    /**
+     * Autonomous system number. See https://bgp.potaroo.net/cidr/autnums.html
+     */
+    asn?: string;
+
+    /**
+     * Mobile carrier.
+     */
+    carrier?:
+      | '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';
+
+    /**
+     * City name (no spaces, e.g. `sanfrancisco`). If provided, `country` must also be
+     * provided.
+     */
+    city?: string;
+
+    /**
+     * ISO 3166 country code
+     */
+    country?: string;
+
+    /**
+     * Two-letter state code.
+     */
+    state?: string;
+
+    /**
+     * US ZIP code.
+     */
+    zip?: string;
+  }
+
+  /**
+   * Configuration for a custom proxy (e.g., private proxy server).
+   */
+  export interface CustomProxyConfig {
+    /**
+     * Proxy host address or IP.
+     */
+    host: string;
+
+    /**
+     * Proxy port.
+     */
+    port: number;
+
+    /**
+     * Whether the proxy has a password.
+     */
+    has_password?: boolean;
+
+    /**
+     * Username for proxy authentication.
+     */
+    username?: string;
+  }
+}
+
 export interface ProxyCreateParams {
   /**
    * Proxy type to use. In terms of quality for avoiding bot-detection, from best to
@@ -913,6 +1140,7 @@ export declare namespace Proxies {
     type ProxyCreateResponse as ProxyCreateResponse,
     type ProxyRetrieveResponse as ProxyRetrieveResponse,
     type ProxyListResponse as ProxyListResponse,
+    type ProxyCheckResponse as ProxyCheckResponse,
     type ProxyCreateParams as ProxyCreateParams,
   };
 }

tests/api-resources/proxies.test.ts

@@ -65,4 +65,16 @@ describe('resource proxies', () => {
     expect(dataAndResponse.data).toBe(response);
     expect(dataAndResponse.response).toBe(rawResponse);
   });
+
+  // Prism tests are disabled
+  test.skip('check', async () => {
+    const responsePromise = client.proxies.check('id');
+    const rawResponse = await responsePromise.asResponse();
+    expect(rawResponse).toBeInstanceOf(Response);
+    const response = await responsePromise;
+    expect(response).not.toBeInstanceOf(Response);
+    const dataAndResponse = await responsePromise.withResponse();
+    expect(dataAndResponse.data).toBe(response);
+    expect(dataAndResponse.response).toBe(rawResponse);
+  });
 });