proxies.ts

// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

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';

/**
 * Create and manage proxy configurations for routing browser traffic.
 */
export class Proxies extends APIResource {
  /**
   * Create a new proxy configuration in the resolved project.
   *
   * @example
   * ```ts
   * const proxy = await client.proxies.create({ type: 'isp' });
   * ```
   */
  create(body: ProxyCreateParams, options?: RequestOptions): APIPromise<ProxyCreateResponse> {
    return this._client.post('/proxies', { body, ...options });
  }

  /**
   * Retrieve a proxy in the resolved project by ID or exact name using the database
   * collation. IDs take precedence when a value matches both an ID and a name. Proxy
   * names are not unique; an ambiguous name returns a 400 response with code
   * ambiguous_proxy_name.
   *
   * @example
   * ```ts
   * const proxy = await client.proxies.retrieve('id_or_name');
   * ```
   */
  retrieve(idOrName: string, options?: RequestOptions): APIPromise<ProxyRetrieveResponse> {
    return this._client.get(path`/proxies/${idOrName}`, options);
  }

  /**
   * Update a proxy's name. Proxy names are not unique and duplicate names are
   * allowed.
   *
   * @example
   * ```ts
   * const proxy = await client.proxies.update('id_or_name', {
   *   name: 'my-renamed-proxy',
   * });
   * ```
   */
  update(
    idOrName: string,
    body: ProxyUpdateParams,
    options?: RequestOptions,
  ): APIPromise<ProxyUpdateResponse> {
    return this._client.patch(path`/proxies/${idOrName}`, { body, ...options });
  }

  /**
   * List proxies in the resolved project.
   *
   * @example
   * ```ts
   * // Automatically fetches more pages as needed.
   * for await (const proxyListResponse of client.proxies.list()) {
   *   // ...
   * }
   * ```
   */
  list(
    query: ProxyListParams | null | undefined = {},
    options?: RequestOptions,
  ): PagePromise<ProxyListResponsesOffsetPagination, ProxyListResponse> {
    return this._client.getAPIList('/proxies', OffsetPagination<ProxyListResponse>, { query, ...options });
  }

  /**
   * Soft delete a proxy. Session records referencing it are not modified. If egress
   * binding polling is enabled, existing tunnels for active sessions using the proxy
   * are terminated within one polling interval; subsequent connections through the
   * deleted proxy are rejected.
   *
   * @example
   * ```ts
   * await client.proxies.delete('id_or_name');
   * ```
   */
  delete(idOrName: string, options?: RequestOptions): APIPromise<void> {
    return this._client.delete(path`/proxies/${idOrName}`, {
      ...options,
      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
    });
  }

  /**
   * Run a health check on the proxy to verify it's working. Optionally specify a URL
   * to test reachability against a specific target. For ISP proxies, this reliably
   * tests whether the target site is reachable from the proxy's stable exit IP. For
   * residential and mobile proxies, the exit node varies between requests, so this
   * validates proxy configuration and connectivity rather than guaranteeing
   * site-specific reachability.
   *
   * @example
   * ```ts
   * const response = await client.proxies.check('id_or_name');
   * ```
   */
  check(
    idOrName: string,
    body: ProxyCheckParams | null | undefined = {},
    options?: RequestOptions,
  ): APIPromise<ProxyCheckResponse> {
    return this._client.post(path`/proxies/${idOrName}/check`, { body, ...options });
  }
}

export type ProxyListResponsesOffsetPagination = OffsetPagination<ProxyListResponse>;

/**
 * Configuration for routing traffic through a proxy.
 */
export interface ProxyCreateResponse {
  type: 'isp' | 'residential' | 'mobile' | 'custom';

  id?: string;

  /**
   * Hostnames that should bypass the parent proxy and connect directly.
   */
  bypass_hosts?: Array<string>;

  /**
   * Configuration for an ISP proxy.
   */
  config?:
    | ProxyCreateResponse.IspProxyConfig
    | ProxyCreateResponse.ResidentialProxyConfig
    | ProxyCreateResponse.MobileProxyConfig
    | ProxyCreateResponse.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 ProxyCreateResponse {
  /**
   * Configuration for an ISP proxy.
   */
  export interface IspProxyConfig {
    /**
     * ISO 3166 country code. Supported countries are US, GB, FR, DE, SG, and KR.
     * 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. If omitted, the proxy uses the global pool without
     * country targeting.
     */
    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 {
    /**
     * Provider city alias. Mobile carrier routing can make observed geo vary.
     */
    city?: string;

    /**
     * ISO 3166 country code. If omitted, the proxy uses the global pool without
     * country targeting.
     */
    country?: string;

    /**
     * US-only state code. Mobile carrier routing can make observed geo vary.
     */
    state?: 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 custom CA bundle configured.
     */
    has_ca_bundle?: boolean;

    /**
     * Whether the proxy has a password.
     */
    has_password?: boolean;

    /**
     * Username for proxy authentication.
     */
    username?: string;
  }
}

/**
 * Configuration for routing traffic through a proxy.
 */
export interface ProxyRetrieveResponse {
  type: 'isp' | 'residential' | 'mobile' | 'custom';

  id?: string;

  /**
   * Hostnames that should bypass the parent proxy and connect directly.
   */
  bypass_hosts?: Array<string>;

  /**
   * Configuration for an ISP proxy.
   */
  config?:
    | ProxyRetrieveResponse.IspProxyConfig
    | ProxyRetrieveResponse.ResidentialProxyConfig
    | ProxyRetrieveResponse.MobileProxyConfig
    | ProxyRetrieveResponse.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 ProxyRetrieveResponse {
  /**
   * Configuration for an ISP proxy.
   */
  export interface IspProxyConfig {
    /**
     * ISO 3166 country code. Supported countries are US, GB, FR, DE, SG, and KR.
     * 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. If omitted, the proxy uses the global pool without
     * country targeting.
     */
    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 {
    /**
     * Provider city alias. Mobile carrier routing can make observed geo vary.
     */
    city?: string;

    /**
     * ISO 3166 country code. If omitted, the proxy uses the global pool without
     * country targeting.
     */
    country?: string;

    /**
     * US-only state code. Mobile carrier routing can make observed geo vary.
     */
    state?: 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 custom CA bundle configured.
     */
    has_ca_bundle?: boolean;

    /**
     * Whether the proxy has a password.
     */
    has_password?: boolean;

    /**
     * Username for proxy authentication.
     */
    username?: string;
  }
}

/**
 * Configuration for routing traffic through a proxy.
 */
export interface ProxyUpdateResponse {
  type: 'isp' | 'residential' | 'mobile' | 'custom';

  id?: string;

  /**
   * Hostnames that should bypass the parent proxy and connect directly.
   */
  bypass_hosts?: Array<string>;

  /**
   * Configuration for an ISP proxy.
   */
  config?:
    | ProxyUpdateResponse.IspProxyConfig
    | ProxyUpdateResponse.ResidentialProxyConfig
    | ProxyUpdateResponse.MobileProxyConfig
    | ProxyUpdateResponse.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 ProxyUpdateResponse {
  /**
   * Configuration for an ISP proxy.
   */
  export interface IspProxyConfig {
    /**
     * ISO 3166 country code. Supported countries are US, GB, FR, DE, SG, and KR.
     * 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. If omitted, the proxy uses the global pool without
     * country targeting.
     */
    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 {
    /**
     * Provider city alias. Mobile carrier routing can make observed geo vary.
     */
    city?: string;

    /**
     * ISO 3166 country code. If omitted, the proxy uses the global pool without
     * country targeting.
     */
    country?: string;

    /**
     * US-only state code. Mobile carrier routing can make observed geo vary.
     */
    state?: 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 custom CA bundle configured.
     */
    has_ca_bundle?: boolean;

    /**
     * Whether the proxy has a password.
     */
    has_password?: boolean;

    /**
     * Username for proxy authentication.
     */
    username?: string;
  }
}

/**
 * Configuration for routing traffic through a proxy.
 */
export interface ProxyListResponse {
  type: 'isp' | 'residential' | 'mobile' | 'custom';

  id?: string;

  /**
   * Hostnames that should bypass the parent proxy and connect directly.
   */
  bypass_hosts?: Array<string>;

  /**
   * Configuration for an ISP proxy.
   */
  config?:
    | 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 an ISP proxy.
   */
  export interface IspProxyConfig {
    /**
     * ISO 3166 country code. Supported countries are US, GB, FR, DE, SG, and KR.
     * 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. If omitted, the proxy uses the global pool without
     * country targeting.
     */
    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 {
    /**
     * Provider city alias. Mobile carrier routing can make observed geo vary.
     */
    city?: string;

    /**
     * ISO 3166 country code. If omitted, the proxy uses the global pool without
     * country targeting.
     */
    country?: string;

    /**
     * US-only state code. Mobile carrier routing can make observed geo vary.
     */
    state?: 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 custom CA bundle configured.
     */
    has_ca_bundle?: boolean;

    /**
     * Whether the proxy has a password.
     */
    has_password?: boolean;

    /**
     * Username for proxy authentication.
     */
    username?: string;
  }
}

/**
 * Configuration for routing traffic through a proxy.
 */
export interface ProxyCheckResponse {
  type: 'isp' | 'residential' | 'mobile' | 'custom';

  id?: string;

  /**
   * Hostnames that should bypass the parent proxy and connect directly.
   */
  bypass_hosts?: Array<string>;

  /**
   * Configuration for an ISP proxy.
   */
  config?:
    | ProxyCheckResponse.IspProxyConfig
    | ProxyCheckResponse.ResidentialProxyConfig
    | ProxyCheckResponse.MobileProxyConfig
    | ProxyCheckResponse.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 ProxyCheckResponse {
  /**
   * Configuration for an ISP proxy.
   */
  export interface IspProxyConfig {
    /**
     * ISO 3166 country code. Supported countries are US, GB, FR, DE, SG, and KR.
     * 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. If omitted, the proxy uses the global pool without
     * country targeting.
     */
    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 {
    /**
     * Provider city alias. Mobile carrier routing can make observed geo vary.
     */
    city?: string;

    /**
     * ISO 3166 country code. If omitted, the proxy uses the global pool without
     * country targeting.
     */
    country?: string;

    /**
     * US-only state code. Mobile carrier routing can make observed geo vary.
     */
    state?: 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 custom CA bundle configured.
     */
    has_ca_bundle?: boolean;

    /**
     * Whether the proxy has a password.
     */
    has_password?: boolean;

    /**
     * Username for proxy authentication.
     */
    username?: string;
  }
}

export interface ProxyCreateParams {
  type: 'isp' | 'residential' | 'mobile' | 'custom';

  /**
   * Hostnames that should bypass the parent proxy and connect directly.
   */
  bypass_hosts?: Array<string>;

  /**
   * Configuration for an ISP proxy.
   */
  config?:
    | ProxyCreateParams.IspProxyConfig
    | ProxyCreateParams.ResidentialProxyConfig
    | ProxyCreateParams.MobileProxyConfig
    | ProxyCreateParams.CreateCustomProxyConfig;

  /**
   * Readable name of the proxy.
   */
  name?: string;

  /**
   * Protocol to use for the proxy connection.
   */
  protocol?: 'http' | 'https';
}

export namespace ProxyCreateParams {
  /**
   * Configuration for an ISP proxy.
   */
  export interface IspProxyConfig {
    /**
     * ISO 3166 country code. Supported countries are US, GB, FR, DE, SG, and KR.
     * 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. If omitted, the proxy uses the global pool without
     * country targeting.
     */
    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 {
    /**
     * Provider city alias. Mobile carrier routing can make observed geo vary.
     */
    city?: string;

    /**
     * ISO 3166 country code. If omitted, the proxy uses the global pool without
     * country targeting.
     */
    country?: string;

    /**
     * US-only state code. Mobile carrier routing can make observed geo vary.
     */
    state?: string;
  }

  /**
   * Configuration for a custom proxy (e.g., private proxy server).
   */
  export interface CreateCustomProxyConfig {
    /**
     * Proxy host address or IP.
     */
    host: string;

    /**
     * Proxy port.
     */
    port: number;

    /**
     * PEM-encoded CA certificate bundle the proxy re-signs upstream TLS with. Provide
     * when the proxy terminates TLS (MITM) so the browser trusts its certificates. May
     * contain multiple concatenated certificates.
     */
    ca_bundle?: string;

    /**
     * Password for proxy authentication.
     */
    password?: string;

    /**
     * Username for proxy authentication.
     */
    username?: string;
  }
}

export interface ProxyUpdateParams {
  /**
   * New proxy name. Proxy names are trimmed and length-checked only; duplicates are
   * allowed because proxies are updated by ID, not by name.
   */
  name: string;
}

export interface ProxyListParams extends OffsetPaginationParams {
  /**
   * Exact-match filter on proxy name using the database collation. In production,
   * matching is case- and accent-insensitive. Names are not required to be unique,
   * so multiple proxies may match.
   */
  name?: string;

  /**
   * Case-insensitive substring match against proxy name, host, or IP address. IDs
   * match by exact value.
   */
  query?: string;
}

export interface ProxyCheckParams {
  /**
   * An optional URL to test reachability against. If provided, the proxy check will
   * test connectivity to this URL instead of the default test URLs. Only HTTP and
   * HTTPS schemes are allowed, and the URL must resolve to a public IP address. For
   * ISP proxies, the exit IP is stable, so a successful check reliably indicates
   * that subsequent browser sessions will reach the target site with the same IP.
   * For residential and mobile proxies, the exit node changes between requests, so a
   * successful check validates proxy configuration but does not guarantee that a
   * subsequent browser session will use the same exit IP or reach the same site — it
   * is useful for verifying credentials and connectivity, not for predicting
   * site-specific behavior. When provided, the check result does not update the
   * proxy's health status, since a failure may indicate a problem with the target
   * site rather than the proxy itself.
   */
  url?: string;
}

export declare namespace Proxies {
  export {
    type ProxyCreateResponse as ProxyCreateResponse,
    type ProxyRetrieveResponse as ProxyRetrieveResponse,
    type ProxyUpdateResponse as ProxyUpdateResponse,
    type ProxyListResponse as ProxyListResponse,
    type ProxyCheckResponse as ProxyCheckResponse,
    type ProxyListResponsesOffsetPagination as ProxyListResponsesOffsetPagination,
    type ProxyCreateParams as ProxyCreateParams,
    type ProxyUpdateParams as ProxyUpdateParams,
    type ProxyListParams as ProxyListParams,
    type ProxyCheckParams as ProxyCheckParams,
  };
}