@serenity-js/rest 3.18.1 → 3.20.0

package/CHANGELOG.md

@@ -3,6 +3,25 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [3.20.0](https://github.com/serenity-js/serenity-js/compare/v3.19.0...v3.20.0) (2024-03-02)
+
+
+### Features
+
+* **rest:** createAxios function instantiates axios with HTTP proxy support ([c453678](https://github.com/serenity-js/serenity-js/commit/c4536784c0bd9e77826563b944904fb862c43c83))
+
+
+
+
+
+# [3.19.0](https://github.com/serenity-js/serenity-js/compare/v3.18.1...v3.19.0) (2024-03-01)
+
+**Note:** Version bump only for package @serenity-js/rest
+
+
+
+
+
 ## [3.18.1](https://github.com/serenity-js/serenity-js/compare/v3.18.0...v3.18.1) (2024-02-23)
 
 **Note:** Version bump only for package @serenity-js/rest

package/lib/index.d.ts

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

package/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,MAAM,CAAC;AACrB,cAAc,cAAc,CAAC"}

package/lib/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("./io"), exports);
 __exportStar(require("./screenplay"), exports);
 //# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,+CAA6B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,uCAAqB;AACrB,+CAA6B"}

package/lib/io/AxiosRequestConfigDefaults.d.ts

@@ -0,0 +1,14 @@
+import { type CreateAxiosDefaults } from 'axios';
+export type AxiosRequestConfigProxyDefaults = {
+    host: string;
+    port?: number;
+    auth?: {
+        username: string;
+        password: string;
+    };
+    protocol?: string;
+};
+export type AxiosRequestConfigDefaults<Data = any> = Omit<CreateAxiosDefaults<Data>, 'proxy'> & {
+    proxy?: AxiosRequestConfigProxyDefaults | false;
+};
+//# sourceMappingURL=AxiosRequestConfigDefaults.d.ts.map

package/lib/io/AxiosRequestConfigDefaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AxiosRequestConfigDefaults.d.ts","sourceRoot":"","sources":["../../src/io/AxiosRequestConfigDefaults.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,mBAAmB,EAAE,MAAM,OAAO,CAAC;AAEjD,MAAM,MAAM,+BAA+B,GAAG;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE;QACH,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;KACpB,CAAC;IACF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB,CAAA;AAED,MAAM,MAAM,0BAA0B,CAAC,IAAI,GAAG,GAAG,IAAI,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,GAAG;IAC5F,KAAK,CAAC,EAAE,+BAA+B,GAAG,KAAK,CAAC;CACnD,CAAA"}

package/lib/io/AxiosRequestConfigDefaults.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=AxiosRequestConfigDefaults.js.map

package/lib/io/AxiosRequestConfigDefaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AxiosRequestConfigDefaults.js","sourceRoot":"","sources":["../../src/io/AxiosRequestConfigDefaults.ts"],"names":[],"mappings":""}

package/lib/io/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/io/ProxyAgent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProxyAgent.d.ts","sourceRoot":"","sources":["../../src/io/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"}

package/lib/io/ProxyAgent.js

@@ -0,0 +1,111 @@
+"use strict";
+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.ProxyAgent = void 0;
+const core_1 = require("@serenity-js/core");
+const agent_base_1 = require("agent-base");
+const http = __importStar(require("http"));
+const http_proxy_agent_1 = require("http-proxy-agent");
+const https = __importStar(require("https"));
+const https_proxy_agent_1 = require("https-proxy-agent");
+const lru_cache_1 = require("lru-cache");
+const proxy_from_env_1 = require("proxy-from-env");
+const protocols = [
+    ...http_proxy_agent_1.HttpProxyAgent.protocols,
+];
+/**
+ * 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.
+ */
+class ProxyAgent extends agent_base_1.Agent {
+    agentOptions;
+    static proxyAgents = {
+        http: [http_proxy_agent_1.HttpProxyAgent, https_proxy_agent_1.HttpsProxyAgent],
+        https: [http_proxy_agent_1.HttpProxyAgent, https_proxy_agent_1.HttpsProxyAgent],
+    };
+    /**
+     * Cache for `Agent` instances.
+     */
+    cache = new lru_cache_1.LRUCache({
+        max: 20,
+        dispose: (value, key) => value.destroy(),
+    });
+    httpAgent;
+    httpsAgent;
+    getProxyForUrl;
+    constructor(agentOptions) {
+        super(agentOptions);
+        this.agentOptions = agentOptions;
+        this.httpAgent = agentOptions?.httpAgent || new http.Agent(agentOptions);
+        this.httpsAgent = agentOptions?.httpsAgent || new https.Agent(agentOptions);
+        this.getProxyForUrl = agentOptions?.getProxyForUrl || proxy_from_env_1.getProxyForUrl;
+    }
+    async connect(request, options) {
+        const { secureEndpoint } = options;
+        const isWebSocket = request.getHeader('upgrade') === 'websocket';
+        const protocol = secureEndpoint
+            ? (isWebSocket ? 'wss:' : 'https:')
+            : (isWebSocket ? 'ws:' : 'http:');
+        const host = request.getHeader('host');
+        const url = new URL(request.path, `${protocol}//${host}`).href;
+        const proxy = this.getProxyForUrl(url);
+        if (!proxy) {
+            return secureEndpoint
+                ? this.httpsAgent
+                : this.httpAgent;
+        }
+        // attempt to get a cached `http.Agent` instance first
+        const cacheKey = `${protocol}+${proxy}`;
+        let agent = this.cache.get(cacheKey);
+        if (!agent) {
+            agent = this.createAgent(new URL(proxy), secureEndpoint || isWebSocket);
+            this.cache.set(cacheKey, agent);
+        }
+        return agent;
+    }
+    createAgent(proxyUrl, requiresTls) {
+        const protocol = proxyUrl.protocol.replace(':', '');
+        if (!this.isValidProtocol(protocol)) {
+            throw new core_1.ConfigurationError(`Unsupported protocol for proxy URL: ${proxyUrl}`);
+        }
+        const ctor = ProxyAgent.proxyAgents[protocol][requiresTls ? 1 : 0];
+        return new ctor(proxyUrl, this.agentOptions);
+    }
+    isValidProtocol(v) {
+        return protocols.includes(v);
+    }
+    destroy() {
+        this.cache.clear();
+        super.destroy();
+    }
+}
+exports.ProxyAgent = ProxyAgent;
+//# sourceMappingURL=ProxyAgent.js.map

package/lib/io/ProxyAgent.js.map

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

package/lib/io/axiosProxyOverridesFor.d.ts

@@ -0,0 +1,12 @@
+/// <reference types="node" />
+import type * as http from 'http';
+import type { AxiosRequestConfigDefaults } from './AxiosRequestConfigDefaults';
+/**
+ * @param options
+ */
+export declare function axiosProxyOverridesFor<Data = any>(options: AxiosRequestConfigDefaults<Data>): {
+    proxy: false;
+    httpAgent: http.Agent;
+    httpsAgent: http.Agent;
+};
+//# sourceMappingURL=axiosProxyOverridesFor.d.ts.map

package/lib/io/axiosProxyOverridesFor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"axiosProxyOverridesFor.d.ts","sourceRoot":"","sources":["../../src/io/axiosProxyOverridesFor.ts"],"names":[],"mappings":";AAAA,OAAO,KAAK,KAAK,IAAI,MAAM,MAAM,CAAC;AAGlC,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,8BAA8B,CAAC;AAI/E;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,GAAG,GAAG,EAAE,OAAO,EAAE,0BAA0B,CAAC,IAAI,CAAC,GAAG;IAC3F,KAAK,EAAE,KAAK,CAAC;IAAC,SAAS,EAAE,IAAI,CAAC,KAAK,CAAC;IAAC,UAAU,EAAE,IAAI,CAAC,KAAK,CAAA;CAC9D,CA0BA"}

package/lib/io/axiosProxyOverridesFor.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.axiosProxyOverridesFor = void 0;
+const tiny_types_1 = require("tiny-types");
+const createUrl_1 = require("./createUrl");
+const ProxyAgent_1 = require("./ProxyAgent");
+/**
+ * @param options
+ */
+function axiosProxyOverridesFor(options) {
+    const envProxyOverride = options.proxy
+        && (0, createUrl_1.createUrl)({
+            username: options.proxy?.auth?.username,
+            password: options.proxy?.auth?.password,
+            protocol: options.proxy?.protocol,
+            hostname: (0, tiny_types_1.ensure)('proxy.host', options.proxy?.host, (0, tiny_types_1.isDefined)()),
+            port: options.proxy?.port
+        }).toString();
+    const agent = new ProxyAgent_1.ProxyAgent({
+        httpAgent: options.httpAgent,
+        httpsAgent: options.httpsAgent,
+        // if there's a specific proxy override configured, use it
+        // if not - detect proxy automatically based on env variables
+        getProxyForUrl: envProxyOverride
+            ? (url_) => envProxyOverride
+            : undefined,
+    });
+    return {
+        proxy: false,
+        httpAgent: agent,
+        httpsAgent: agent,
+    };
+}
+exports.axiosProxyOverridesFor = axiosProxyOverridesFor;
+//# sourceMappingURL=axiosProxyOverridesFor.js.map

package/lib/io/axiosProxyOverridesFor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"axiosProxyOverridesFor.js","sourceRoot":"","sources":["../../src/io/axiosProxyOverridesFor.ts"],"names":[],"mappings":";;;AACA,2CAA+C;AAG/C,2CAAwC;AACxC,6CAA0C;AAE1C;;GAEG;AACH,SAAgB,sBAAsB,CAAa,OAAyC;IAGxF,MAAM,gBAAgB,GAAmB,OAAO,CAAC,KAAK;WAC/C,IAAA,qBAAS,EAAC;YACT,QAAQ,EAAE,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE,QAAQ;YACvC,QAAQ,EAAE,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE,QAAQ;YACvC,QAAQ,EAAE,OAAO,CAAC,KAAK,EAAE,QAAQ;YACjC,QAAQ,EAAE,IAAA,mBAAM,EAAC,YAAY,EAAE,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE,IAAA,sBAAS,GAAE,CAAC;YAChE,IAAI,EAAE,OAAO,CAAC,KAAK,EAAE,IAAI;SAC5B,CAAC,CAAC,QAAQ,EAAE,CAAC;IAElB,MAAM,KAAK,GAAG,IAAI,uBAAU,CAAC;QACzB,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,UAAU,EAAE,OAAO,CAAC,UAAU;QAE9B,0DAA0D;QAC1D,6DAA6D;QAC7D,cAAc,EAAE,gBAAgB;YAC5B,CAAC,CAAC,CAAC,IAAY,EAAE,EAAE,CAAC,gBAAgB;YACpC,CAAC,CAAC,SAAS;KAClB,CAAC,CAAC;IAEH,OAAO;QACH,KAAK,EAAE,KAAK;QACZ,SAAS,EAAE,KAAK;QAChB,UAAU,EAAE,KAAK;KACpB,CAAC;AACN,CAAC;AA5BD,wDA4BC"}

package/lib/io/createAxios.d.ts

@@ -0,0 +1,9 @@
+import { type AxiosInstance } from 'axios';
+import type { AxiosRequestConfigDefaults } from './AxiosRequestConfigDefaults';
+/**
+ * Creates an Axios instance with desired configuration and proxy support.
+ *
+ * @param axiosInstanceOrConfig
+ */
+export declare function createAxios(axiosInstanceOrConfig?: AxiosInstance | AxiosRequestConfigDefaults): AxiosInstance;
+//# sourceMappingURL=createAxios.d.ts.map

package/lib/io/createAxios.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createAxios.d.ts","sourceRoot":"","sources":["../../src/io/createAxios.ts"],"names":[],"mappings":"AACA,OAAc,EAAS,KAAK,aAAa,EAA2B,MAAM,OAAO,CAAC;AAGlF,OAAO,KAAK,EAAE,0BAA0B,EAAmC,MAAM,8BAA8B,CAAC;AAEhH;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,qBAAqB,GAAE,aAAa,GAAG,0BAA+B,GAAG,aAAa,CAoBjH"}

package/lib/io/createAxios.js

@@ -0,0 +1,67 @@
+"use strict";
+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.createAxios = void 0;
+const core_1 = require("@serenity-js/core");
+const axios_1 = __importStar(require("axios"));
+const axiosProxyOverridesFor_1 = require("./axiosProxyOverridesFor");
+/**
+ * Creates an Axios instance with desired configuration and proxy support.
+ *
+ * @param axiosInstanceOrConfig
+ */
+function createAxios(axiosInstanceOrConfig = {}) {
+    const axiosInstanceGiven = isAxiosInstance(axiosInstanceOrConfig);
+    const axiosInstance = axiosInstanceGiven
+        ? axiosInstanceOrConfig
+        : axios_1.default.create({
+            timeout: core_1.Duration.ofSeconds(10).inMilliseconds(),
+            ...omit(axiosInstanceOrConfig, 'proxy'),
+        });
+    const proxyConfig = axiosInstanceGiven
+        ? axiosInstanceOrConfig.defaults.proxy
+        : axiosInstanceOrConfig.proxy;
+    const proxyOverrides = (0, axiosProxyOverridesFor_1.axiosProxyOverridesFor)({
+        ...axiosInstance.defaults,
+        proxy: proxyConfig || undefined,
+    });
+    return withOverrides(axiosInstance, proxyOverrides);
+}
+exports.createAxios = createAxios;
+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=createAxios.js.map

package/lib/io/createAxios.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createAxios.js","sourceRoot":"","sources":["../../src/io/createAxios.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,4CAA6C;AAC7C,+CAAkF;AAElF,qEAAkE;AAGlE;;;;GAIG;AACH,SAAgB,WAAW,CAAC,wBAAoE,EAAE;IAC9F,MAAM,kBAAkB,GAAG,eAAe,CAAC,qBAAqB,CAAC,CAAC;IAElE,MAAM,aAAa,GAAG,kBAAkB;QACpC,CAAC,CAAC,qBAAqB;QACvB,CAAC,CAAC,eAAK,CAAC,MAAM,CAAC;YACX,OAAO,EAAE,eAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,cAAc,EAAE;YAChD,GAAG,IAAI,CAAC,qBAAqB,EAAE,OAAO,CAAC;SAC1C,CAAC,CAAC;IAEP,MAAM,WAAW,GAAwD,kBAAkB;QACvF,CAAC,CAAC,qBAAqB,CAAC,QAAQ,CAAC,KAAK;QACtC,CAAC,CAAC,qBAAqB,CAAC,KAAK,CAAC;IAElC,MAAM,cAAc,GAAG,IAAA,+CAAsB,EAAC;QAC1C,GAAG,aAAa,CAAC,QAAQ;QACzB,KAAK,EAAE,WAAW,IAAI,SAAS;KAClC,CAAC,CAAC;IAEH,OAAO,aAAa,CAAC,aAAa,EAAE,cAAc,CAAC,CAAC;AACxD,CAAC;AApBD,kCAoBC;AAED,SAAS,eAAe,CAAC,qBAA0B;IAC/C,OAAO,qBAAqB;WACrB,CAAC,qBAAqB,YAAY,aAAK,IAAI,qBAAqB,CAAC,QAAQ,CAAC,CAAC;AACtF,CAAC;AAED,SAAS,aAAa,CAAa,aAA4B,EAAE,SAAmC;IAChG,KAAK,MAAM,CAAC,GAAG,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE;QACrD,aAAa,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC;KAC1C;IAED,OAAO,aAAa,CAAC;AACzB,CAAC;AAED,SAAS,IAAI,CAAsC,MAAS,EAAE,GAAM;IAChE,MAAM,EAAE,CAAC,GAAG,CAAC,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,GAAG,MAAM,CAAC;IAC5C,OAAO,IAAI,CAAC;AAChB,CAAC"}

package/lib/io/createUrl.d.ts

@@ -0,0 +1,10 @@
+/// <reference types="node" />
+export interface CreateUrlOptions {
+    protocol?: string;
+    hostname: string;
+    port?: string | number;
+    username?: string;
+    password?: string;
+}
+export declare function createUrl(options: CreateUrlOptions): URL;
+//# sourceMappingURL=createUrl.d.ts.map

package/lib/io/createUrl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createUrl.d.ts","sourceRoot":"","sources":["../../src/io/createUrl.ts"],"names":[],"mappings":";AAEA,MAAM,WAAW,gBAAgB;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,wBAAgB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,GAAG,CAYxD"}

package/lib/io/createUrl.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createUrl = void 0;
+const tiny_types_1 = require("tiny-types");
+function createUrl(options) {
+    const hostname = (0, tiny_types_1.ensure)('hostname', options?.hostname, (0, tiny_types_1.isString)(), (0, tiny_types_1.isNotBlank)()).trim();
+    const port = options?.port
+        ? ':' + options?.port
+        : (options?.protocol ? undefined : ':80');
+    return new URL([
+        options?.protocol && protocolFrom(options?.protocol),
+        (options?.username || options?.password) && credentialsFrom(options.username, options.password),
+        hostname,
+        port,
+    ].filter(Boolean).join(''));
+}
+exports.createUrl = createUrl;
+function protocolFrom(protocol) {
+    const protocolName = protocol.match(/([A-Za-z]+)[/:]*/)[1];
+    (0, tiny_types_1.ensure)('hostname', protocolName, (0, tiny_types_1.isDefined)());
+    return protocolName + '://';
+}
+function credentialsFrom(username, password) {
+    return [
+        username && encodeURIComponent(username),
+        password && ':' + encodeURIComponent(password),
+        '@'
+    ].filter(Boolean).join('');
+}
+//# sourceMappingURL=createUrl.js.map

package/lib/io/createUrl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createUrl.js","sourceRoot":"","sources":["../../src/io/createUrl.ts"],"names":[],"mappings":";;;AAAA,2CAAqE;AAUrE,SAAgB,SAAS,CAAC,OAAyB;IAC/C,MAAM,QAAQ,GAAI,IAAA,mBAAM,EAAC,UAAU,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAA,qBAAQ,GAAE,EAAE,IAAA,uBAAU,GAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACzF,MAAM,IAAI,GAAQ,OAAO,EAAE,IAAI;QAC3B,CAAC,CAAC,GAAG,GAAG,OAAO,EAAE,IAAI;QACrB,CAAC,CAAC,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IAE9C,OAAO,IAAI,GAAG,CAAC;QACX,OAAO,EAAE,QAAQ,IAAI,YAAY,CAAC,OAAO,EAAE,QAAQ,CAAC;QACpD,CAAC,OAAO,EAAE,QAAQ,IAAI,OAAO,EAAE,QAAQ,CAAC,IAAI,eAAe,CAAC,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC;QAC/F,QAAQ;QACR,IAAI;KACP,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;AAChC,CAAC;AAZD,8BAYC;AAED,SAAS,YAAY,CAAC,QAAiB;IACnC,MAAM,YAAY,GAAG,QAAQ,CAAC,KAAK,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAC;IAE3D,IAAA,mBAAM,EAAC,UAAU,EAAE,YAAY,EAAE,IAAA,sBAAS,GAAE,CAAC,CAAC;IAE9C,OAAO,YAAY,GAAG,KAAK,CAAC;AAChC,CAAC;AAED,SAAS,eAAe,CAAC,QAAiB,EAAE,QAAiB;IACzD,OAAO;QACH,QAAQ,IAAI,kBAAkB,CAAC,QAAQ,CAAC;QACxC,QAAQ,IAAI,GAAG,GAAG,kBAAkB,CAAC,QAAQ,CAAC;QAC9C,GAAG;KACN,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AAC/B,CAAC"}

package/lib/io/index.d.ts

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

package/lib/io/index.d.ts.map

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

package/lib/io/index.js

@@ -0,0 +1,19 @@
+"use strict";
+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 __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("./createAxios"), exports);
+//# sourceMappingURL=index.js.map

package/lib/io/index.js.map

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

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

@@ -1,7 +1,7 @@
 /// <reference types="node" />
 import { Ability } from '@serenity-js/core';
 import { type AxiosDefaults, type AxiosInstance, type AxiosRequestConfig, type AxiosResponse } from 'axios';
-import type { AxiosRequestConfigDefaults } from './AxiosRequestConfigDefaults';
+import type { AxiosRequestConfigDefaults } from '../../io';
 /**
  * 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.
@@ -137,14 +137,13 @@ import type { AxiosRequestConfigDefaults } from './AxiosRequestConfigDefaults';
  *
  * ```ts
  * import { actorCalled } from '@serenity-js/core'
- * import { CallAnApi, GetRequest, LastResponse, Send } from '@serenity-js/rest'
+ * import { createAxios, 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 })
+ * const instance = createAxios({ baseURL 'https://api.example.org/' })
+ * axiosRetry(instance, { retries: 3 })
  *
  * await actorCalled('Apisitt')
  *   .whoCan(
@@ -167,11 +166,11 @@ import type { AxiosRequestConfigDefaults } from './AxiosRequestConfigDefaults';
  * import { CallAnApi, GetRequest, LastResponse, Send } from '@serenity-js/rest'
  * import { Ensure, equals } from '@serenity-js/assertions'
  *
- * import axios from 'axios'
+ * import { axiosCreate } from '@serenity-js/rest'
  * import axiosRetry from 'axios-retry'
  *
- * const instance = axios.create({ baseURL 'https://api.example.org/' })
- * axiosRetry(axios, { retries: 3 })
+ * const instance = axiosCreate({ baseURL 'https://api.example.org/' })
+ * axiosRetry(instance, { retries: 3 })
  *
  * await actorCalled('Apisitt')
  *   .whoCan(
@@ -315,7 +314,6 @@ import type { AxiosRequestConfigDefaults } from './AxiosRequestConfigDefaults';
 export declare class CallAnApi extends Ability {
     private readonly axiosInstance;
     private lastResponse;
-    private static readonly defaults;
     /**
      * Produces an {@apilink Ability|ability} to call a REST API at a specified `baseURL`;
      *

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

@@ -1 +1 @@
-{"version":3,"file":"CallAnApi.d.ts","sourceRoot":"","sources":["../../../src/screenplay/abilities/CallAnApi.ts"],"names":[],"mappings":";AAAA,OAAO,EAAE,OAAO,EAAkE,MAAM,mBAAmB,CAAC;AAC5G,OAAc,EAEV,KAAK,aAAa,EAElB,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAErB,MAAM,OAAO,CAAC;AAEf,OAAO,KAAK,EAAE,0BAA0B,EAAmC,MAAM,8BAA8B,CAAC;AAGhH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqTG;AACH,qBAAa,SAAU,SAAQ,OAAO;IAsEtB,OAAO,CAAC,QAAQ,CAAC,aAAa;IApE1C,OAAO,CAAC,YAAY,CAAgB;IAEpC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAE9B;IAEF;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,GAAG,MAAM,GAAG,SAAS;IAQ3C;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,KAAK,CAAC,qBAAqB,EAAE,aAAa,GAAG,0BAA0B,GAAG,SAAS;IAuB1F;;;;;;OAMG;gBAC0B,aAAa,EAAE,aAAa;IAIzD;;;;;;;;;OASG;IACH,YAAY,CAAC,EAAE,EAAE,CAAC,QAAQ,EAAE,aAAa,CAAC,GAAG,CAAC,KAAK,GAAG,GAAG,IAAI;IAI7D;;;;;;;;;;;OAWG;IACG,OAAO,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,aAAa,CAAC;IAgCjE;;;;;;;;OAQG;IACH,UAAU,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM;IAQ9C;;;;;;;;OAQG;IACH,eAAe,CAAC,CAAC,EAAE,eAAe,EAAE,CAAC,QAAQ,EAAE,aAAa,KAAK,CAAC,GAAG,CAAC;CAOzE"}
+{"version":3,"file":"CallAnApi.d.ts","sourceRoot":"","sources":["../../../src/screenplay/abilities/CallAnApi.ts"],"names":[],"mappings":";AAAA,OAAO,EAAE,OAAO,EAAwD,MAAM,mBAAmB,CAAC;AAClG,OAAO,EACH,KAAK,aAAa,EAElB,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,aAAa,EACrB,MAAM,OAAO,CAAC;AAEf,OAAO,KAAK,EAAE,0BAA0B,EAAC,MAAM,UAAU,CAAC;AAG1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoTG;AACH,qBAAa,SAAU,SAAQ,OAAO;IA+CtB,OAAO,CAAC,QAAQ,CAAC,aAAa;IA7C1C,OAAO,CAAC,YAAY,CAAgB;IAEpC;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,GAAG,MAAM,GAAG,SAAS;IAQ3C;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,KAAK,CAAC,qBAAqB,EAAE,aAAa,GAAG,0BAA0B,GAAG,SAAS;IAI1F;;;;;;OAMG;gBAC0B,aAAa,EAAE,aAAa;IAIzD;;;;;;;;;OASG;IACH,YAAY,CAAC,EAAE,EAAE,CAAC,QAAQ,EAAE,aAAa,CAAC,GAAG,CAAC,KAAK,GAAG,GAAG,IAAI;IAI7D;;;;;;;;;;;OAWG;IACG,OAAO,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,aAAa,CAAC;IAgCjE;;;;;;;;OAQG;IACH,UAAU,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM;IAQ9C;;;;;;;;OAQG;IACH,eAAe,CAAC,CAAC,EAAE,eAAe,EAAE,CAAC,QAAQ,EAAE,aAAa,KAAK,CAAC,GAAG,CAAC;CAOzE"}

package/lib/screenplay/abilities/CallAnApi.js

@@ -1,32 +1,8 @@
 "use strict";
-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 = __importStar(require("axios"));
-const proxy_1 = require("./proxy");
+const io_1 = require("../../io");
 /**
  * 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.
@@ -162,14 +138,13 @@ const proxy_1 = require("./proxy");
  *
  * ```ts
  * import { actorCalled } from '@serenity-js/core'
- * import { CallAnApi, GetRequest, LastResponse, Send } from '@serenity-js/rest'
+ * import { createAxios, 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 })
+ * const instance = createAxios({ baseURL 'https://api.example.org/' })
+ * axiosRetry(instance, { retries: 3 })
  *
  * await actorCalled('Apisitt')
  *   .whoCan(
@@ -192,11 +167,11 @@ const proxy_1 = require("./proxy");
  * import { CallAnApi, GetRequest, LastResponse, Send } from '@serenity-js/rest'
  * import { Ensure, equals } from '@serenity-js/assertions'
  *
- * import axios from 'axios'
+ * import { axiosCreate } from '@serenity-js/rest'
  * import axiosRetry from 'axios-retry'
  *
- * const instance = axios.create({ baseURL 'https://api.example.org/' })
- * axiosRetry(axios, { retries: 3 })
+ * const instance = axiosCreate({ baseURL 'https://api.example.org/' })
+ * axiosRetry(instance, { retries: 3 })
  *
  * await actorCalled('Apisitt')
  *   .whoCan(
@@ -340,9 +315,6 @@ const proxy_1 = require("./proxy");
 class CallAnApi extends core_1.Ability {
     axiosInstance;
     lastResponse;
-    static defaults = {
-        timeout: core_1.Duration.ofSeconds(10).inMilliseconds(),
-    };
     /**
      * Produces an {@apilink Ability|ability} to call a REST API at a specified `baseURL`;
      *
@@ -375,21 +347,7 @@ class CallAnApi extends core_1.Ability {
      * @param axiosInstanceOrConfig
      */
     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));
+        return new CallAnApi((0, io_1.createAxios)(axiosInstanceOrConfig));
     }
     /**
      * #### Learn more
@@ -486,18 +444,4 @@ class CallAnApi extends core_1.Ability {
     }
 }
 exports.CallAnApi = CallAnApi;
-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,3 +1,2 @@
-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,8BAA8B,CAAC;AAC7C,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/screenplay/abilities/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC"}

package/lib/screenplay/abilities/index.js

@@ -14,6 +14,5 @@ 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,+DAA6C;AAC7C,8CAA4B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/screenplay/abilities/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,8CAA4B"}

package/lib/screenplay/interactions/ChangeApiConfig.d.ts

@@ -9,7 +9,7 @@ import { Interaction } from '@serenity-js/core';
  * ```ts
  * import { actorCalled } from '@serenity-js/core';
  * import { By Navigate, PageElement, Text } from '@serenity-js/web';
- * import { CallAnApi, ChangeApiConfig, GetRequest, LastResponse, Send } from '@serenity-js/rest'
+ * import { axiosCreate, CallAnApi, ChangeApiConfig, GetRequest, LastResponse, Send } from '@serenity-js/rest'
  * import { Ensure, equals } from '@serenity-js/assertions';
  *
  * import * as axios from 'axios';
@@ -25,7 +25,7 @@ import { Interaction } from '@serenity-js/core';
  *     BrowseTheWeb.using(protractor.browser),
  *
  *     // Note: no default base URL is given when the axios instance is created
- *     CallAnApi.using(axios.create()),
+ *     CallAnApi.using(axiosCreate()),
  *   )
  *   .attemptsTo(
  *     Navigate.to('/profile'),

package/lib/screenplay/interactions/ChangeApiConfig.js

@@ -13,7 +13,7 @@ const abilities_1 = require("../abilities");
  * ```ts
  * import { actorCalled } from '@serenity-js/core';
  * import { By Navigate, PageElement, Text } from '@serenity-js/web';
- * import { CallAnApi, ChangeApiConfig, GetRequest, LastResponse, Send } from '@serenity-js/rest'
+ * import { axiosCreate, CallAnApi, ChangeApiConfig, GetRequest, LastResponse, Send } from '@serenity-js/rest'
  * import { Ensure, equals } from '@serenity-js/assertions';
  *
  * import * as axios from 'axios';
@@ -29,7 +29,7 @@ const abilities_1 = require("../abilities");
  *     BrowseTheWeb.using(protractor.browser),
  *
  *     // Note: no default base URL is given when the axios instance is created
- *     CallAnApi.using(axios.create()),
+ *     CallAnApi.using(axiosCreate()),
  *   )
  *   .attemptsTo(
  *     Navigate.to('/profile'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serenity-js/rest",
-  "version": "3.18.1",
+  "version": "3.20.0",
   "description": "Test REST APIs with Serenity/JS",
   "author": {
     "name": "Jan Molak",
@@ -46,7 +46,7 @@
     "node": "^16.13 || ^18.12 || ^20"
   },
   "dependencies": {
-    "@serenity-js/core": "3.18.1",
+    "@serenity-js/core": "3.20.0",
     "agent-base": "7.1.0",
     "axios": "1.6.7",
     "http-proxy-agent": "7.0.2",
@@ -56,7 +56,7 @@
   },
   "devDependencies": {
     "@integration/testing-tools": "3.0.0",
-    "@serenity-js/assertions": "3.18.1",
+    "@serenity-js/assertions": "3.20.0",
     "@types/chai": "4.3.12",
     "@types/mocha": "10.0.6",
     "axios-mock-adapter": "1.22.0",
@@ -66,5 +66,5 @@
     "ts-node": "10.9.2",
     "typescript": "5.2.2"
   },
-  "gitHead": "e64f71601cae8bf0060f60a5d65dbe5e1e981a72"
+  "gitHead": "2089afc60adb2751416fa6d800d4e7af95a99f25"
 }

package/src/index.ts

@@ -1 +1,2 @@
+export * from './io';
 export * from './screenplay';

package/src/io/AxiosRequestConfigDefaults.ts

@@ -0,0 +1,15 @@
+import { type CreateAxiosDefaults } from 'axios';
+
+export type AxiosRequestConfigProxyDefaults = {
+    host: string;
+    port?: number;          // SOCKS proxies don't require port number
+    auth?: {
+        username: string;
+        password: string;
+    };
+    protocol?: string;
+}
+
+export type AxiosRequestConfigDefaults<Data = any> = Omit<CreateAxiosDefaults<Data>, 'proxy'> & {
+    proxy?: AxiosRequestConfigProxyDefaults | false;
+}

package/src/io/ProxyAgent.ts

@@ -0,0 +1,129 @@
+import { ConfigurationError } from '@serenity-js/core';
+import type { AgentConnectOpts } from 'agent-base';
+import { Agent } from 'agent-base';
+import * as http from 'http';
+import { HttpProxyAgent, type HttpProxyAgentOptions } from 'http-proxy-agent';
+import * as https from 'https';
+import { HttpsProxyAgent, type HttpsProxyAgentOptions } from 'https-proxy-agent';
+import { LRUCache } from 'lru-cache';
+import { getProxyForUrl as envGetProxyForUrl } from 'proxy-from-env';
+
+const protocols = [
+    ...HttpProxyAgent.protocols,
+] as const;
+
+type AgentConstructor = new (proxy: URL | string, options?: ProxyAgentOptions) => Agent;
+
+type ValidProtocol = (typeof protocols)[number];
+
+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 class ProxyAgent extends Agent {
+
+    private static proxyAgents: { [P in ValidProtocol]: [ AgentConstructor, AgentConstructor ] } = {
+        http:   [ HttpProxyAgent, HttpsProxyAgent ],
+        https:  [ HttpProxyAgent, HttpsProxyAgent ],
+    };
+
+    /**
+     * Cache for `Agent` instances.
+     */
+    private readonly cache = new LRUCache<string, Agent>({
+        max: 20,
+        dispose: (value: Agent, key: string) => value.destroy(),
+    });
+
+    private readonly httpAgent: http.Agent;
+    private readonly httpsAgent: http.Agent;
+    private readonly getProxyForUrl: GetProxyForUrlCallback;
+
+    constructor(private readonly agentOptions: ProxyAgentOptions) {
+        super(agentOptions);
+        this.httpAgent      = agentOptions?.httpAgent       || new http.Agent(agentOptions);
+        this.httpsAgent     = agentOptions?.httpsAgent      || new https.Agent(agentOptions as https.AgentOptions);
+        this.getProxyForUrl = agentOptions?.getProxyForUrl  || envGetProxyForUrl;
+    }
+
+    override async connect(request: http.ClientRequest, options: AgentConnectOpts): Promise<http.Agent> {
+        const { secureEndpoint } = options;
+        const isWebSocket = request.getHeader('upgrade') === 'websocket';
+        const protocol = secureEndpoint
+            ? (isWebSocket ? 'wss:' : 'https:')
+            : (isWebSocket ? 'ws:' : 'http:');
+        const host = request.getHeader('host');
+        const url = new URL(request.path, `${protocol}//${host}`).href;
+        const proxy = this.getProxyForUrl(url);
+
+        if (! proxy) {
+            return secureEndpoint
+                ? this.httpsAgent
+                : this.httpAgent;
+        }
+
+        // attempt to get a cached `http.Agent` instance first
+        const cacheKey = `${ protocol }+${ proxy }`;
+        let agent = this.cache.get(cacheKey);
+        if (! agent) {
+            agent = this.createAgent(new URL(proxy), secureEndpoint || isWebSocket);
+
+            this.cache.set(cacheKey, agent);
+        }
+
+        return agent;
+    }
+
+    private createAgent(proxyUrl: URL, requiresTls: boolean): Agent {
+
+        const protocol = proxyUrl.protocol.replace(':', '');
+
+        if (! this.isValidProtocol(protocol)) {
+            throw new ConfigurationError(`Unsupported protocol for proxy URL: ${ proxyUrl }`);
+        }
+
+        const ctor = ProxyAgent.proxyAgents[protocol][requiresTls ? 1 : 0];
+
+        return new ctor(proxyUrl, this.agentOptions);
+    }
+
+    private isValidProtocol(v: string): v is ValidProtocol {
+        return (protocols as readonly string[]).includes(v);
+    }
+
+    override destroy(): void {
+        this.cache.clear();
+        super.destroy();
+    }
+}

package/src/io/axiosProxyOverridesFor.ts

@@ -0,0 +1,39 @@
+import type * as http from 'http';
+import { ensure, isDefined } from 'tiny-types';
+
+import type { AxiosRequestConfigDefaults } from './AxiosRequestConfigDefaults';
+import { createUrl } from './createUrl';
+import { ProxyAgent } from './ProxyAgent';
+
+/**
+ * @param options
+ */
+export function axiosProxyOverridesFor<Data = any>(options: AxiosRequestConfigDefaults<Data>): {
+    proxy: false, httpAgent: http.Agent, httpsAgent: http.Agent
+} {
+    const envProxyOverride: string | false = options.proxy
+        && createUrl({
+            username: options.proxy?.auth?.username,
+            password: options.proxy?.auth?.password,
+            protocol: options.proxy?.protocol,
+            hostname: ensure('proxy.host', options.proxy?.host, isDefined()),
+            port: options.proxy?.port
+        }).toString();
+
+    const agent = new ProxyAgent({
+        httpAgent: options.httpAgent,
+        httpsAgent: options.httpsAgent,
+
+        // if there's a specific proxy override configured, use it
+        // if not - detect proxy automatically based on env variables
+        getProxyForUrl: envProxyOverride
+            ? (url_: string) => envProxyOverride
+            : undefined,
+    });
+
+    return {
+        proxy: false,
+        httpAgent: agent,
+        httpsAgent: agent,
+    };
+}

package/src/io/createAxios.ts

@@ -0,0 +1,50 @@
+import { Duration } from '@serenity-js/core';
+import axios, { Axios, type AxiosInstance, type AxiosRequestConfig } from 'axios';
+
+import { axiosProxyOverridesFor } from './axiosProxyOverridesFor';
+import type { AxiosRequestConfigDefaults, AxiosRequestConfigProxyDefaults } from './AxiosRequestConfigDefaults';
+
+/**
+ * Creates an Axios instance with desired configuration and proxy support.
+ *
+ * @param axiosInstanceOrConfig
+ */
+export function createAxios(axiosInstanceOrConfig: AxiosInstance | AxiosRequestConfigDefaults = {}): AxiosInstance {
+    const axiosInstanceGiven = isAxiosInstance(axiosInstanceOrConfig);
+
+    const axiosInstance = axiosInstanceGiven
+        ? axiosInstanceOrConfig
+        : axios.create({
+            timeout: Duration.ofSeconds(10).inMilliseconds(),
+            ...omit(axiosInstanceOrConfig, 'proxy'),
+        });
+
+    const proxyConfig: AxiosRequestConfigProxyDefaults | false | undefined = axiosInstanceGiven
+        ? axiosInstanceOrConfig.defaults.proxy
+        : axiosInstanceOrConfig.proxy;
+
+    const proxyOverrides = axiosProxyOverridesFor({
+        ...axiosInstance.defaults,
+        proxy: proxyConfig || undefined,
+    });
+
+    return withOverrides(axiosInstance, proxyOverrides);
+}
+
+function isAxiosInstance(axiosInstanceOrConfig: any): axiosInstanceOrConfig is AxiosInstance {
+    return axiosInstanceOrConfig
+        && (axiosInstanceOrConfig instanceof Axios || axiosInstanceOrConfig.defaults);
+}
+
+function withOverrides<Data = any>(axiosInstance: AxiosInstance, overrides: AxiosRequestConfig<Data>): AxiosInstance {
+    for (const [key, override] of Object.entries(overrides)) {
+        axiosInstance.defaults[key] = override;
+    }
+
+    return axiosInstance;
+}
+
+function omit<T extends object, K extends keyof T>(record: T, key: K): Omit<T, K> {
+    const { [key]: omitted_, ...rest } = record;
+    return rest;
+}

package/src/io/createUrl.ts

@@ -0,0 +1,39 @@
+import { ensure, isDefined, isNotBlank, isString } from 'tiny-types';
+
+export interface CreateUrlOptions {
+    protocol?: string;
+    hostname: string;
+    port?: string | number;
+    username?: string;
+    password?: string;
+}
+
+export function createUrl(options: CreateUrlOptions): URL {
+    const hostname  = ensure('hostname', options?.hostname, isString(), isNotBlank()).trim();
+    const port      = options?.port
+        ? ':' + options?.port
+        : (options?.protocol ? undefined : ':80');
+
+    return new URL([
+        options?.protocol && protocolFrom(options?.protocol),
+        (options?.username || options?.password) && credentialsFrom(options.username, options.password),
+        hostname,
+        port,
+    ].filter(Boolean).join(''));
+}
+
+function protocolFrom(protocol?: string): string {
+    const protocolName = protocol.match(/([A-Za-z]+)[/:]*/)[1];
+
+    ensure('hostname', protocolName, isDefined());
+
+    return protocolName + '://';
+}
+
+function credentialsFrom(username?: string, password?: string): string {
+    return [
+        username && encodeURIComponent(username),
+        password && ':' + encodeURIComponent(password),
+        '@'
+    ].filter(Boolean).join('');
+}

package/src/io/index.ts

@@ -0,0 +1,2 @@
+export * from './AxiosRequestConfigDefaults';
+export * from './createAxios';

package/src/screenplay/abilities/CallAnApi.ts

@@ -1,16 +1,14 @@
-import { Ability, ConfigurationError, Duration, LogicError, TestCompromisedError } from '@serenity-js/core';
-import axios, {
-    Axios,
+import { Ability, ConfigurationError, LogicError, TestCompromisedError } from '@serenity-js/core';
+import {
     type AxiosDefaults,
     type AxiosError,
     type AxiosInstance,
     type AxiosRequestConfig,
     type AxiosResponse,
-    type CreateAxiosDefaults,
 } from 'axios';
 
-import type { AxiosRequestConfigDefaults, AxiosRequestConfigProxyDefaults } from './AxiosRequestConfigDefaults';
-import { axiosProxyOverridesFor } from './proxy';
+import type { AxiosRequestConfigDefaults} from '../../io';
+import { createAxios } from '../../io';
 
 /**
  * An {@apilink Ability} that wraps [axios client](https://axios-http.com/docs/api_intro) and enables
@@ -147,14 +145,13 @@ import { axiosProxyOverridesFor } from './proxy';
  *
  * ```ts
  * import { actorCalled } from '@serenity-js/core'
- * import { CallAnApi, GetRequest, LastResponse, Send } from '@serenity-js/rest'
+ * import { createAxios, 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 })
+ * const instance = createAxios({ baseURL 'https://api.example.org/' })
+ * axiosRetry(instance, { retries: 3 })
  *
  * await actorCalled('Apisitt')
  *   .whoCan(
@@ -177,11 +174,11 @@ import { axiosProxyOverridesFor } from './proxy';
  * import { CallAnApi, GetRequest, LastResponse, Send } from '@serenity-js/rest'
  * import { Ensure, equals } from '@serenity-js/assertions'
  *
- * import axios from 'axios'
+ * import { axiosCreate } from '@serenity-js/rest'
  * import axiosRetry from 'axios-retry'
  *
- * const instance = axios.create({ baseURL 'https://api.example.org/' })
- * axiosRetry(axios, { retries: 3 })
+ * const instance = axiosCreate({ baseURL 'https://api.example.org/' })
+ * axiosRetry(instance, { retries: 3 })
  *
  * await actorCalled('Apisitt')
  *   .whoCan(
@@ -326,10 +323,6 @@ export class CallAnApi extends Ability {
 
     private lastResponse: AxiosResponse;
 
-    private static readonly defaults: CreateAxiosDefaults<any> = {
-        timeout: Duration.ofSeconds(10).inMilliseconds(),
-    };
-
     /**
      * Produces an {@apilink Ability|ability} to call a REST API at a specified `baseURL`;
      *
@@ -363,26 +356,7 @@ export class CallAnApi extends Ability {
      * @param axiosInstanceOrConfig
      */
     static using(axiosInstanceOrConfig: AxiosInstance | AxiosRequestConfigDefaults): CallAnApi {
-
-        const axiosInstanceGiven = isAxiosInstance(axiosInstanceOrConfig);
-
-        const axiosInstance = axiosInstanceGiven
-            ? axiosInstanceOrConfig
-            : axios.create({
-                ...CallAnApi.defaults,
-                ...omit(axiosInstanceOrConfig, 'proxy'),
-            });
-
-        const proxyConfig: AxiosRequestConfigProxyDefaults | false | undefined = axiosInstanceGiven
-            ? axiosInstanceOrConfig.defaults.proxy
-            : axiosInstanceOrConfig.proxy;
-
-        const proxyOverrides = axiosProxyOverridesFor({
-            ...axiosInstance.defaults,
-            proxy: proxyConfig || undefined,
-        });
-
-        return new CallAnApi(withOverrides(axiosInstance, proxyOverrides));
+        return new CallAnApi(createAxios(axiosInstanceOrConfig));
     }
 
     /**
@@ -488,21 +462,3 @@ export class CallAnApi extends Ability {
         return mappingFunction(this.lastResponse);
     }
 }
-
-function isAxiosInstance(axiosInstanceOrConfig: any): axiosInstanceOrConfig is AxiosInstance {
-    return axiosInstanceOrConfig
-        && (axiosInstanceOrConfig instanceof Axios || axiosInstanceOrConfig.defaults);
-}
-
-function withOverrides<Data = any>(axiosInstance: AxiosInstance, overrides: AxiosRequestConfig<Data>): AxiosInstance {
-    for (const [key, override] of Object.entries(overrides)) {
-        axiosInstance.defaults[key] = override;
-    }
-
-    return axiosInstance;
-}
-
-function omit<T extends object, K extends keyof T>(record: T, key: K): Omit<T, K> {
-    const { [key]: omitted_, ...rest } = record;
-    return rest;
-}

package/src/screenplay/abilities/index.ts

@@ -1,2 +1 @@
-export * from './AxiosRequestConfigDefaults';
 export * from './CallAnApi';

package/src/screenplay/interactions/ChangeApiConfig.ts

@@ -13,7 +13,7 @@ import { CallAnApi } from '../abilities';
  * ```ts
  * import { actorCalled } from '@serenity-js/core';
  * import { By Navigate, PageElement, Text } from '@serenity-js/web';
- * import { CallAnApi, ChangeApiConfig, GetRequest, LastResponse, Send } from '@serenity-js/rest'
+ * import { axiosCreate, CallAnApi, ChangeApiConfig, GetRequest, LastResponse, Send } from '@serenity-js/rest'
  * import { Ensure, equals } from '@serenity-js/assertions';
  *
  * import * as axios from 'axios';
@@ -29,7 +29,7 @@ import { CallAnApi } from '../abilities';
  *     BrowseTheWeb.using(protractor.browser),
  *
  *     // Note: no default base URL is given when the axios instance is created
- *     CallAnApi.using(axios.create()),
+ *     CallAnApi.using(axiosCreate()),
  *   )
  *   .attemptsTo(
  *     Navigate.to('/profile'),