@alwaysmeticulous/sdk-bundles-api 2.163.0 → 2.165.0

package/dist/record/middleware.d.ts

@@ -59,41 +59,50 @@ export interface RecorderMiddleware {
     /**
      * Transforms network requests before they are sent to Meticulous's servers.
      *
-     * Please ensure you call tryLoadAndStartRecorder with your middleware, or set
-     * `window.METICULOUS_RECORDER_MIDDLEWARE_V1`, when Meticulous is replaying sessions at test time ('replay time'),
-     * and not just when you want to record. This allows Meticulous to auto-detect your middleware and transform the
-     * requests at replay time when finding an appropiate request to match with. This enables correctly matching
-     * requests with the corresponding saved responses even if the requests have been substantially transformed by
-     * your middleware.
-     *
-     * Please note however that enough unique information must still be preserved in the redacted network request
-     * to allow Meticulous to correctly match a request that is performed at replay time by your application with
-     * the correct corresponding saved request stored in the recording / recorded session.
-     *
-     * For example: if you replace all query string values with "[REDACTED]", and there are multiple distinct requests with
-     * identical paths but different query string values then Meticulous will not have enough information to match
-     * them correctly. However if instead you md5 hash all query string values then Meticulous would have enough
-     * information to match the requests correctly.
-     *
-     * Note: returning null will cause the request and the corresponding response to be dropped from the payload.
-     * If the request/response is dropped from the payload but at replay time your application still makes
-     * the request then Meticulous will look for another closely matching recorded request, and replay that,
-     * or if none can be found it will fail the request with 'net::ERR_FAILED'/'Failed to fetch'.
+     * If you are only transforming headers, and nothing else then set {@link applyRequestTransformationAtReplayTime}
+     * to false.
+     *
+     * If you are transforming URLs, query strings or request bodies, or sometimes returning null, then:
+     *
+     *  1. Please ensure you call tryLoadAndStartRecorder with your middleware, or set
+     *     `window.METICULOUS_RECORDER_MIDDLEWARE_V1`, when Meticulous is replaying sessions at test time
+     *     ('replay time'), and not just when you want to record. This allows Meticulous to auto-detect your
+     *     middleware and transform the requests at replay time when finding an appropiate request to match
+     *     with. This enables correctly matching requests with the corresponding saved responses even if the
+     *     requests have been substantially transformed by your middleware.
+     *
+     *  2. Please avoid changing the transformations applied based on context that may differ at replay time.
+     *     For example, if you change whether you apply transformNetworkRequest based on whether the current URL contains
+     *     'staging', then when replaying the recorded session that network request transformer would not be applied
+     *     (URL does not contain 'staging', even if the original session was recorded on a staging environment), and
+     *     so the request may not be able to be matched correctly.
+     *
+     *  3. Enough unique information must still be preserved in the redacted network request to allow Meticulous
+     *     to correctly match a request that is performed at replay time by your application with
+     *     the correct corresponding saved request stored in the recording / recorded session.
+     *
+     *     For example: if you replace all query string values with "[REDACTED]", and there are multiple distinct
+     *     requests with identical paths but different query string values then Meticulous will not have enough
+     *     information to match them correctly. However if instead you md5 hash all query string values then
+     *     Meticulous would have enough information to match the requests correctly.
+     *
+     *  4. Returning null will cause the request and the corresponding response to be dropped from the payload.
+     *     At replay time if there is no exact match for a request that is transformed to null then the request
+     *     will be failed with 'net::ERR_FAILED'/'Failed to fetch' rather than automatically trying to find a
+     *     'closest match' in the recorded session.
      *
      * See JSDoc for {@link RecorderMiddleware} before implementing.
      */
     transformNetworkRequest?: (request: Omit<HarRequest, "queryString">, metadata: NetworkRequestMetadata) => Omit<HarRequest, "queryString"> | null;
     /**
-     * Transforms network requests before they are sent to Meticulous's servers.
+     * Transforms network responses before they are sent to Meticulous's servers.
      *
-     * Returning null will cause the request and the response to be dropped from the payload.
-     * If the request/response is dropped from the payload but at replay time your application still makes
-     * the request then Meticulous will look for another closely matching recorded request, and replay that,
-     * or if none can be found it will fail the request with 'net::ERR_FAILED'/'Failed to fetch'.
+     * If you wish to drop a network response entirely please implement transformNetworkRequest
+     * instead and return null for the corresponding request.
      *
      * See JSDoc for {@link RecorderMiddleware} before implementing.
      */
-    transformNetworkResponse?: (response: HarResponse, metadata: NetworkResponseMetadata) => HarResponse | null;
+    transformNetworkResponse?: (response: HarResponse, metadata: NetworkResponseMetadata) => HarResponse;
     /**
      * Transforms WebSocket messages before they are sent to Meticulous's servers.
      *
@@ -107,6 +116,13 @@ export interface RecorderMiddleware {
      * See JSDoc for {@link RecorderMiddleware} before implementing.
      */
     transformWebSocketConnectionData?: (entry: Omit<WebSocketConnectionData, "id">) => Omit<WebSocketConnectionData, "id"> | null;
+    /**
+     * Defaults to true. Set to false if transformNetworkRequest only transforms the headers and not the URL or body of the request,
+     * and transformNetworkRequest never returns null. Setting to false when not required improves replay performance.
+     *
+     * See {@link transformNetworkRequest} for more details.
+     */
+    applyRequestTransformationAtReplayTime?: boolean;
 }
 export interface IndexedDBStoreEntries {
     databaseName: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alwaysmeticulous/sdk-bundles-api",
-  "version": "2.163.0",
+  "version": "2.165.0",
   "description": "Meticulous common types",
   "license": "ISC",
   "main": "dist/index.js",
@@ -19,7 +19,7 @@
     "depcheck": "depcheck --ignore-patterns=dist"
   },
   "devDependencies": {
-    "@alwaysmeticulous/api": "^2.163.0"
+    "@alwaysmeticulous/api": "^2.164.0"
   },
   "peerDependencies": {
     "loglevel": "^1.8.0"
@@ -46,5 +46,5 @@
   "bugs": {
     "url": "https://github.com/alwaysmeticulous/meticulous-sdk/issues"
   },
-  "gitHead": "3433132494bcd861f837662603d25556521dbeac"
+  "gitHead": "fb42f552b9ae0d56218c531977db13fb14e94205"
 }