feat: api: paginate GET /proxies

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 117
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel/kernel-33e46e6a0095c2ec39a51860ee4e133c5a21a80a90cbe9e52953c07e5e0295de.yml
-openapi_spec_hash: 4aa466b9af39768b65a44b68ae0d1f6e
-config_hash: ede72e4ae65cc5a6d6927938b3455c46
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel/kernel-f3e52a8a9d9e37f8b527bdcce63b39cf8807d138cf3570c9954ba7f42ef02375.yml
+openapi_spec_hash: 2b787691eba1bb7bafb553528c09d5c0
+config_hash: e12afec516ced9520590c7a05af7a6f7

api.md

@@ -283,7 +283,7 @@ 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="get /proxies">client.proxies.<a href="./src/resources/proxies.ts">list</a>({ ...params }) -> ProxyListResponsesOffsetPagination</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, { ...params }) -> ProxyCheckResponse</code>
 

src/client.ts

@@ -110,7 +110,9 @@ import {
   ProxyCheckResponse,
   ProxyCreateParams,
   ProxyCreateResponse,
+  ProxyListParams,
   ProxyListResponse,
+  ProxyListResponsesOffsetPagination,
   ProxyRetrieveResponse,
 } from './resources/proxies';
 import { Auth } from './resources/auth/auth';
@@ -1081,7 +1083,9 @@ export declare namespace Kernel {
     type ProxyRetrieveResponse as ProxyRetrieveResponse,
     type ProxyListResponse as ProxyListResponse,
     type ProxyCheckResponse as ProxyCheckResponse,
+    type ProxyListResponsesOffsetPagination as ProxyListResponsesOffsetPagination,
     type ProxyCreateParams as ProxyCreateParams,
+    type ProxyListParams as ProxyListParams,
     type ProxyCheckParams as ProxyCheckParams,
   };
 

src/resources/index.ts

@@ -122,5 +122,7 @@ export {
   type ProxyListResponse,
   type ProxyCheckResponse,
   type ProxyCreateParams,
+  type ProxyListParams,
   type ProxyCheckParams,
+  type ProxyListResponsesOffsetPagination,
 } from './proxies';

src/resources/proxies.ts

@@ -2,6 +2,7 @@
 
 import { APIResource } from '../core/resource';
 import { APIPromise } from '../core/api-promise';
+import { OffsetPagination, type OffsetPaginationParams, PagePromise } from '../core/pagination';
 import { buildHeaders } from '../internal/headers';
 import { RequestOptions } from '../internal/request-options';
 import { path } from '../internal/utils/path';
@@ -27,8 +28,11 @@ export class Proxies extends APIResource {
   /**
    * List proxies owned by the caller's organization.
    */
-  list(options?: RequestOptions): APIPromise<ProxyListResponse> {
-    return this._client.get('/proxies', options);
+  list(
+    query: ProxyListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<ProxyListResponsesOffsetPagination, ProxyListResponse> {
+    return this._client.getAPIList('/proxies', OffsetPagination<ProxyListResponse>, { query, ...options });
   }
 
   /**
@@ -58,6 +62,8 @@ export class Proxies extends APIResource {
   }
 }
 
+export type ProxyListResponsesOffsetPagination = OffsetPagination<ProxyListResponse>;
+
 /**
  * Configuration for routing traffic through a proxy.
  */
@@ -370,163 +376,159 @@ export namespace ProxyRetrieveResponse {
   }
 }
 
-export type ProxyListResponse = Array<ProxyListResponse.ProxyListResponseItem>;
+/**
+ * Configuration for routing traffic through a proxy.
+ */
+export interface ProxyListResponse {
+  /**
+   * 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;
+
+  /**
+   * Hostnames that should bypass the parent proxy and connect directly.
+   */
+  bypass_hosts?: Array<string>;
+
+  /**
+   * Configuration specific to the selected proxy `type`.
+   */
+  config?:
+    | ProxyListResponse.DatacenterProxyConfig
+    | ProxyListResponse.IspProxyConfig
+    | ProxyListResponse.ResidentialProxyConfig
+    | ProxyListResponse.MobileProxyConfig
+    | ProxyListResponse.CustomProxyConfig;
+
+  /**
+   * IP address that the proxy uses when making requests.
+   */
+  ip_address?: string;
+
+  /**
+   * 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 ProxyListResponse {
   /**
-   * Configuration for routing traffic through a proxy.
+   * Configuration for a datacenter proxy.
    */
-  export interface ProxyListResponseItem {
+  export interface DatacenterProxyConfig {
     /**
-     * Proxy type to use. In terms of quality for avoiding bot-detection, from best to
-     * worst: `mobile` > `residential` > `isp` > `datacenter`.
+     * ISO 3166 country code. Defaults to US if not provided.
      */
-    type: 'datacenter' | 'isp' | 'residential' | 'mobile' | 'custom';
-
-    id?: string;
+    country?: string;
+  }
 
+  /**
+   * Configuration for an ISP proxy.
+   */
+  export interface IspProxyConfig {
     /**
-     * Hostnames that should bypass the parent proxy and connect directly.
+     * ISO 3166 country code. Defaults to US if not provided.
      */
-    bypass_hosts?: Array<string>;
+    country?: string;
+  }
 
+  /**
+   * Configuration for residential proxies.
+   */
+  export interface ResidentialProxyConfig {
     /**
-     * Configuration specific to the selected proxy `type`.
+     * Autonomous system number. See https://bgp.potaroo.net/cidr/autnums.html
      */
-    config?:
-      | ProxyListResponseItem.DatacenterProxyConfig
-      | ProxyListResponseItem.IspProxyConfig
-      | ProxyListResponseItem.ResidentialProxyConfig
-      | ProxyListResponseItem.MobileProxyConfig
-      | ProxyListResponseItem.CustomProxyConfig;
+    asn?: string;
 
     /**
-     * IP address that the proxy uses when making requests.
+     * City name (no spaces, e.g. `sanfrancisco`). If provided, `country` must also be
+     * provided.
      */
-    ip_address?: string;
+    city?: string;
 
     /**
-     * Timestamp of the last health check performed on this proxy.
+     * ISO 3166 country code.
      */
-    last_checked?: string;
+    country?: string;
 
     /**
-     * Readable name of the proxy.
+     * @deprecated Operating system of the residential device.
      */
-    name?: string;
+    os?: 'windows' | 'macos' | 'android';
 
     /**
-     * Protocol to use for the proxy connection.
+     * Two-letter state code.
      */
-    protocol?: 'http' | 'https';
+    state?: string;
 
     /**
-     * Current health status of the proxy.
+     * US ZIP code.
      */
-    status?: 'available' | 'unavailable';
+    zip?: string;
   }
 
-  export namespace ProxyListResponseItem {
+  /**
+   * Configuration for mobile proxies.
+   */
+  export interface MobileProxyConfig {
     /**
-     * Configuration for a datacenter proxy.
+     * Provider city alias. Mobile carrier routing can make observed geo vary.
      */
-    export interface DatacenterProxyConfig {
-      /**
-       * ISO 3166 country code. Defaults to US if not provided.
-       */
-      country?: string;
-    }
+    city?: string;
 
     /**
-     * Configuration for an ISP proxy.
+     * ISO 3166 country code
      */
-    export interface IspProxyConfig {
-      /**
-       * ISO 3166 country code. Defaults to US if not provided.
-       */
-      country?: string;
-    }
+    country?: string;
 
     /**
-     * Configuration for residential proxies.
+     * US-only state code. Mobile carrier routing can make observed geo vary.
      */
-    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;
-    }
+    state?: string;
+  }
 
+  /**
+   * Configuration for a custom proxy (e.g., private proxy server).
+   */
+  export interface CustomProxyConfig {
     /**
-     * Configuration for mobile proxies.
+     * Proxy host address or IP.
      */
-    export interface MobileProxyConfig {
-      /**
-       * Provider city alias. Mobile carrier routing can make observed geo vary.
-       */
-      city?: string;
-
-      /**
-       * ISO 3166 country code
-       */
-      country?: string;
-
-      /**
-       * US-only state code. Mobile carrier routing can make observed geo vary.
-       */
-      state?: string;
-    }
+    host: string;
 
     /**
-     * Configuration for a custom proxy (e.g., private proxy server).
+     * Proxy port.
      */
-    export interface CustomProxyConfig {
-      /**
-       * Proxy host address or IP.
-       */
-      host: string;
-
-      /**
-       * Proxy port.
-       */
-      port: number;
+    port: number;
 
-      /**
-       * Whether the proxy has a password.
-       */
-      has_password?: boolean;
+    /**
+     * Whether the proxy has a password.
+     */
+    has_password?: boolean;
 
-      /**
-       * Username for proxy authentication.
-       */
-      username?: string;
-    }
+    /**
+     * Username for proxy authentication.
+     */
+    username?: string;
   }
 }
 
@@ -822,6 +824,8 @@ export namespace ProxyCreateParams {
   }
 }
 
+export interface ProxyListParams extends OffsetPaginationParams {}
+
 export interface ProxyCheckParams {
   /**
    * An optional URL to test reachability against. If provided, the proxy check will
@@ -846,7 +850,9 @@ export declare namespace Proxies {
     type ProxyRetrieveResponse as ProxyRetrieveResponse,
     type ProxyListResponse as ProxyListResponse,
     type ProxyCheckResponse as ProxyCheckResponse,
+    type ProxyListResponsesOffsetPagination as ProxyListResponsesOffsetPagination,
     type ProxyCreateParams as ProxyCreateParams,
+    type ProxyListParams as ProxyListParams,
     type ProxyCheckParams as ProxyCheckParams,
   };
 }

tests/api-resources/proxies.test.ts

@@ -55,6 +55,14 @@ describe('resource proxies', () => {
     expect(dataAndResponse.response).toBe(rawResponse);
   });
 
+  // Mock server tests are disabled
+  test.skip('list: request options and params are passed correctly', async () => {
+    // ensure the request options are being passed correctly by passing an invalid HTTP method in order to cause an error
+    await expect(
+      client.proxies.list({ limit: 1, offset: 0 }, { path: '/_stainless_unknown_path' }),
+    ).rejects.toThrow(Kernel.NotFoundError);
+  });
+
   // Mock server tests are disabled
   test.skip('delete', async () => {
     const responsePromise = client.proxies.delete('id');