@serenity-js/rest 3.0.0-rc.8 → 3.0.0

package/lib/models/PutRequest.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PutRequest = void 0;
+const core_1 = require("@serenity-js/core");
+const HTTPRequest_1 = require("./HTTPRequest");
+/**
+ * The PUT method requests that the state of the target resource be
+ * created or replaced with the state defined by the representation
+ * enclosed in the request message payload.
+ *
+ * PUT request should be used when you want to create
+ * a new resource at a known `resourceUri` (e.g. `/books/0-688-00230-7`)
+ * or replace an existing resource at such `resourceUri`.
+ *
+ * PUT request is [idempotent](https://developer.mozilla.org/en-US/docs/Glossary/Idempotent):
+ * calling it once or several times successively has the same effect (that is no _side effect_).
+ *
+ * ## Create a new resource at a known location
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core';
+ * import { CallAnApi, LastResponse, PutRequest, Send } from '@serenity-js/rest';
+ * import { Ensure, equals } from '@serenity-js/assertions';
+ *
+ * await actorCalled('Apisit')
+ *   .whoCan(CallAnApi.at('https://api.example.org/'))
+ *   .attemptsTo(
+ *     Send.a(PutRequest.to('/books/0-688-00230-7').with({
+ *       isbn: '0-688-00230-7',
+ *       title: 'Zen and the Art of Motorcycle Maintenance: An Inquiry into Values',
+ *       author: 'Robert M. Pirsig',
+ *     })),
+ *     Ensure.that(LastResponse.status(), equals(201)),
+ *   )
+ * ```
+ *
+ * ## Learn more
+ * - https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PUT
+ * - https://tools.ietf.org/html/rfc7231#section-4.3.4
+ *
+ * @group Models
+ */
+class PutRequest extends HTTPRequest_1.HTTPRequest {
+    /**
+     * Configures the object with a destination URI.
+     *
+     * When the `resourceUri` is not a fully qualified URL but a path, such as `/products/2`,
+     * it gets concatenated with the URL provided to the Axios instance
+     * when the {@apilink Ability|ability} to {@apilink CallAnApi} was instantiated.
+     *
+     * @param resourceUri
+     *  The URI where the {@apilink Actor}
+     *  should send the {@apilink HTTPRequest}
+     */
+    static to(resourceUri) {
+        return new PutRequest(resourceUri);
+    }
+    /**
+     * Configures the object with a request body.
+     *
+     * @param data
+     *  Data to be sent to the `resourceUri`
+     */
+    with(data) {
+        return new PutRequest(this.resourceUri, data, this.config);
+    }
+    /**
+     * Overrides the default Axios request configuration provided
+     * when the {@apilink Ability|ability} to {@apilink CallAnApi} was instantiated.
+     *
+     * #### Learn more
+     * - {@apilink Answerable}
+     * - {@apilink WithAnswerableProperties}
+     * - [AxiosRequestConfig](https://github.com/axios/axios/blob/v0.27.2/index.d.ts#L75-L113)
+     *
+     * @param {Answerable<WithAnswerableProperties<AxiosRequestConfig>>} config
+     *  Axios request configuration overrides
+     */
+    using(config) {
+        return new PutRequest(this.resourceUri, this.data, core_1.Question.fromObject(config));
+    }
+}
+exports.PutRequest = PutRequest;
+//# sourceMappingURL=PutRequest.js.map

package/lib/models/PutRequest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PutRequest.js","sourceRoot":"","sources":["../../src/models/PutRequest.ts"],"names":[],"mappings":";;;AAAA,4CAAmF;AAGnF,+CAA4C;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAa,UAAW,SAAQ,yBAAW;IAEvC;;;;;;;;;;OAUG;IACH,MAAM,CAAC,EAAE,CAAC,WAA+B;QACrC,OAAO,IAAI,UAAU,CAAC,WAAW,CAAC,CAAC;IACvC,CAAC;IAED;;;;;OAKG;IACH,IAAI,CAAC,IAAqB;QACtB,OAAO,IAAI,UAAU,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IAC/D,CAAC;IAED;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,MAAgE;QAClE,OAAO,IAAI,UAAU,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,IAAI,EAAE,eAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;IACpF,CAAC;CACJ;AA1CD,gCA0CC"}

package/lib/{model → models}/index.d.ts

@@ -6,3 +6,4 @@ export * from './OptionsRequest';
 export * from './PatchRequest';
 export * from './PostRequest';
 export * from './PutRequest';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/models/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC"}

package/lib/{model → models}/index.js

@@ -1,7 +1,11 @@
 "use strict";
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
-    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[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];

package/lib/models/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/models/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,kDAAgC;AAChC,+CAA6B;AAC7B,gDAA8B;AAC9B,gDAA8B;AAC9B,mDAAiC;AACjC,iDAA+B;AAC/B,gDAA8B;AAC9B,+CAA6B"}

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

@@ -1,151 +1,140 @@
-import { Ability, UsesAbilities } from '@serenity-js/core';
-import { AxiosInstance, AxiosRequestConfig, AxiosResponse } from 'axios';
+import { Ability } from '@serenity-js/core';
+import { AxiosDefaults, AxiosInstance, AxiosRequestConfig, AxiosResponse } from 'axios';
 /**
- * @desc
- *  An {@link @serenity-js/core/lib/screenplay~Ability} that enables the {@link Actor} to call a HTTP API.
- *  If you need to connect via a proxy, check out [this article](https://janmolak.com/node-js-axios-behind-corporate-proxies-8b17a6f31f9d).
+ * An {@apilink Ability} that enables the {@apilink Actor} to call an HTTP API.
  *
- * @example <caption>Using a default Axios HTTP client</caption>
- *  import { Actor } from '@serenity-js/core';
- *  import { CallAnApi, GetRequest, LastResponse, Send } from '@serenity-js/rest'
- *  import { Ensure, equals } from '@serenity-js/assertions';
+ * 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).
  *
- *  const actor = Actor.named('Apisit').whoCan(
- *      CallAnApi.at('https://myapp.com/api'),
- *  );
+ * ## Using the default Axios HTTP client
  *
- *  actor.attemptsTo(
- *      Send.a(GetRequest.to('/users/2')),
- *      Ensure.that(LastResponse.status(), equals(200)),
- *  );
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { CallAnApi, GetRequest, LastResponse, Send } from '@serenity-js/rest'
+ * import { Ensure, equals } from '@serenity-js/assertions'
  *
- * @example <caption>Using Axios client with custom configuration</caption>
- *  import { Actor } 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('https://api.example.org/')
+ *   )
+ *   .attemptsTo(
+ *     Send.a(GetRequest.to('/users/2')),
+ *     Ensure.that(LastResponse.status(), equals(200)),
+ *   )
+ * ```
  *
- *  import axios from 'axios';
+ * ## Using Axios client with custom configuration
  *
- *  const axiosInstance = axios.create({
- *      timeout: 5 * 1000,
- *      headers: {
- *          'X-Custom-Api-Key': 'secret-key',
- *      },
- *  });
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { CallAnApi, GetRequest, LastResponse, Send } from '@serenity-js/rest'
+ * import { Ensure, equals } from '@serenity-js/assertions'
  *
- *  const actor = Actor.named('Apisit').whoCan(
- *      CallAnApi.using(axiosInstance),
- *  );
+ * import * as axios from 'axios'
  *
- *  actor.attemptsTo(
- *      Send.a(GetRequest.to('/users/2')),
- *      Ensure.that(LastResponse.status(), equals(200)),
- *  );
+ * const axiosInstance = axios.create({
+ *   timeout: 5 * 1000,
+ *   headers: {
+ *     'X-Custom-Api-Key': 'secret-key',
+ *   },
+ * });
  *
- * @see https://github.com/axios/axios
- * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods
+ * await actorCalled('Apisitt')
+ *   .whoCan(
+ *     CallAnApi.using(axiosInstance),
+ *   )
+ *   .attemptsTo(
+ *     Send.a(GetRequest.to('/users/2')),
+ *     Ensure.that(LastResponse.status(), equals(200)),
+ *   )
+ * ```
  *
- * @public
- * @implements {@link @serenity-js/core/lib/screenplay~Ability}
+ * ## Learn more
+ * - https://github.com/axios/axios
+ * - https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods
+ *
+ * @group Abilities
  */
-export declare class CallAnApi implements Ability {
+export declare class CallAnApi extends Ability {
     private readonly axiosInstance;
     /** @private */
     private lastResponse;
     /**
-     * @desc
-     *  Ability to Call and api at a specified baseUrl
+     * Produces an {@apilink Ability|ability} to call a REST api at a specified baseUrl
      *
-     *  Default timeout is set to 2s.
+     * Default timeout is set to 2s.
      *
-     *  Default request headers:
-     *  - Accept: application/json,application/xml
+     * Default request headers:
+     * - `Accept`: `application/json,application/xml`
      *
-     * @param {string} baseURL
-     * @returns {CallAnApi}
+     * @param baseURL
      */
     static at(baseURL: string): CallAnApi;
     /**
-     * @desc
-     *  Ability to Call a REST API using a given axios instance.
+     * Produces an {@apilink Ability|ability} to call a REST API using a given axios instance.
      *
-     *  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.
+     * 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.
      *
-     * @param {AxiosInstance} axiosInstance
-     * @returns {CallAnApi}
+     * #### Learn more
+     * - [AxiosInstance](https://github.com/axios/axios/blob/v0.27.2/index.d.ts#L235-L238)
      *
-     * @see {@link AxiosInstance}
+     * @param axiosInstance
      */
     static using(axiosInstance: AxiosInstance): CallAnApi;
     /**
-     * @desc
-     *  Used to access the Actor's ability to {@link CallAnApi}
-     *  from within the {@link @serenity-js/core/lib/screenplay~Interaction} classes,
-     *  such as {@link Send}.
+     * #### Learn more
+     * - [AxiosInstance](https://github.com/axios/axios/blob/v0.27.2/index.d.ts#L235-L238)
      *
-     * @param {UsesAbilities} actor
-     * @return {CallAnApi}
-     */
-    static as(actor: UsesAbilities): CallAnApi;
-    /**
-     * @param {AxiosInstance} axiosInstance
+     * @param axiosInstance
      *  A pre-configured instance of the Axios HTTP client
-     *
-     * @see {@link AxiosInstance}
      */
     constructor(axiosInstance: AxiosInstance);
     /**
-     * @desc
-     *  Allows for the original Axios config to be changed after
-     *  the {@link CallAnApi} {@link @serenity-js/core/lib/screenplay~Ability}
-     *  has been instantiated and given to the {@link Actor}.
+     * Allows for the original Axios config to be changed after
+     * the {@apilink Ability|ability} to {@apilink CallAnApi}
+     * has been instantiated and given to the {@apilink Actor}.
      *
-     * @param {function (original: AxiosRequestConfig): any} fn
-     * @returns {void}
+     * #### Learn more
+     * - [AxiosRequestConfig](https://github.com/axios/axios/blob/v0.27.2/index.d.ts#L75-L113)
      *
-     * @see {@link AxiosRequestConfig}
+     * @param fn
      */
-    modifyConfig(fn: (original: AxiosRequestConfig) => any): void;
+    modifyConfig(fn: (original: AxiosDefaults<any>) => any): void;
     /**
-     * @desc
-     *  Sends a HTTP request to a specified url.
-     *  Response will be cached and available via {@link CallAnApi#mapLastResponse}
+     * Sends an HTTP request to a specified url.
+     * Response will be cached and available via {@apilink mapLastResponse}
      *
-     * @param {AxiosRequestConfig} config
-     *  Axios request configuration, which can be used to override the defaults
-     *  provided when the {@link CallAnApi} {@link @serenity-js/core/lib/screenplay~Ability} is instantiated
-     *
-     * @returns {Promise<AxiosResponse>}
-     *  A promise of an AxiosResponse
+     * #### 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)
      *
-     * @see {@link AxiosRequestConfig}
-     * @see {@link AxiosResponse}
+     * @param config
+     *  Axios request configuration, which can be used to override the defaults
+     *  provided when the {@apilink Ability|ability} to {@apilink CallAnApi} was instantiated.
      */
     request(config: AxiosRequestConfig): Promise<AxiosResponse>;
     /**
-     * @desc
-     *  Resolves the final URL, based on the {@link AxiosRequestConfig} provided
-     *  any any defaults {@link AxiosInstance} has been configured with.
+     * Resolves the final URL, based on the {@apilink AxiosRequestConfig} provided
+     * and any defaults that the {@apilink AxiosInstance} has been configured with.
      *
-     * @param {AxiosRequestConfig} config
-     * @returns {string}
+     * #### 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)
      *
-     * @see {@link AxiosRequestConfig}
-     * @see {@link AxiosInstance}
+     * @param config
      */
     resolveUrl(config: AxiosRequestConfig): string;
     /**
-     * @desc
-     *  Maps the last cached response to another type.
-     *  Useful when you need to extract a portion of the {@link AxiosResponse} object.
+     * Maps the last cached response to another type.
+     * Useful when you need to extract a portion of the {@apilink AxiosResponse} object.
      *
-     * @param {function<T>(AxiosResponse): T} fn - mapper function
-     * @returns {T}
+     * #### Learn more
+     * - [AxiosResponse](https://github.com/axios/axios/blob/v0.27.2/index.d.ts#L133-L140)
      *
-     * @see {@link AxiosResponse}
+     * @param mappingFunction
      */
-    mapLastResponse<T>(fn: (response: AxiosResponse) => T): T;
+    mapLastResponse<T>(mappingFunction: (response: AxiosResponse) => T): T;
     private captureResponseOf;
 }
+//# sourceMappingURL=CallAnApi.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"CallAnApi.d.ts","sourceRoot":"","sources":["../../../src/screenplay/abilities/CallAnApi.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAwD,MAAM,mBAAmB,CAAC;AAClG,OAAc,EAAE,aAAa,EAAc,aAAa,EAAgB,kBAAkB,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAEzH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,qBAAa,SAAU,SAAQ,OAAO;IA8CtB,OAAO,CAAC,QAAQ,CAAC,aAAa;IA5C1C,eAAe;IACf,OAAO,CAAC,YAAY,CAAgB;IAEpC;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS;IAQrC;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,KAAK,CAAC,aAAa,EAAE,aAAa,GAAG,SAAS;IAIrD;;;;;;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;IACH,OAAO,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,aAAa,CAAC;IAI3D;;;;;;;;;OASG;IACH,UAAU,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM;IAI9C;;;;;;;;OAQG;IACH,eAAe,CAAC,CAAC,EAAE,eAAe,EAAE,CAAC,QAAQ,EAAE,aAAa,KAAK,CAAC,GAAG,CAAC;IAQtE,OAAO,CAAC,iBAAiB;CA0B5B"}

package/lib/screenplay/abilities/CallAnApi.js

@@ -1,79 +1,75 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CallAnApi = void 0;
 const core_1 = require("@serenity-js/core");
-const axios_1 = require("axios");
-const mergeConfig = require('axios/lib/core/mergeConfig'); // eslint-disable-line @typescript-eslint/no-var-requires
-const buildFullPath = require('axios/lib/core/buildFullPath'); // eslint-disable-line @typescript-eslint/no-var-requires
+const axios_1 = __importDefault(require("axios"));
 /**
- * @desc
- *  An {@link @serenity-js/core/lib/screenplay~Ability} that enables the {@link Actor} to call a HTTP API.
- *  If you need to connect via a proxy, check out [this article](https://janmolak.com/node-js-axios-behind-corporate-proxies-8b17a6f31f9d).
+ * An {@apilink Ability} that enables the {@apilink Actor} to call an HTTP API.
  *
- * @example <caption>Using a default Axios HTTP client</caption>
- *  import { Actor } from '@serenity-js/core';
- *  import { CallAnApi, GetRequest, LastResponse, Send } from '@serenity-js/rest'
- *  import { Ensure, equals } from '@serenity-js/assertions';
+ * 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).
  *
- *  const actor = Actor.named('Apisit').whoCan(
- *      CallAnApi.at('https://myapp.com/api'),
- *  );
+ * ## Using the default Axios HTTP client
  *
- *  actor.attemptsTo(
- *      Send.a(GetRequest.to('/users/2')),
- *      Ensure.that(LastResponse.status(), equals(200)),
- *  );
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { CallAnApi, GetRequest, LastResponse, Send } from '@serenity-js/rest'
+ * import { Ensure, equals } from '@serenity-js/assertions'
  *
- * @example <caption>Using Axios client with custom configuration</caption>
- *  import { Actor } 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('https://api.example.org/')
+ *   )
+ *   .attemptsTo(
+ *     Send.a(GetRequest.to('/users/2')),
+ *     Ensure.that(LastResponse.status(), equals(200)),
+ *   )
+ * ```
  *
- *  import axios from 'axios';
+ * ## Using Axios client with custom configuration
  *
- *  const axiosInstance = axios.create({
- *      timeout: 5 * 1000,
- *      headers: {
- *          'X-Custom-Api-Key': 'secret-key',
- *      },
- *  });
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { CallAnApi, GetRequest, LastResponse, Send } from '@serenity-js/rest'
+ * import { Ensure, equals } from '@serenity-js/assertions'
  *
- *  const actor = Actor.named('Apisit').whoCan(
- *      CallAnApi.using(axiosInstance),
- *  );
+ * import * as axios from 'axios'
  *
- *  actor.attemptsTo(
- *      Send.a(GetRequest.to('/users/2')),
- *      Ensure.that(LastResponse.status(), equals(200)),
- *  );
+ * const axiosInstance = axios.create({
+ *   timeout: 5 * 1000,
+ *   headers: {
+ *     'X-Custom-Api-Key': 'secret-key',
+ *   },
+ * });
  *
- * @see https://github.com/axios/axios
- * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods
+ * await actorCalled('Apisitt')
+ *   .whoCan(
+ *     CallAnApi.using(axiosInstance),
+ *   )
+ *   .attemptsTo(
+ *     Send.a(GetRequest.to('/users/2')),
+ *     Ensure.that(LastResponse.status(), equals(200)),
+ *   )
+ * ```
  *
- * @public
- * @implements {@link @serenity-js/core/lib/screenplay~Ability}
+ * ## Learn more
+ * - https://github.com/axios/axios
+ * - https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods
+ *
+ * @group Abilities
  */
-class CallAnApi {
-    /**
-     * @param {AxiosInstance} axiosInstance
-     *  A pre-configured instance of the Axios HTTP client
-     *
-     * @see {@link AxiosInstance}
-     */
-    constructor(axiosInstance) {
-        this.axiosInstance = axiosInstance;
-    }
+class CallAnApi extends core_1.Ability {
     /**
-     * @desc
-     *  Ability to Call and api at a specified baseUrl
+     * Produces an {@apilink Ability|ability} to call a REST api at a specified baseUrl
      *
-     *  Default timeout is set to 2s.
+     * Default timeout is set to 2s.
      *
-     *  Default request headers:
-     *  - Accept: application/json,application/xml
+     * Default request headers:
+     * - `Accept`: `application/json,application/xml`
      *
-     * @param {string} baseURL
-     * @returns {CallAnApi}
+     * @param baseURL
      */
     static at(baseURL) {
         return new CallAnApi(axios_1.default.create({
@@ -83,95 +79,86 @@ class CallAnApi {
         }));
     }
     /**
-     * @desc
-     *  Ability to Call a REST API using a given axios instance.
+     * Produces an {@apilink Ability|ability} to call a REST API using a given axios instance.
      *
-     *  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.
+     * 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.
      *
-     * @param {AxiosInstance} axiosInstance
-     * @returns {CallAnApi}
+     * #### Learn more
+     * - [AxiosInstance](https://github.com/axios/axios/blob/v0.27.2/index.d.ts#L235-L238)
      *
-     * @see {@link AxiosInstance}
+     * @param axiosInstance
      */
     static using(axiosInstance) {
         return new CallAnApi(axiosInstance);
     }
     /**
-     * @desc
-     *  Used to access the Actor's ability to {@link CallAnApi}
-     *  from within the {@link @serenity-js/core/lib/screenplay~Interaction} classes,
-     *  such as {@link Send}.
+     * #### Learn more
+     * - [AxiosInstance](https://github.com/axios/axios/blob/v0.27.2/index.d.ts#L235-L238)
      *
-     * @param {UsesAbilities} actor
-     * @return {CallAnApi}
+     * @param axiosInstance
+     *  A pre-configured instance of the Axios HTTP client
      */
-    static as(actor) {
-        return actor.abilityTo(CallAnApi);
+    constructor(axiosInstance) {
+        super();
+        this.axiosInstance = axiosInstance;
     }
     /**
-     * @desc
-     *  Allows for the original Axios config to be changed after
-     *  the {@link CallAnApi} {@link @serenity-js/core/lib/screenplay~Ability}
-     *  has been instantiated and given to the {@link Actor}.
+     * Allows for the original Axios config to be changed after
+     * the {@apilink Ability|ability} to {@apilink CallAnApi}
+     * has been instantiated and given to the {@apilink Actor}.
      *
-     * @param {function (original: AxiosRequestConfig): any} fn
-     * @returns {void}
+     * #### Learn more
+     * - [AxiosRequestConfig](https://github.com/axios/axios/blob/v0.27.2/index.d.ts#L75-L113)
      *
-     * @see {@link AxiosRequestConfig}
+     * @param fn
      */
     modifyConfig(fn) {
         fn(this.axiosInstance.defaults);
     }
     /**
-     * @desc
-     *  Sends a HTTP request to a specified url.
-     *  Response will be cached and available via {@link CallAnApi#mapLastResponse}
+     * Sends an HTTP request to a specified url.
+     * Response will be cached and available via {@apilink mapLastResponse}
      *
-     * @param {AxiosRequestConfig} config
-     *  Axios request configuration, which can be used to override the defaults
-     *  provided when the {@link CallAnApi} {@link @serenity-js/core/lib/screenplay~Ability} is instantiated
-     *
-     * @returns {Promise<AxiosResponse>}
-     *  A promise of an AxiosResponse
+     * #### 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)
      *
-     * @see {@link AxiosRequestConfig}
-     * @see {@link AxiosResponse}
+     * @param config
+     *  Axios request configuration, which can be used to override the defaults
+     *  provided when the {@apilink Ability|ability} to {@apilink CallAnApi} was instantiated.
      */
     request(config) {
         return this.captureResponseOf(this.axiosInstance.request(config));
     }
     /**
-     * @desc
-     *  Resolves the final URL, based on the {@link AxiosRequestConfig} provided
-     *  any any defaults {@link AxiosInstance} has been configured with.
+     * Resolves the final URL, based on the {@apilink AxiosRequestConfig} provided
+     * and any defaults that the {@apilink AxiosInstance} has been configured with.
      *
-     * @param {AxiosRequestConfig} config
-     * @returns {string}
+     * #### 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)
      *
-     * @see {@link AxiosRequestConfig}
-     * @see {@link AxiosInstance}
+     * @param config
      */
     resolveUrl(config) {
-        const merged = mergeConfig(this.axiosInstance.defaults, config);
-        return buildFullPath(merged.baseURL, merged.url);
+        return this.axiosInstance.getUri(config);
     }
     /**
-     * @desc
-     *  Maps the last cached response to another type.
-     *  Useful when you need to extract a portion of the {@link AxiosResponse} object.
+     * Maps the last cached response to another type.
+     * Useful when you need to extract a portion of the {@apilink AxiosResponse} object.
      *
-     * @param {function<T>(AxiosResponse): T} fn - mapper function
-     * @returns {T}
+     * #### Learn more
+     * - [AxiosResponse](https://github.com/axios/axios/blob/v0.27.2/index.d.ts#L133-L140)
      *
-     * @see {@link AxiosResponse}
+     * @param mappingFunction
      */
-    mapLastResponse(fn) {
+    mapLastResponse(mappingFunction) {
         if (!this.lastResponse) {
             throw new core_1.LogicError(`Make sure to perform a HTTP API call before checking on the response`);
         }
-        return fn(this.lastResponse);
+        return mappingFunction(this.lastResponse);
     }
     captureResponseOf(promisedResponse) {
         return promisedResponse

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":";;;;;;AAAA,4CAAkG;AAClG,kDAAyH;AAEzH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,MAAa,SAAU,SAAQ,cAAO;IAKlC;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,CAAC,OAAe;QACrB,OAAO,IAAI,SAAS,CAAC,eAAK,CAAC,MAAM,CAAC;YAC9B,OAAO;YACP,OAAO,EAAE,IAAI;YACb,OAAO,EAAE,EAAE,MAAM,EAAE,kCAAkC,EAAE;SAC1D,CAAC,CAAC,CAAC;IACR,CAAC;IAED;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,KAAK,CAAC,aAA4B;QACrC,OAAO,IAAI,SAAS,CAAC,aAAa,CAAC,CAAC;IACxC,CAAC;IAED;;;;;;OAMG;IACH,YAA6B,aAA4B;QACrD,KAAK,EAAE,CAAC;QADiB,kBAAa,GAAb,aAAa,CAAe;IAEzD,CAAC;IAED;;;;;;;;;OASG;IACH,YAAY,CAAC,EAAyC;QAClD,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;IACpC,CAAC;IAED;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,MAA0B;QAC9B,OAAO,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;IACtE,CAAC;IAED;;;;;;;;;OASG;IACH,UAAU,CAAC,MAA0B;QACjC,OAAO,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC7C,CAAC;IAED;;;;;;;;OAQG;IACH,eAAe,CAAI,eAA+C;QAC9D,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE;YACpB,MAAM,IAAI,iBAAU,CAAC,sEAAsE,CAAC,CAAC;SAChG;QAED,OAAO,eAAe,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IAC9C,CAAC;IAEO,iBAAiB,CAAC,gBAA8B;QACpD,OAAO,gBAAgB;aAClB,IAAI,CACD,YAAY,CAAC,EAAE;YACX,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;YAEjC,OAAO,YAAY,CAAC;QACxB,CAAC,EACD,KAAK,CAAC,EAAE;YACJ,QAAQ,IAAI,EAAE;gBACV,KAAK,mBAAmB,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC;oBACxC,MAAM,IAAI,2BAAoB,CAAC,2BAA2B,EAAE,KAAK,CAAC,CAAC;gBACvE,KAAK,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC;oBACpC,MAAM,IAAI,2BAAoB,CAAC,8BAA8B,EAAE,KAAK,CAAC,CAAC;gBAC1E,KAAK,KAAK,YAAY,SAAS;oBAC3B,MAAM,IAAI,yBAAkB,CAAC,wDAAwD,EAAE,KAAK,CAAC,CAAC;gBAClG,KAAK,CAAG,KAAoB,CAAC,QAAQ;oBACjC,MAAM,IAAI,2BAAoB,CAAC,yBAAyB,EAAE,KAAK,CAAC,CAAC,CAAG,4BAA4B;gBACpG;oBACI,IAAI,CAAC,YAAY,GAAG,KAAK,CAAC,QAAQ,CAAC;oBAEnC,OAAO,KAAK,CAAC,QAAQ,CAAC;aAC7B;QACL,CAAC,CACJ,CAAC;IACV,CAAC;CACJ;AAzID,8BAyIC"}