@serenity-js/rest 3.10.3 → 3.11.0

package/lib/screenplay/abilities/CallAnApi.js

@@ -1,17 +1,46 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CallAnApi = void 0;
 const core_1 = require("@serenity-js/core");
-const axios_1 = __importDefault(require("axios"));
+const axios_1 = __importStar(require("axios"));
+const proxy_1 = require("./proxy");
 /**
- * An {@apilink Ability} that enables the {@apilink Actor} to call an HTTP API.
+ * An {@apilink Ability} that wraps [axios client](https://axios-http.com/docs/api_intro) and enables
+ * the {@apilink Actor} to {@apilink Send} {@apilink HTTPRequest|HTTP requests} to HTTP APIs.
+ *
+ * `CallAnApi` uses [`proxy-from-env`](https://www.npmjs.com/package/proxy-from-env) and an approach
+ * described in ["Node.js Axios behind corporate proxies"](https://janmolak.com/node-js-axios-behind-corporate-proxies-8b17a6f31f9d)
+ * to automatically detect proxy server configuration based
+ * on your [environment variables](https://www.npmjs.com/package/proxy-from-env#environment-variables).
+ * You can override this configuration if needed.
  *
- * If you need to connect via a proxy, check out ["Using Axios behind corporate proxies"](https://janmolak.com/node-js-axios-behind-corporate-proxies-8b17a6f31f9d).
+ * ## Configuring the ability to call an API
  *
- * ## Using the default Axios HTTP client
+ * The easiest way to configure the ability to `CallAnApi` is to provide the `baseURL` of your HTTP API,
+ * and rely on Serenity/JS to offer other sensible defaults:
  *
  * ```ts
  * import { actorCalled } from '@serenity-js/core'
@@ -23,30 +52,180 @@ const axios_1 = __importDefault(require("axios"));
  *     CallAnApi.at('https://api.example.org/')
  *   )
  *   .attemptsTo(
+ *     Send.a(GetRequest.to('/v1/users/2')),            // GET https://api.example.org/v1/users/2
+ *     Ensure.that(LastResponse.status(), equals(200)),
+ *   )
+ * ```
+ *
+ * ### Resolving relative URLs
+ *
+ * Serenity/JS resolves request URLs using Node.js [WHATWG URL API](https://nodejs.org/api/url.html#new-urlinput-base).
+ * This means that the request URL is determined using the resource path resolved in the context of base URL, i.e. `new URL(resourcePath, [baseURL])`.
+ *
+ * Consider the following example:
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { CallAnApi, GetRequest, LastResponse, Send } from '@serenity-js/rest'
+ * import { Ensure, equals } from '@serenity-js/assertions'
+ *
+ * await actorCalled('Apisitt')
+ *   .whoCan(
+ *     CallAnApi.at(baseURL)
+ *   )
+ *   .attemptsTo(
+ *     Send.a(GetRequest.to(resourcePath)),
+ *     Ensure.that(LastResponse.status(), equals(200)),
+ *   )
+ * ```
+ *
+ * In the above example:
+ * - when `resourcePath` is defined as a full URL, it overrides the base URL
+ * - when `resourcePath` starts with a forward slash `/`, it replaces any path defined in the base URL
+ * - when `resourcePath` is not a full URL and doesn't start with a forward slash, it gets appended to the base URL
+ *
+ * | baseURL                       | resourcePath               | result                               |
+ * | ----------------------------- | -------------------------- | ------------------------------------ |
+ * | `https://api.example.org/`    | `/v1/users/2`              | `https://api.example.org/v1/users/2` |
+ * | `https://example.org/api/v1/` | `users/2`                  | `https://example.org/api/v1/users/2` |
+ * | `https://example.org/api/v1/` | `/secure/oauth`            | `https://example.org/secure/oauth`   |
+ * | `https://v1.example.org/api/` | `https://v2.example.org/`  | `https://v2.example.org/`            |
+ *
+ * ### Using Axios configuration object
+ *
+ * When you need more control over how your Axios instance is configured, provide
+ * an [Axios configuration object](https://axios-http.com/docs/req_config). For example:
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { CallAnApi, GetRequest, LastResponse, Send } from '@serenity-js/rest'
+ * import { Ensure, equals } from '@serenity-js/assertions'
+ *
+ * await actorCalled('Apisitt')
+ *   .whoCan(
+ *     CallAnApi.using({
+ *       baseURL: 'https://api.example.org/',
+ *       timeout: 30_000,
+ *       // ... other configuration options
+ *     })
+ *   )
+ *   .attemptsTo(
+ *     Send.a(GetRequest.to('/users/2')),
+ *     Ensure.that(LastResponse.status(), equals(200)),
+ *   )
+ * ```
+ *
+ * ### Working with proxy servers
+ *
+ * `CallAnApi` uses [`proxy-from-env`](https://www.npmjs.com/package/proxy-from-env) to automatically
+ * detect proxy server configuration based on your [environment variables](https://www.npmjs.com/package/proxy-from-env#environment-variables).
+ *
+ * This default behaviour can be overridden by providing explicit proxy configuration:
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { CallAnApi, GetRequest, LastResponse, Send } from '@serenity-js/rest'
+ * import { Ensure, equals } from '@serenity-js/assertions'
+ *
+ * await actorCalled('Apisitt')
+ *   .whoCan(
+ *     CallAnApi.using({
+ *       baseURL: 'https://api.example.org/',
+ *       proxy: {
+ *         protocol: 'http',
+ *         host: 'proxy.example.org',
+ *         port: 9000,
+ *         auth: {                          // `auth` is optional
+ *           username: 'proxy-username',
+ *           password: 'proxy-password',
+ *         }
+ *       }
+ *       // ... other configuration options
+ *     })
+ *   )
+ *   .attemptsTo(
+ *     Send.a(GetRequest.to('/users/2')),
+ *     Ensure.that(LastResponse.status(), equals(200)),
+ *   )
+ * ```
+ *
+ * Please note that Serenity/JS uses [proxy-agents](https://github.com/TooTallNate/proxy-agents)
+ * and the approach described in ["Node.js Axios behind corporate proxies"](https://janmolak.com/node-js-axios-behind-corporate-proxies-8b17a6f31f9d)
+ * to work around [limited proxy support capabilities](https://github.com/axios/axios/issues?q=is%3Aissue+is%3Aopen+proxy) in Axios itself.
+ *
+ * ### Using Axios instance with proxy support
+ *
+ * To have full control over the Axios instance used by the ability to `CallAnApi`, you can create it yourself
+ * and inject it into the ability.
+ * This approach allows you to still benefit from automated proxy detection in configuration, while taking advantage
+ * of the many [Axios plugins](https://www.npmjs.com/search?q=axios).
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { CallAnApi, GetRequest, LastResponse, Send } from '@serenity-js/rest'
+ * import { Ensure, equals } from '@serenity-js/assertions'
+ *
+ * import axios from 'axios'
+ * import axiosRetry from 'axios-retry'
+ *
+ * const instance = axios.create({ baseURL 'https://api.example.org/' })
+ * axiosRetry(axios, { retries: 3 })
+ *
+ * await actorCalled('Apisitt')
+ *   .whoCan(
+ *     CallAnApi.using(instance)
+ *   )
+ *   .attemptsTo(
  *     Send.a(GetRequest.to('/users/2')),
  *     Ensure.that(LastResponse.status(), equals(200)),
  *   )
  * ```
  *
- * ## Using Axios client with custom configuration
+ * ### Using raw Axios instance
+ *
+ * If you don't want Serenity/JS to enhance your Axios instance with proxy support, instantiate the ability to
+ * `CallAnApi` using its constructor directly.
+ * Note, however, that by using this approach you're taking the responsibility for all the aspects of configuring Axios.
  *
  * ```ts
  * import { actorCalled } from '@serenity-js/core'
  * import { CallAnApi, GetRequest, LastResponse, Send } from '@serenity-js/rest'
  * import { Ensure, equals } from '@serenity-js/assertions'
  *
- * import * as axios from 'axios'
+ * import axios from 'axios'
+ * import axiosRetry from 'axios-retry'
+ *
+ * const instance = axios.create({ baseURL 'https://api.example.org/' })
+ * axiosRetry(axios, { retries: 3 })
+ *
+ * await actorCalled('Apisitt')
+ *   .whoCan(
+ *     new CallAnApi(instance)     // using the constructor ensures your axios instance is not modified in any way.
+ *   )
+ *   .attemptsTo(
+ *     // ...
+ *   )
+ * ```
+ *
+ * ### Serenity/JS defaults
+ *
+ * When using {@apilink CallAnApi.at} or {@apilink CallAnApi.using} with a configuration object, Serenity/JS
+ * merges your [Axios request configuration](https://axios-http.com/docs/req_config) with the following defaults:
+ * - `timeout`: 10 seconds
  *
- * const axiosInstance = axios.create({
- *   timeout: 5 * 1000,
- *   headers: {
- *     'X-Custom-Api-Key': 'secret-key',
- *   },
- * });
+ *
+ * You can override them by specifying the given property in your configuration object, for example:
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { CallAnApi, GetRequest, LastResponse, Send } from '@serenity-js/rest'
+ * import { Ensure, equals } from '@serenity-js/assertions'
  *
  * await actorCalled('Apisitt')
  *   .whoCan(
- *     CallAnApi.using(axiosInstance),
+ *     CallAnApi.using({
+ *       baseURL: 'https://api.example.org/',
+ *       timeout: 30_000
+ *     })
  *   )
  *   .attemptsTo(
  *     Send.a(GetRequest.to('/users/2')),
@@ -54,48 +233,162 @@ const axios_1 = __importDefault(require("axios"));
  *   )
  * ```
  *
+ * ## Interacting with multiple APIs
+ *
+ * Some test scenarios might require you to interact with multiple HTTP APIs. With Serenity/JS you can do this
+ * using either API-specific actors, or by specifying full URLs when performing the requests.
+ *
+ * The following examples will assume that the test scenarios needs to interact with the following APIs:
+ * - `https://testdata.example.org/api/v1/`
+ * - `https://shop.example.org/api/v1/`
+ *
+ * Let's also assume that the `testdata` API allows the automation to manage the test data used by the `shop` API.
+ *
+ * ### Using API-specific actors
+ *
+ * To create API-specific actors, configure your [test runner](/handbook/test-runners/) with a {@apilink Cast}
+ * that gives your actors appropriate abilities based, for example, on their name:
+ *
+ * ```ts
+ * import { beforeEach } from 'mocha'
+ * import { Actor, Cast, engage } from '@serenity-js/core'
+ * import { CallAnApi } from '@serenity-js/rest'
+ *
+ * export class MyActors implements Cast {
+ *   prepare(actor: Actor): Actor {
+ *     switch(actor.name) {
+ *       case 'Ted':
+ *         return actor.whoCan(CallAnApi.at('https://testdata.example.org/api/v1/'))
+ *       case 'Shelly':
+ *         return actor.whoCan(CallAnApi.at('https://shop.example.org/api/v1/'))
+ *       default:
+ *         return actor;
+ *     }
+ *   }
+ * }
+ *
+ * beforeEach(() => engage(new MyActors()))
+ * ```
+ *
+ * Next, retrieve the appropriate actor in your test scenario using {@apilink actorCalled}, for example:
+ *
+ * ```ts
+ * import { describe, it, beforeEach } from 'mocha'
+ * import { actorCalled, engage } from '@serenity-js/core
+ * import { Send, GetRequest, PostRequest, LastResponse } from '@serenity-js/rest'
+ * import { Ensure, equals } from '@serenity-js/assertions'
+ *
+ * describe('Multi-actor API testing', () => {
+ *   beforeEach(() => engage(new MyActors()))
+ *
+ *   it('allows each actor to interact with their API', async () => {
+ *
+ *     await actorCalled('Ted').attemptsTo(
+ *       Send.a(PostRequest.to('products').with({ name: 'Apples', price: '£2.50' })),
+ *       Ensure.that(LastResponse.status(), equals(201)),
+ *     )
+ *
+ *     await actorCalled('Shelly').attemptsTo(
+ *       Send.a(GetRequest.to('?product=Apples')),
+ *       Ensure.that(LastResponse.status(), equals(200)),
+ *       Ensure.that(LastResponse.body(), equals([
+ *         { name: 'Apples', price: '£2.50' }
+ *       ])),
+ *     )
+ *   })
+ * })
+ * ```
+ *
+ * ### Using full URLs
+ *
+ * If you prefer to have a single actor interacting with multiple APIs, you can specify the full URL for every request:
+ *
+ * ```ts
+ * import { describe, it, beforeEach } from 'mocha'
+ * import { actorCalled, Cast, engage } from '@serenity-js/core
+ * import { CallAnApi, Send, GetRequest, PostRequest, LastResponse } from '@serenity-js/rest'
+ * import { Ensure, equals } from '@serenity-js/assertions'
+ *
+ * describe('Multi-actor API testing', () => {
+ *   beforeEach(() => engage(
+ *     Cast.where(actor => actor.whoCan(CallAnApi.using({})))
+ *   ))
+ *
+ *   it('allows each actor to interact with their API', async () => {
+ *
+ *     await actorCalled('Alice').attemptsTo(
+ *       Send.a(PostRequest.to('https://testdata.example.org/api/v1/products')
+ *         .with({ name: 'Apples', price: '£2.50' })),
+ *       Ensure.that(LastResponse.status(), equals(201)),
+ *
+ *       Send.a(GetRequest.to('https://shop.example.org/api/v1/?product=Apples')),
+ *       Ensure.that(LastResponse.status(), equals(200)),
+ *       Ensure.that(LastResponse.body(), equals([
+ *         { name: 'Apples', price: '£2.50' }
+ *       ])),
+ *     )
+ *   })
+ * })
+ * ```
+ *
  * ## Learn more
- * - https://github.com/axios/axios
- * - https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods
+ * - [Axios: Configuring requests](https://axios-http.com/docs/req_config)
+ * - [MDN: HTTP methods documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods)
  *
  * @group Abilities
  */
 class CallAnApi extends core_1.Ability {
     /**
-     * Produces an {@apilink Ability|ability} to call a REST api at a specified baseUrl
-     *
-     * Default timeout is set to 2s.
+     * Produces an {@apilink Ability|ability} to call a REST API at a specified `baseURL`;
      *
-     * Default request headers:
-     * - `Accept`: `application/json,application/xml`
+     * This is the same as invoking `CallAnApi.using({ baseURL: 'https://example.org' })`
      *
      * @param baseURL
      */
     static at(baseURL) {
-        return new CallAnApi(axios_1.default.create({
-            baseURL,
-            timeout: 2000,
-            headers: { Accept: 'application/json,application/xml' },
-        }));
+        return CallAnApi.using({
+            baseURL: baseURL instanceof URL
+                ? baseURL.toString()
+                : baseURL
+        });
     }
     /**
-     * Produces an {@apilink Ability|ability} to call a REST API using a given axios instance.
+     * Produces an {@apilink Ability|ability} to call an HTTP API using the given Axios instance,
+     * or an Axios request configuration object.
      *
-     * Useful when you need to customise Axios to
-     * [make it aware of proxies](https://janmolak.com/node-js-axios-behind-corporate-proxies-8b17a6f31f9d),
-     * for example.
+     * When you provide an [Axios configuration object](https://axios-http.com/docs/req_config),
+     * it gets shallow-merged with the following defaults:
+     * - request timeout of 10 seconds
+     * - automatic proxy support based on
+     *   your [environment variables](https://www.npmjs.com/package/proxy-from-env#environment-variables)
      *
-     * #### Learn more
-     * - [AxiosInstance](https://github.com/axios/axios/blob/v0.27.2/index.d.ts#L235-L238)
+     * When you provide an Axios instance, it's enhanced with proxy support and no other modifications are made.
      *
-     * @param axiosInstance
+     * If you don't want Serenity/JS to augment or modify your Axios instance in any way,
+     * please use the {@apilink CallAnApi.constructor} directly.
+     *
+     * @param axiosInstanceOrConfig
      */
-    static using(axiosInstance) {
-        return new CallAnApi(axiosInstance);
+    static using(axiosInstanceOrConfig) {
+        const axiosInstanceGiven = isAxiosInstance(axiosInstanceOrConfig);
+        const axiosInstance = axiosInstanceGiven
+            ? axiosInstanceOrConfig
+            : axios_1.default.create({
+                ...CallAnApi.defaults,
+                ...omit(axiosInstanceOrConfig, 'proxy'),
+            });
+        const proxyConfig = axiosInstanceGiven
+            ? axiosInstanceOrConfig.defaults.proxy
+            : axiosInstanceOrConfig.proxy;
+        const proxyOverrides = (0, proxy_1.axiosProxyOverridesFor)({
+            ...axiosInstance.defaults,
+            proxy: proxyConfig || undefined,
+        });
+        return new CallAnApi(withOverrides(axiosInstance, proxyOverrides));
     }
     /**
      * #### Learn more
-     * - [AxiosInstance](https://github.com/axios/axios/blob/v0.27.2/index.d.ts#L235-L238)
+     * - [AxiosInstance](https://axios-http.com/docs/instance)
      *
      * @param axiosInstance
      *  A pre-configured instance of the Axios HTTP client
@@ -110,7 +403,7 @@ class CallAnApi extends core_1.Ability {
      * has been instantiated and given to the {@apilink Actor}.
      *
      * #### Learn more
-     * - [AxiosRequestConfig](https://github.com/axios/axios/blob/v0.27.2/index.d.ts#L75-L113)
+     * - [AxiosRequestConfig](https://axios-http.com/docs/req_config)
      *
      * @param fn
      */
@@ -122,8 +415,8 @@ class CallAnApi extends core_1.Ability {
      * Response will be cached and available via {@apilink mapLastResponse}
      *
      * #### Learn more
-     * - [AxiosRequestConfig](https://github.com/axios/axios/blob/v0.27.2/index.d.ts#L75-L113)
-     * - [AxiosResponse](https://github.com/axios/axios/blob/v0.27.2/index.d.ts#L133-L140)
+     * - [AxiosRequestConfig](https://axios-http.com/docs/req_config)
+     * - [AxiosResponse](https://axios-http.com/docs/res_schema)
      *
      * @param config
      *  Axios request configuration, which can be used to override the defaults
@@ -160,9 +453,8 @@ class CallAnApi extends core_1.Ability {
      * Resolves the final URL, based on the {@apilink AxiosRequestConfig} provided
      * and any defaults that the {@apilink AxiosInstance} has been configured with.
      *
-     * #### Learn more
-     * - [AxiosRequestConfig](https://github.com/axios/axios/blob/v0.27.2/index.d.ts#L75-L113)
-     * - [AxiosInstance](https://github.com/axios/axios/blob/v0.27.2/index.d.ts#L235-L238)
+     * Note that unlike Axios, this method uses the Node.js [WHATWG URL API](https://nodejs.org/api/url.html#new-urlinput-base)
+     * to ensure URLs are correctly resolved.
      *
      * @param config
      */
@@ -177,7 +469,7 @@ class CallAnApi extends core_1.Ability {
      * Useful when you need to extract a portion of the {@apilink AxiosResponse} object.
      *
      * #### Learn more
-     * - [AxiosResponse](https://github.com/axios/axios/blob/v0.27.2/index.d.ts#L133-L140)
+     * - [AxiosResponse](https://axios-http.com/docs/res_schema)
      *
      * @param mappingFunction
      */
@@ -189,4 +481,21 @@ class CallAnApi extends core_1.Ability {
     }
 }
 exports.CallAnApi = CallAnApi;
+CallAnApi.defaults = {
+    timeout: core_1.Duration.ofSeconds(10).inMilliseconds(),
+};
+function isAxiosInstance(axiosInstanceOrConfig) {
+    return axiosInstanceOrConfig
+        && (axiosInstanceOrConfig instanceof axios_1.Axios || axiosInstanceOrConfig.defaults);
+}
+function withOverrides(axiosInstance, overrides) {
+    for (const [key, override] of Object.entries(overrides)) {
+        axiosInstance.defaults[key] = override;
+    }
+    return axiosInstance;
+}
+function omit(record, key) {
+    const { [key]: omitted_, ...rest } = record;
+    return rest;
+}
 //# sourceMappingURL=CallAnApi.js.map

package/lib/screenplay/abilities/CallAnApi.js.map

@@ -1 +1 @@
-{"version":3,"file":"CallAnApi.js","sourceRoot":"","sources":["../../../src/screenplay/abilities/CallAnApi.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"CallAnApi.js","sourceRoot":"","sources":["../../../src/screenplay/abilities/CallAnApi.ts"],"names":[],"mappings":"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"}

package/lib/screenplay/abilities/index.d.ts

@@ -1,2 +1,3 @@
+export * from './AxiosRequestConfigDefaults';
 export * from './CallAnApi';
 //# sourceMappingURL=index.d.ts.map

package/lib/screenplay/abilities/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/screenplay/abilities/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/screenplay/abilities/index.ts"],"names":[],"mappings":"AAAA,cAAc,8BAA8B,CAAC;AAC7C,cAAc,aAAa,CAAC"}

package/lib/screenplay/abilities/index.js

@@ -14,5 +14,6 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./AxiosRequestConfigDefaults"), exports);
 __exportStar(require("./CallAnApi"), exports);
 //# sourceMappingURL=index.js.map

package/lib/screenplay/abilities/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/screenplay/abilities/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,8CAA4B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/screenplay/abilities/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,+DAA6C;AAC7C,8CAA4B"}

package/lib/screenplay/abilities/proxy/ProxyAgent.d.ts

@@ -0,0 +1,55 @@
+/// <reference types="node" />
+import type { AgentConnectOpts } from 'agent-base';
+import { Agent } from 'agent-base';
+import * as http from 'http';
+import { type HttpProxyAgentOptions } from 'http-proxy-agent';
+import { type HttpsProxyAgentOptions } from 'https-proxy-agent';
+type GetProxyForUrlCallback = (url: string) => string;
+export type ProxyAgentOptions = HttpProxyAgentOptions<''> & HttpsProxyAgentOptions<''> & {
+    /**
+     * Default `http.Agent` instance to use when no proxy is
+     * configured for a request. Defaults to a new `http.Agent()`
+     * instance with the proxy agent options passed in.
+     */
+    httpAgent?: http.Agent;
+    /**
+     * Default `http.Agent` instance to use when no proxy is
+     * configured for a request. Defaults to a new `https.Agent()`
+     * instance with the proxy agent options passed in.
+     */
+    httpsAgent?: http.Agent;
+    /**
+     * A callback for dynamic provision of proxy for url.
+     * Defaults to standard proxy environment variables,
+     * see https://www.npmjs.com/package/proxy-from-env for details
+     */
+    getProxyForUrl?: GetProxyForUrlCallback;
+};
+/**
+ * A simplified version of the original
+ * [`ProxyAgent`](https://github.com/TooTallNate/proxy-agents/blob/5923589c2e5206504772c250ac4f20fc31122d3b/packages/proxy-agent/src/index.ts)
+ * with fewer dependencies.
+ *
+ * Delegates requests to the appropriate `Agent` subclass based on the "proxy"
+ * environment variables, or the provided `agentOptions.getProxyForUrl` callback.
+ *
+ * Uses an LRU cache to prevent unnecessary creation of proxy `http.Agent` instances.
+ */
+export declare class ProxyAgent extends Agent {
+    private readonly agentOptions;
+    private static proxyAgents;
+    /**
+     * Cache for `Agent` instances.
+     */
+    private readonly cache;
+    private readonly httpAgent;
+    private readonly httpsAgent;
+    private readonly getProxyForUrl;
+    constructor(agentOptions: ProxyAgentOptions);
+    connect(request: http.ClientRequest, options: AgentConnectOpts): Promise<http.Agent>;
+    private createAgent;
+    private isValidProtocol;
+    destroy(): void;
+}
+export {};
+//# sourceMappingURL=ProxyAgent.d.ts.map

package/lib/screenplay/abilities/proxy/ProxyAgent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProxyAgent.d.ts","sourceRoot":"","sources":["../../../../src/screenplay/abilities/proxy/ProxyAgent.ts"],"names":[],"mappings":";AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,EAAkB,KAAK,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAE9E,OAAO,EAAmB,KAAK,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAYjF,KAAK,sBAAsB,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC;AAEtD,MAAM,MAAM,iBAAiB,GACzB,qBAAqB,CAAC,EAAE,CAAC,GACzB,sBAAsB,CAAC,EAAE,CAAC,GAAG;IACzB;;;;OAIG;IACH,SAAS,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC;IACvB;;;;OAIG;IACH,UAAU,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC;IACxB;;;;OAIG;IACH,cAAc,CAAC,EAAE,sBAAsB,CAAC;CAC3C,CAAC;AAEN;;;;;;;;;GASG;AACH,qBAAa,UAAW,SAAQ,KAAK;IAmBrB,OAAO,CAAC,QAAQ,CAAC,YAAY;IAjBzC,OAAO,CAAC,MAAM,CAAC,WAAW,CAGxB;IAEF;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,KAAK,CAGnB;IAEH,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAa;IACvC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAa;IACxC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAyB;gBAE3B,YAAY,EAAE,iBAAiB;IAO7C,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,aAAa,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC;IA4BnG,OAAO,CAAC,WAAW;IAanB,OAAO,CAAC,eAAe;IAId,OAAO,IAAI,IAAI;CAI3B"}